# Allow domain access
Source: https://developer.box.com/guides/api-calls/allowing-domain-access



To use the Box APIs it is important that your application and users have access
to the following domains, where needed.

## File preview

To enable file preview, your application might need to load javascript file from
the Box content delivery network (CDN). This file is loaded from the following
domains.

* `api.box.com`
* `boxcdn.net`
* `boxcloud.com`
* `dl2.boxcloud.com` to `dl20.boxcloud.com`

## File downloads

The following API domains are used to download files via the Box API.

* `api.box.com` to initially request a file to download
* `dl.boxcloud.com` to actually download files for authenticated users
* `public.boxcloud.com` to actually download files for unauthenticated users

<Warning>
  Ensuring access to these domains is only a first step to downloading a file.
  To download a file the users need to have proper access permissions and need
  to be fully authenticated where needed.
</Warning>

## File uploads

The following API domains are used to upload files via the Box API.

* `api.box.com` to start a file upload
* `upload.app.box.com` and `upload.box.com` to upload the file to Box

<RelatedLinks title="RELATED APIS" />


# API versioning strategy
Source: https://developer.box.com/guides/api-calls/api-versioning-strategy



Box provides versioning capabilities for selected API endpoints. The version control system guarantees seamless functioning of existing endpoint versions, even if Box introduces new ones.

API versioning empowers Box to continually enhance its platform, while also offering third-party developers a reliable avenue for feature updates and deprecations.

<Tip>
  To stay informed about the forthcoming API modifications, monitor the <Link href="/changelog">Changelog</Link> and maintain a current email address in the Developer Console's App Info section.
</Tip>

<Note>
  In 2024, Box introduced year-based API versioning.

  All endpoints available at the end of 2024 were assigned the version `2024.0`.

  **No action is required for API users to continue using Box APIs.**

  To make version-aware API calls, include the `box-version` header with the value `2024.0` in your requests.
</Note>

## How Box API versioning works

<Note>
  Box API supports versioning in `header`. To determine which version to use, look at the API reference and included sample requests.
</Note>

### Versioning in `header`

Box API processes the `box-version` header which should contain a valid version name. For example, when a client wants
to get a list of all sign requests using version `2025.0`, the request should look like this:

```sh theme={null}
curl --location 'https://api.box.com/2.0/sign_requests' \
     --header 'box-version: 2025.0' \
     --header 'Authorization: Bearer …
```

If the provided version is correct and supported by the endpoint, a response is sent to the client.
If the endpoint is available in multiple versions, the response will include the `box-version` header,
which indicates the version used to handle the request.
Endpoints introduced after 2024 may return a `400` error code if the version is incorrect.
More information about versioning errors can be found <Link href="/guides/api-calls/permissions-and-errors/versioning-errors">here</Link>.

If your request doesn't include a version, the API defaults to the initial Box API version - `2024.0` - the version of endpoints available before
year-based versioning was introduced. However, relying on this behavior is not recommended when adopting deprecated
changes. To ensure consistency, always specify the API version, with each request. By making your application
version-aware, you anchor it to a specific set of features, ensuring consistent behavior throughout the supported
timeframe.

## Release schedule and naming convention

Box can introduce a new breaking change to certain endpoints **once per year**, which results in a new API version.
Introducing a new version of the Sign Request endpoint means that **all paths and HTTP methods** of an endpoint will support it.

For example, if Sign Request endpoints receive a new version it will apply to all endpoints listed in the table:

| Method | Request URL | Description |
| - | - | - |
| GET | `https://api.box.com/2.0/sign_requests/:id` | Retrieves specific sign request details. |
| GET | `https://api.box.com/2.0/sign_requests/` | Retrieves all sign requests. |
| POST | `https://api.box.com/2.0/sign_requests/` | Creates new sign requests. |
| POST | `https://api.box.com/2.0/sign_requests/:id/resend` | Sends a specific sign request again. |
| POST | `https://api.box.com/2.0/sign_requests/:id/cancel` | Cancels a specific sign request. |

### Naming convention

New API versions are labeled according to the calendar year of their release.

**Example**: If a new version of the Sign Requests endpoint is released in 2025, it will be named `2025.0`.

Box can issue a new breaking change to API endpoints **once** per year, reserving the right to release an additional breaking change to address security or privacy concerns. In such cases, the new version will be incremented by one in the suffix.

**Example**: If security issues need addressing in the previously released version `2025.0` of Sign Requests, the new version will be labeled `2025.1`.

Each stable version is supported for a minimum of 12 months. This means that when a new version is released, the previous version becomes deprecated and will be available for use, but no new features will be added.
It also means that a new version cannot be released sooner than every 12 months.

We strongly recommend updating your apps to make requests to the latest stable API version. However, if your app uses a stable version that is no longer supported, then you will get a response with an HTTP error code `400 - Bad Request`. For details, see <Link href="/guides/api-calls/permissions-and-errors/versioning-errors">Versioning Errors</Link>.

### Endpoint versioning indication

To keep you informed about the current API state, and improve the readability of the versioned API reference, the affected endpoints are marked with a pill based on the `x-stability-level` tag or `deprecated` attribute.

<Frame>
  <img alt="An example of a beta pill used for API reference endpoints" />
</Frame>

| Schema element | Pill name | Description |
| - | - | - |
| `x-stability-level: beta` | Beta | Endpoints marked with **beta**, are offered subject to Box’s Main Beta Agreement, meaning the available capabilities may change at any time. When the beta endpoint becomes stable, the **beta** indication is removed. |
| `x-stability-level: stable` or no `x-stability-level` tag | Latest version | **Latest version** marks the most recent stable API version of an endpoint. |
| `deprecated: true` | Deprecated | An endpoint is deprecated, which means it is still available for use, but no new features are added. Such an endpoint is annotated with the `deprecated` attribute set to `true`. |

## Versioning errors

When using versioned API actions such as calling an incorrect API version in header or a deprecated version can lead to errors.

For details on possible errors, see <Link href="/guides/api-calls/permissions-and-errors/versioning-errors">versioning errors</Link>.

## How Box SDK versioning works

The versioning strategy applies only to [generated SDKs](/sdks-and-tools/#next-generation-sdks).

Box SDKs support the **All Versions In** SDK approach.
This means that every release of SDK provides access to all endpoints in any version which is currently live. All generated SDKs use manager's approach - they group all endpoints with the same domain in one manager.

For example `FolderManager` contains methods to: `create_folder`, `get_folder_by_id`, `update_folder_by_id`, `delete_folder_by_id`, `get_folder_items` and `copy_folder`. This division is done based on the value of `x-box-tag` field, which is assigned to each method in Public API Service specification. It mostly corresponds to the root of the endpoint URL, but not necessarily. For example: `FolderManager` contains methods with `https://api.box.com/2.0/folders` root URL, but the same base URL is also used in some methods of `SharedLinkFoldersManager`.
References to all managers are stored under one Box Client object.

See an example of the endpoint's lifecycle:

1. Initial state (only one version is available).

   ```js theme={null}
   class FilesManager {
       async updateFileById(
           fileId: string,
           requestBody: UpdateFileByIdRequestBody,
           queryParams: UpdateFileByIdQueryParams,
           headers: UpdateFileByIdHeaders
       ): Promise < FileFull > {}
   }
   ```

2. A new `v2025_0` version of the endpoint is introduced (previous version is deprecated).

   The SDK introduces a new method for each new version of an endpoint. These methods are stored in the same manager as the old ones, but their names and corresponding classes are suffixed with the version number. The old method is deprecated with a notice indicating the minimal maintenance date – this will be the date when the endpoint will be considered for end-of-life status.

   ```js theme={null}
   class FilesManager {
       /**
        * @deprecated This endpoint will be EOL'ed after 05-2026.
           */
       async updateFileById(
           fileId: string,
           requestBody: UpdateFileByIdRequestBody,
           queryParams: UpdateFileByIdQueryParams,
           headers: UpdateFileByIdHeaders
       ): Promise<FileFull> {}

       async updateFileById_2025_0(
           fileId: string,
           requestBody: UpdateFileByIdRequestBody_2025_0,
           queryParams: UpdateFileByIdQueryParams_2025_0,
           headers: UpdateFileByIdHeaders_2025_0
       ): Promise<FileFull_2025_0> {}
   }
   ```

3. The API endpoint is marked as End-of-Life (EOL)

   The SDK releases a breaking change release with removed end-of-life (EOL) endpoints. Ideally, we should group the end-of-life dates for all endpoints into one date per quarter to avoid releasing numerous new major versions of SDKs.

   ```js theme={null}
   class FilesManager {
       async updateFileById_2025_0(
           fileId: string,
           requestBody: UpdateFileByIdRequestBody_2025_0,
           queryParams: UpdateFileByIdQueryParams_2025_0,
           headers: UpdateFileByIdHeaders_2025_0
       ): Promise < FileFull_2025_0 > {}
   }
   ```

## Breaking vs non-breaking changes

Breaking changes in the Box API occur within versioned releases, typically accompanied by a new major API version. Minor adjustments, which do not disrupt existing functionality, can be integrated into an existing API version. The following table lists both breaking and non-breaking changes.

| API Change | Breaking change |
| - | - |
| New endpoints | No |
| New [read-only](https://swagger.io/docs/specification/data-models/data-types/) or optional fields in request | No |
| New required fields in request | Yes |
| New string constant in request | Yes |
| Deprecation | No |
| Retired / End-of-Life endpoints | Yes |
| Rename/reshape of a field, data type, or string constant | Yes |
| More restrictive change to field validations | Yes |
| Less restrictive change to field validations | No |
| Changing HTTP status code returned by an operation | Yes |
| Removing a declared property | Yes |
| Removing or renaming APIs or API parameters | Yes |
| Adding a required request header | Yes |
| Adding more error codes | No |
| Removing or modifying error codes | Yes |
| Adding a member to an enumeration | Yes |

<Tip>
  The [oasdiff](https://github.com/Tufin/oasdiff) tool allows detecting most of the possible breaking changes.
</Tip>

## Forward compatibility of API responses

Box may add new, optional, or read-only fields to API responses at any time without a version bump. These changes are considered non-breaking and require no advance notification.

Client applications must be implemented to tolerate additional JSON fields and ignore fields they do not recognize. Strict response schema validation or deserialization that rejects unknown fields is discouraged, as it may cause integrations to break when Box introduces new fields.

To ensure long-term stability:

* Integrate only the documented fields your application explicitly requires
* Do not assume API responses will exactly match a fixed schema
* Configure JSON parsing libraries to ignore unmapped or unexpected properties

## AI agent configuration versioning

<Link href="/guides/box-ai/ai-agents">AI agent</Link> versioning gives the developers more control over model version management and ensures consistent responses. For details, see <Link href="/guides/box-ai/ai-agents/ai-agent-versioning">AI agent configuration versioning guide</Link>.

## Support policy and deprecation information

When new versions of the Box APIs and Box SDKs are released, earlier versions will be retired. Box marks a version as `deprecated` at least 24 months before retiring it. In other words, a deprecated version cannot become end-of-life
sooner than after 24 months.
Similarly, for individual APIs that are generally available (GA), Box declares an API as `deprecated` at least 24 months in advance of removing it from the GA version.

When we increment the major version of the API (for example, from `2025.0` to `2026.0`), we're announcing that the current version (in this example, `2025.0`) is immediately deprecated and we'll no longer support it 24 months after the announcement. We might make exceptions to this policy for service security or health reliability issues.

When an API is marked as deprecated, we strongly recommend that you migrate to the latest version as soon as possible. In some cases, we'll announce that new applications will have to start using the new APIs a short time after the original APIs are deprecated.

When customer calls deprecated API endpoint, the response will contain a header:

```sh theme={null}
Deprecation: date="Fri, 11 Nov 2026 23:59:59 GMT"
Box-API-Deprecated-Reason: /reference/deprecated
```

The date tells clients when this version was marked as deprecated.

## Versioning considerations

When building your request, consider the following:

* Endpoints in version `2024.0` can be called without specifying the version in the `box-version` header. If no version is specified and the `2024.0` version of the called endpoint does not exist, the response will return an HTTP error code `400 - Bad Request`.
* If the `box-version` version header is specified but the requested version does not exist, the response will return an HTTP error code `400 - Bad Request`.

For details, see <Link href="/guides/api-calls/permissions-and-errors/versioning-errors">versioning errors</Link>.

When Box deprecates a resource or a property of a resource in the API, the change is communicated in one or more of the following ways:

* Calls that include the deprecated behavior return the response header `Box-API-Deprecated-Reason` and a link to get more information:

  ```sh theme={null}
  box-version: 2025.0
  Deprecation: version="version", date="date"
  Box-API-Deprecated-Reason: /reference/deprecated
  ```

* A deprecation announcement is posted in the developer changelog.

* The API reference is updated to identify the affected resource and any action you need to take. Affected endpoints are marked with **deprecated** pill.

* If there is an imminent backwards-incompatible change that affects your app, then the contact email for your app might be contacted about the deprecation.

## Additional resources

* <Link href="/reference">API reference</Link>


# Ensure consistency with headers
Source: https://developer.box.com/guides/api-calls/ensure-consistency



Some Box APIs support headers used to ensure consistency between your
application and Box.

## `etag`, `if-match`, and `if-none-match`

Many of the file system items (files or folders) that can be requested via the
API return an `etag` value for the item.

For example, a file resource returns an `etag` in the JSON response.

```sh theme={null}
curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
{
  "id": 12345,
  "etag": 1,
  "type": "file",
  "sequence_id": 3,
  "name": "Contract.pdf",
  ...
}
```

This `etag` can be used as the value of an `if-match` or `if-none-match`
header to either ensure a resource hasn't changed since the `etag` value was
received, or to prevent unnecessary downloads for items that haven't changed.

For example, to fetch the same file only if it has changed, pass in the `etag`
value in an `if-none-match` header.

```sh theme={null}
curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN" \
    -H "if-none-match: 1"
```

This API call would result in an empty response if the file had not changed.

## Ensure consistent changes

The `if-match` header allows your application to ensure that no changes are
made to items when another application or a user has made changes to the item
since your application last inspected it. This helps ensure that
changes aren't lost when two applications or users are changing items at the
same time.

The following endpoints support this header.

| `if-match` capable endpoints | |
| - | - |
| <Link href="/reference/post-files-id-content">`POST /files/:id/content`</Link> | Upload a new file version |
| <Link href="/reference/put-files-id">`PUT /files/:id`</Link> | Update a file's information |
| <Link href="/reference/delete-files-id">`DELETE /files/:id`</Link> | Delete a file |
| <Link href="/reference/put-folders-id">`PUT /folders/:id`</Link> | Update a folder's information |
| <Link href="/reference/delete-folders-id">`DELETE /folders/:id`</Link> | Delete a folder |
| <Link href="/reference/put-web-links-id">`PUT /web_links/:id`</Link> | Update a web link's information |
| <Link href="/reference/delete-web-links-id">`DELETE /web_links/:id`</Link> | Delete a web link |

The response of these API calls depends on the existence of the item,
and whether the `etag` value matches the most recent version.

| Item found? | Etag match? | HTTP status |
| - | - | - |
| Yes | Yes | 200 |
| Yes | No | 412 |
| No | Yes | 412 |
| No | No | 404 |

<Warning>
  **Moving items**

  The `if-match` header cannot be used to prevent moving of files, folders,
  or web links. Instead, Box always ensures that the latest item is moved to
  the new location.
</Warning>

## Prevent unnecessary request downloads

The `if-none-match` header allows your application to ensure that no information
is downloaded for items that have not changed since your application last
inspected it. This helps ensure no unnecessary information is downloaded,
speeding up your application and saving on bandwidth.

| `if-none-match` capable endpoints | |
| - | - |
| <Link href="/reference/get-files-id">`GET /files/:id`</Link> | Get a file's information |
| <Link href="/reference/get-folders-id">`GET /folders/:id`</Link> | Get a folder's information |
| <Link href="/reference/get-web-links-id">`GET /web_links/:id`</Link> | Get a web link's information |
| <Link href="/reference/get-shared-items">`GET /shared_items`</Link> | Get a shared item's information |

The response of these API calls depends on the existence of the item,
and whether the `etag` value matches the most recent version.

| Item found? | Etag match? | HTTP Status |
| - | - | - |
| Yes | Yes | 304 |
| Yes | No | 200 |
| No | Yes | 404 |
| No | No | 404 |

<RelatedLinks title="RELATED APIS" />


# API Calls
Source: https://developer.box.com/guides/api-calls/index

Learn how to make calls to the Box REST API, including authentication headers, common patterns, and platform insights.

The Box API is a restful API that follows common HTTP standards
where possible. The following guides take a look at some of the useful
features and common mistakes that a developer can encounter when working with
these APIs.

## Quick example

Every API call requires an access token in the `Authorization` header. This example retrieves the current user's profile:

```bash theme={null}
curl https://api.box.com/2.0/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

## API calls insights

Admins and co-admins can access the Platform Insights
dashboard that provides information on the total number
of API calls per application.

See [Platform Insights][insights] and <Link href="/guides/applications">applications</Link> for details.

[insights]: https://support.box.com/hc/en-us/articles/20738406915219-Platform-Insights


# Language codes
Source: https://developer.box.com/guides/api-calls/language-codes



The Box API uses a modified version of the **ISO 639-1 Language Code** to specify a user's language.

The following is a list of language codes used when <Link href="/reference/post-users#param-language">creating</Link> or <Link href="/reference/put-users-id#param-language">updating</Link>.

| Language | Code |
| - | - |
| Bengali | `bn` |
| Danish | `da` |
| German | `de` |
| English (US) | `en` |
| English (UK) | `gb` |
| English (Canada) | `e2` |
| English (Australia) | `e3` |
| Spanish (Latin America) | `s2` |
| Spanish | `es` |
| Finnish | `fi` |
| French | `fr` |
| French (Canada) | `f2` |
| Hindi | `hi` |
| Italian | `it` |
| Japanese | `ja` |
| Korean | `ko` |
| Norwegian (Bokmal) | `nb` |
| Dutch | `nl` |
| Polish | `pl` |
| Portuguese | `pt` |
| Russian | `ru` |
| Swedish | `sv` |
| Turkish | `tr` |
| Chinese (Simplified) | `zh` |
| Chinese (Traditional) | `zt` |


# Pagination overview
Source: https://developer.box.com/guides/api-calls/pagination/index



The Box API supports two ways to paginate collections. The most common way to
paginate is through offset-based pagination which is often used where the list
of items is of a fixed, predetermined length.

In some cases an API endpoint supports marker-based pagination, either as an
alternative to offset-based pagination or as a full replacement. Marker-based
pagination is often used in cases where the length of the total set of items is
either changing frequently, or where the total length might not be known
upfront.


# Marker-based Pagination
Source: https://developer.box.com/guides/api-calls/pagination/marker-based



APIs that use marker-based paging use the `marker` and `limit` query parameters
to paginate through items in a collection.

Marker-based pagination is often used in cases where the length of the total set
of items is either changing frequently, or where the total length might not be
known upfront.

## Paging

To fetch the first page of entries in a collection the API needs to be called
either without the `marker` parameter, or with the `marker` set to `0`. The
`limit` parameter is optional.

```sh theme={null}
curl https://api.box.com/2.0/folders/0/items?limit=100&usemarker=true&marker= \
    -H "authorization: Bearer ACCESS_TOKEN"
```

<Note>
  APIs that support both offset-based pagination and marker-based pagination
  require the `usemarker` query parameter to be set to `true` to ensure
  marker-based pagination is used.
</Note>

To fetch the next page of entries the API needs to be called with
a `marker` parameter that equals the value of the `next_marker` value that was
received in the API response.

```sh theme={null}
curl https://api.box.com/2.0/folders/0/items?marker=34332423&limit=100&usemarker=true \
    -H "authorization: Bearer ACCESS_TOKEN"
```

The final page of items has been requested when the next `next_marker` value is
`null` in the response object. At this point there are no more items to fetch.

<Note>
  With marker-based paging there is no way to determine the total number of
  entries in a collection except by fetching them all. Applications should not
  retain the `next_marker` value long-term as the internal implementation of the
  markers may change over time.
</Note>

## Marker & Limit

The following query parameters are used to paginate a collection.

| Query parameter | Type | Default | |
| - | - | - | - |
| `marker` | String | | The first position in the collection to return results from. This should be a value that was returned in a previous request. |
| `limit` | Integer | Depends on API | The maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used. |
| `usemarker` | Boolean | | An optional query parameter that can be used with API endpoints that support both types of pagination to select pagination type. Set to `true` to enforce marker-based pagination. |

## Collections

When paginating collections, the API returns an object that contains the set of
results as an array, as well as some information about the current page of results.

| Field | Type | |
| - | - | - |
| `entries` | Array | The page of items for this page. This will be an empty array if there are no results. |
| `next_marker` | String | The value that can be used as the `marker` value to fetch the next page of results. If this value is `null` or an empty string there are no more results to fetch. |
| `limit` | Integer | The limit used for this page of results. This will be the same as the `limit` query parameter unless it exceeded the maximum value allowed for this API endpoint. |

## Example endpoints

Some endpoints that support marker-based pagination are:

* <Link href="/reference/get-folders-id-items">List items for a folder</Link>
* <Link href="/reference/get-files-id-collaborations">List a file's collaborations</Link>
* <Link href="/reference/get-webhooks">List all webhooks for a user</Link>
* <Link href="/reference/get-users">List all users in an enterprise</Link>
* <Link href="/reference/get-folders-trash-items">List all items in the trash</Link>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box API offset-based pagination
Source: https://developer.box.com/guides/api-calls/pagination/offset-based

Page Box API collections with `offset` and `limit`. This includes limits of offset-based pagination, and when to use marker-based paging instead.

APIs that use offset-based paging use the `offset` and `limit` query parameters
to paginate through items in a collection.

Offset-based pagination is often used where the list of items is of a fixed and
predetermined length.

## Paging

To fetch the first page of entries in a collection the API needs to be called
either without the `offset` parameter, or with the `offset` set to `0`. The
`limit` field is optional.

```sh theme={null}
curl https://api.box.com/2.0/folders/0/items?offset=0&limit=100 \
    -H "authorization: Bearer ACCESS_TOKEN"
```

To fetch the next page of entries the API needs to be called with
an `offset` parameter that equals the sum of the previous `offset` value and
limit returned in the previous result, `previous_offset + previous_limit`.

```sh theme={null}
curl https://api.box.com/2.0/folders/0/items?offset=100&limit=100 \
    -H "authorization: Bearer ACCESS_TOKEN"
```

<Note>
  Note that the `offset` should be increased by the previous `limit` and not by
  the size of the entries in the response array, as this may be less than the
  limit. Generally we advise using the value of the `limit` in the response
  object to increase the `offset` value.
</Note>

The final page of items has been requested when the next `offset` value exceeds
the `total_count` value in the response object. At this point there are no more
items to fetch.

## Offset & Limit

The following query parameters are used to paginate a collection.

| Query parameter | Type | Default | |
| - | - | - | - |
| `offset` | Integer | `0` | The (zero-based) offset of the first item returned in the collection. In a zero-based offset `0` is a correct value. |
| `limit` | Integer | Depends on API | The maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used. |

<Note>
  The maximum `offset` for offset-based pagination is `9999`. Marker-based
  pagination is recommended when a higher offset is needed.
</Note>

## Collections

When paginating collections, the API returns an object that contains the set of
results as an array, as well as some information about the current page of results.

| Field | Type | |
| - | - | - |
| `entries` | Array | The page of items for this page. This will be an empty array if there are no results. |
| `offset` | Integer | The offset used for this page of results |
| `limit` | Integer | The limit used for this page of results. This will be the same as the `limit` query parameter unless it exceeded the maximum value allowed for this API endpoint. |
| `total_count` | Integer | One greater than the offset of the last item in the entire collection. The total number of items in the collection may be less than `total_count`. |

## Example endpoints

Some endpoints that support offset-based pagination are:

* <Link href="/reference/get-folders-id-items">List items for a folder</Link>
* <Link href="/reference/get-files-id-comments">List a file's comments</Link>
* <Link href="/reference/get-folders-trash-items">List all items in the trash</Link>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box API errors
Source: https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors

Look up Box API HTTP errors, JSON error responses, and common 4xx and 5xx codes when a request fails.

The Box API uses [HTTP status codes][status-codes] to communicate whether a
request was processed successfully.

<SignupCTA>
  Working through API errors? A free developer account gives you access to the Developer Console, where you can test API calls and debug with your own applications.
</SignupCTA>

## Client error

Most client errors in the HTTP 4XX range, and some server errors in the HTTP 5XX
range, return a standard client error JSON object.

```json theme={null}
{
  "type": "error",
  "status": 400,
  "code": "bad_digest",
  "help_url": "/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "The specified content-md5 did not match what we received",
  "request_id": "abcdef123456"
}
```

See the <Link href="/reference/resources/client-error">Client Error resource</Link> for more details.

## Common error codes

Check our [Developer Troubleshooting Articles][articles]
for solutions to common errors encountered when working with the Box APIs.

### 400 Bad Request

| | |
| - | - |
| **Error** | `bad_digest` |
| **Message** | The specified `content-md5` did not match what we received. |
| **Solution** | While uploading a file, a `content-md5` header with the SHA-1 hash of the file can be supplied to ensure that the file is not corrupted in transit. The SHA-1 hash that was supplied in the request did not match what was received in the upload. Supply a valid SHA-1 hash of the uploaded file. |

| | |
| - | - |
| **Error** | `bad_request` |
| **Message** | |
| **Solution** | Required parameters supplied in the API request are either missing or invalid. Check the extended error message in the response body for more details. |

| | |
| - | - |
| **Error** | `cannot_make_collaborated_subfolder_private` |
| **Message** | Cannot move a collaborated subfolder to a private folder unless `owned_by.id` matches the requestor’s user ID. |
| **Solution** | Set the `owned_by.id` field to the user ID of the API requestor when moving a collaborated subfolder into a private folder. |

| | |
| - | - |
| **Error** | `collaborations_not_available_on_root_folder` |
| **Message** | Root folder cannot be collaborated |
| **Solution** | You cannot set collaborators on a user's root folder (folder ID 0). Use a different folder ID than the root folder. |

| | |
| - | - |
| **Error** | `cyclical_folder_structure` |
| **Message** | Folder move creates cyclical folder structure |
| **Solution** | The folder ID specified in the folder move would create a cyclical folder structure (for example moving a folder to a subfolder within itself). Change the folder ID for the folder move request. |

| | |
| - | - |
| **Error** | `folder_not_empty` |
| **Message** | Cannot delete – folder not empty |
| **Solution** | Delete all content from the folder before attempting to delete it. |
| | |
| **Error** | `invalid_collaboration_item` |
| **Message** | Item type must be specified and set to 'folder' |
| **Solution** | Set the `item.type` field of the collaboration item to `folder`. |

| | |
| - | - |
| **Error** | `invalid_client` |
| **Message** | The client credentials are invalid. |
| **Solution** | Verify the `client_id` and `client_secret` in the token request match the values in the Developer Console. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Verify the authorization code is set correctly in your request, or your application likely needs to get a new authorization code. |
| **Solution** | The authorization code supplied in the API request is missing or no longer valid. Possible solutions are to verify that the access token is added correctly in the request. If correctly set, the access token might have expired. Attempt to refresh the access token or fetch a new one. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Current date time must be before the expiration date time listed in the `exp` claim. |
| **Solution** | This error occurs when the Unix time on your local machine and the Box server are out of sync. To fix this error, update the Unix time on your machine to match a synchronized time server, then try the request again. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Invalid refresh token. |
| **Solution** | The refresh token might be invalid, revoked, or expired. Correct your application's refresh token handling and obtain a new token pair through the OAuth 2.0 authorization flow if needed. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | The authorization code has expired. |
| **Solution** | Authorization codes expire shortly after they are issued (on the order of tens of seconds). Exchange the code for tokens immediately after the user is redirected back to your application. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Please check the `sub` claim. |
| **Solution** | For JWT authentication, set the `sub` (subject) claim to the correct user ID or enterprise ID depending on `box_sub_type`. More information is available on our [support site](https://support.box.com/hc/en-us/articles/360043691734). |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Please check the `jti` claim. A unique `jti` value is required. |
| **Solution** | Ensure the JWT ID (`jti`) is set to a valid, unique value for each assertion. The same `jti` cannot be reused. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Please check the `iss` claim. |
| **Solution** | The issuer (`iss`) claim must match the OAuth client ID for your application when using JWT authentication. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Signature verification error. The public key identified by `kid` must correspond to the private key used for signing. |
| **Solution** | Use the public/private keypair associated with your app in the Developer Console. If you rotate keys, add the new key, remove the old one, update your configuration file with the new keypair and `kid`, then request a new access token. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | `kid` invalid, unable to lookup correct key. |
| **Solution** | The key ID (`kid`) in the JWT header must match a public key registered for the application (for example, the `publicKeyID` in your configuration). Confirm you are using the correct configuration file, or generate a new RSA keypair in the Developer Console and update your app to use it. |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | App is not yet authorized for use. |
| **Solution** | The server authentication app (JWT or Client Credentials Grant) has not been authorized for use in your enterprise. Check the authorization status in the right-side panel on the app's **Configuration** tab. See [Platform app approval](/guides/authorization/platform-app-approval). |

| | |
| - | - |
| **Error** | `invalid_grant` |
| **Message** | Cannot obtain user token based on the enterprise configuration for your app. |
| **Solution** | You are requesting a user token (for example, CCG with `box_subject_type=user`, or the `as-user` header) but the app is not configured to issue one. On the app's **Configuration** tab, enable **Generate User Access Tokens** under **Advanced Features**, set **App Access Level** to **App + Enterprise Access** if you are authenticating as a Managed User or Admin, then have an admin re-authorize the app. See [Client Credentials Grant](/guides/authentication/client-credentials). |

| | |
| - | - |
| **Error** | `invalid_limit` |
| **Message** | Limit is not a valid number |
| **Solution** | Add a valid numeric value for the supplied limit value. |
| | |
| **Error** | `invalid_offset` |
| **Message** | Offset is not a valid number |
| **Solution** | Add a valid numeric value for the supplied offset value. |
| | |
| **Error** | `invalid_request` |
| **Message** | The grant type is unauthorized for this client\_id. |
| **Solution** | You might be requesting a token using standard OAuth 2.0 while the app is configured for Server Authentication (JWT), or the other way around. Use the token request type that matches your app's authentication method. See [The grant type is unauthorized for this client\_id](https://support.box.com/hc/en-us/articles/360044193033-API-Authentication-The-grant-type-is-unauthorized-for-this-client-id). |

| | |
| - | - |
| **Error** | `invalid_request` |
| **Message** | Invalid `grant_type` parameter or parameter missing. |
| **Solution** | You might be sending token requests to the wrong domain (such as `app.box.com` or `www.box.com`). Send token requests to `https://api.box.com`. Use the `grant_type` and other parameters required for your flow (`authorization_code`, `refresh_token`, [JWT assertion](/reference/post-oauth2-token#body-grant-type), and so on). |

| | |
| - | - |
| **Error** | `invalid_request` |
| **Message** | Cannot obtain user token based on the enterprise configuration for your app. |
| **Solution** | Your app might be missing a scope or configuration needed to request a user token. See [Cannot Obtain Token Based on Enterprise Configuration for Your App](https://support.box.com/hc/en-us/articles/360044192553). |

| | |
| - | - |
| **Error** | `invalid_request_parameters` |
| **Message** | Invalid input parameters in request |
| **Solution** | Invalid parameters were sent in the API request. Check the API reference documentation for the correct request parameters that should be supplied for the API operation. |

| | |
| - | - |
| **Error** | `invalid_status` |
| **Message** | You can change the status only if the collaboration is pending |
| **Solution** | The status of a collaboration can only be updated to accepted or rejected by the user specified in the `accessible_by` field when the current status is set to pending. |

| | |
| - | - |
| **Error** | `invalid_upload_session_id` |
| **Message** | The upload session ID provided in the URL is not of a valid format. |
| **Solution** | The session ID supplied when making a chunked upload API request was invalid. Use the same session ID from the session that was created. |

| | | |
| - | - | - |
| **Error** | `item_name_invalid` | |
| **Message** | Item name invalid | |
| **Solution** | Verify that the file's name is valid. Box only supports file or folder names that are 255 characters or less. File names containing non-printable characters, names containing the characters `/`, `\`, `<`, `>`, `:`, \` | `, `?`, `\*`, `-\`, names with leading or trailing spaces, and the special names "." and ".." are also unsupported. |

| | |
| - | - |
| **Error** | `item_name_too_long` |
| **Message** | Item name too long |
| **Solution** | Shorten the length of the name that is being supplied for the item. The maximum length of a file or folder name in Box is 255 characters or less. |

| | |
| - | - |
| **Error** | `metadata_after_file_contents` |
| **Message** | Metadata is included after file contents in a file upload request. |
| **Solution** | Include the file metadata before the file's contents. |
| | |
| **Error** | `password_reset_required` |
| **Message** | User needs to reset password |
| **Solution** | The user has not yet completed account [setup steps](https://support.box.com/hc/en-us/articles/360043691614). |
| | |
| **Error** | `requested_page_out_of_range` |
| **Message** | Requested representation page out of range |
| **Solution** | The range header supplied does not fit within the size of the specified item. Adjust the bounds to fit within the size of the item and try again. |

| | |
| - | - |
| **Error** | `requested_preview_unavailable` |
| **Message** | Requested preview unavailable |
| **Solution** | The thumbnail size requested for the file is not valid. See the reference docs for the API operation for available format sizes. |

| | |
| - | - |
| **Error** | `sync_item_move_failure` |
| **Message** | Cannot move a synced item |
| **Solution** | The item is set to be synced by the Box sync clients and cannot be moved. A possible solution is to set the `sync_state` of the item to `not_synced`. |

| | |
| - | - |
| **Error** | `task_assignee_not_allowed` |
| **Message** | Assigner does not have sufficient privileges to assign task to assignee |
| **Solution** | The user who is attempting to assign the task does not have the appropriate permissions to do so. Adjust the user permissions to allow the assignment of tasks. |

| | |
| - | - |
| **Error** | `terms_of_service_required` |
| **Message** | User must accept custom terms of service before action can be taken |
| **Solution** | The user in context for the API request has not accepted the enterprise's custom Terms of Service. For login-capable managed users, acceptance is required before most API calls, user access token issuance, or OAuth authorization can proceed. Service accounts and App Users are exempt. If you are using server authentication with the `As-User` header or a user access token, the impersonated or token subject user must have accepted. The user can accept via the Box web application, or your application can accept programmatically using the <Link href="/guides/security/terms-of-service/flow">Terms of Service application flow</Link>. For more information, see [Using custom Terms of Service](https://support.box.com/hc/en-us/articles/360044192733-Using-Custom-Terms-Of-Service). |

| | |
| - | - |
| **Error** | `unauthorized_client` |
| **Message** | This app is not authorized by the enterprise admin. |
| **Solution** | Server authentication applications using JWT or Client Credentials Grant must be authorized by a Box Admin before use. Follow the steps in <Link href="/guides/authorization/platform-app-approval">Platform app approval</Link>. |

| | |
| - | - |
| **Error** | `user_already_collaborator` |
| **Message** | User is already a collaborator |
| **Solution** | The user you are trying to add as a collaborator is already a collaborator on that item. You don't need to send this request. |

### 401 Unauthorized

| | |
| - | - |
| **Error** | `unauthorized` |
| **Message** | Unauthorized |
| **Solution** | Authorization token is not authorized, check extended error message in body for more details. |

| | |
| - | - |
| **Error** | `invalid_token` |
| **Message** | The access token provided is invalid. |
| **Solution** | The access token might be incorrect, corrupted, or expired – for example, because of a typo, using a token from another environment, or revocation or deletion. Obtain a new access token from the token endpoint. For OAuth 2.0 authentication, you can refresh an expired access token. See <Link href="/guides/authentication/tokens/refresh">Refresh a token</Link>. |

### 403 Forbidden

| | |
| - | - |
| **Error** | `access_denied_insufficient_permissions` |
| **Message** | Access denied – insufficient permission |
| **Solution** | The access token does not have the appropriate user permissions or scopes. For solutions, see [403 access denied insufficient permissions errors](https://support.box.com/hc/en-us/articles/360043693434-API-Content-API-403-access-denied-insufficient-permissions-Errors). |

| | |
| - | - |
| **Error** | `insufficient_scope` |
| **Message** | The request requires higher privileges than provided by the access token. |
| **Solution** | This error is typically produced when scopes that are needed for the API operation are not enabled. Check your configured application scopes and reauthorize your application, if applicable. |

| | |
| - | - |
| **Error** | `access_denied_item_locked` |
| **Message** | Access denied – item locked |
| **Solution** | You are attempting to access a locked item without appropriate permissions to access it. Unlock the item first, then try to access it again. |

| | |
| - | - |
| **Error** | `access_from_location_blocked` |
| **Message** | |
| **Solution** | You're attempting to log in to Box from a location that has not been approved by your admin. Talk to your admin to resolve this issue. |

| | |
| - | - |
| **Error** | `file_size_limit_exceeded` |
| **Message** | File size exceeds the folder owner’s file size limit |
| **Solution** | For limits based on account type, see [Understand the maximum file size you can upload](https://support.box.com/hc/en-us/articles/360043697314-Understand-the-Maximum-File-Size-You-Can-Upload-to-Box). |
| | |
| **Error** | `forbidden` |
| **Message** | |
| **Solution** | Client does not have permission to upload to this session. Only the user who initiated the upload session may upload to it. |

| | |
| - | - |
| **Error** | `forbidden_by_policy` |
| **Message** | Access denied – Blocked by Shield Access Policy |
| **Solution** | Shield access policies applied on your enterprise have prevented this action. Contact your enterprise admin to adjust the applied Shield access policies. |

| | |
| - | - |
| **Error** | `forbidden_by_policy` |
| **Message** | Access denied – Blocked by Shield Malware Detection Rule |
| **Solution** | An active Shield malware detection rule prevents download or local editing of potentially malicious content, but preview and online editing remain available. Contact your enterprise admin to adjust the applied Shield policies. |

| | |
| - | - |
| **Error** | `incorrect_shared_item_password` |
| **Message** | |
| **Solution** | A password is required for the shared item, but it was either incorrect or not supplied. |

| | |
| - | - |
| **Error** | `storage_limit_exceeded` |
| **Message** | Account storage limit reached |
| **Solution** | The storage limit of the account has been reached. Either [upgrade](https://support.box.com/hc/en-us/articles/360043692774-Upgrading-your-Box-Account) your account or permanently delete content to continue. Content moved to the trash still counts towards the account total until it is permanently deleted. |

| | |
| - | - |
| **Error** | `user_email_confirmation_required` |
| **Message** | User needs to complete email confirmation |
| **Solution** | The user has not yet completed [steps](https://support.box.com/hc/en-us/articles/360043691614) for email confirmation. |
| | |
| **Error** | `cors_origin_not_whitelisted` |
| **Message** | Access denied - Did you forget to safelist your origin in the CORS configuration of your app? |
| **Solution** | Your application tried to access the Box API from a website. The application needs to <Link href="/guides/security/cors/#enabling-cors-for-your-domain">explicitly allow Cross Origin Resource Sharing</Link> for the domain your site is hosted on. |

### 404 Not Found

| | |
| - | - |
| **Error** | `not_found` |
| **Message** | |
| **Solution** | The resource could not be found. Check the extended error message in the response body for more details. |

| | |
| - | - |
| **Error** | `not_trashed` |
| **Message** | Item is not trashed |
| **Solution** | The item that is to be permanently deleted is not in the trash. Send the item to the trash first. |

| | |
| - | - |
| **Error** | `preview_cannot_be_generated` |
| **Message** | Preview cannot be generated |
| **Solution** | You are not able to generate a preview thumbnail for the specified file. |
| | |
| **Error** | `trashed` |
| **Message** | Item is trashed |
| **Solution** | The item that is to be accessed is in the trash and unavailable for modification. Move the item out of the trash and try again. |

### 405 Method Not Allowed

| | |
| - | - |
| **Error** | `method_not_allowed` |
| **Message** | Method Not Allowed |
| **Solution** | The HTTP method used for the API operation is not allowed. Check the API reference documentation for the HTTP verb needed for the API operation. |

### 409 Conflict

| | |
| - | - |
| **Error** | `conflict` |
| **Message** | A resource with this value already exists |
| **Solution** | This error can occur when the resource to be created already exists. Check the extended error message in the response body for more details. |

| | |
| - | - |
| **Error** | `item_name_in_use` |
| **Message** | Item with the same name already exists |
| **Solution** | This error is produced when a resource with the same name already exists. Ensure that the resource name being added or modified is unique. |

| | |
| - | - |
| **Error** | `name_temporarily_reserved` |
| **Message** | The item name is reserved by another processing item. Wait 60 seconds and then retry the request, or wait and check the parent folder to see if the name is in use. |
| **Solution** | Two duplicate requests have been submitted at the same time. Box acknowledges the first and reserves the name, but a second duplicate request arrives before the first request has completed. The name can stay reserved for up to 60 seconds. Wait at least 60 seconds before retrying. If the first request completed, a later retry can return `item_name_in_use` instead. |

| | |
| - | - |
| **Error** | `operation_blocked_temporary` |
| **Message** | The operation is blocked by another ongoing operation |
| **Solution** | This error is returned when trying to access a folder that is blocked by another folder operation, such as a move or copy. Try again at a later interval. |

| | |
| - | - |
| **Error** | `recent_similar_comment` |
| **Message** | A similar comment has been made recently |
| **Solution** | A similar comment was recently made, and the API has flagged it as a potential duplicate. Verify that the comment was indeed made, or modify the comment content and try again. |

| | |
| - | - |
| **Error** | `user_login_already_used` |
| **Message** | User with the specified login already exists |
| **Solution** | A user with the same email already exists. Either refer to the existing user or specify a different email. |

### 410 Gone

| | |
| - | - |
| **Error** | `session_expired` |
| **Message** | |
| **Solution** | The upload session associated with the given upload session ID has expired and can no longer be accessed. |

| | |
| - | - |
| **Error** | `upload_failed` |
| **Message** | |
| **Solution** | The upload session is in an unrecoverable state and cannot continue. This or other requests have resulted in the upload session reaching a bad state (for example parts overlapping). Possible situations where this can occur include when the maximum number of parts has been exceeded or when overlapping parts have been uploaded. |

### 411 Length Required

| | |
| - | - |
| **Error** | `length_required` |
| **Message** | content-length header was required, but not provided. |
| **Solution** | Supply a content-length header within your API request. |

### 412 Precondition Failed

| | |
| - | - |
| **Error** | `precondition_failed` |
| **Message** | The resource has been modified. Retrieve the resource again and retry |
| **Solution** | Check the extended error message in the response body for more details. |

| | |
| - | - |
| **Error** | `sync_state_precondition_failed` |
| **Message** | The resource has been modified. Retrieve the resource again and retry |
| **Solution** | Check the extended error message in the response body for more details. |

### 413 Request Entity Too Large

| | |
| - | - |
| **Error** | `request_entity_too_large` |
| **Message** | Request Entity too Large |
| **Solution** | This error is produced when the size of the upload is more than the allowed maximum. Check the extended error message in the response body. |

### 415 Unsupported Media Type

| | |
| - | - |
| **Error** | `unsupported_media_type` |
| **Message** | Previews for `boxnote` files are not yet supported. |
| **Solution** | This error is produced when requesting an embed preview of a Box Note. Embedded previews are currently unsupported for Box Notes. |

### 429 Too Many Requests

| | |
| - | - |
| **Error** | `rate_limit_exceeded` |
| **Message** | Request rate limit exceeded, try again later. |
| **Solution** | The client is performing operations too quickly and has been rate limited. Client is advised to retry their request after the amount of time specified by the `retry-after` header. There are <Link href="/guides/api-calls/permissions-and-errors/rate-limits">four rate limits</Link> to be aware of. |

| | |
| - | - |
| **Error** | `rate_limit_exceeded` |
| **Message** | Your enterprise has reached its monthly AI unit quota. Try another agent, contact your admin to purchase additional units, or wait for the quota to reset. |
| **Solution** | Box AI endpoints return this error when your enterprise has used all of its AI Units. The response has no `retry-after` header, and retrying doesn't succeed until the quota resets or your admin purchases more AI Units. Box SDKs retry `429` responses automatically, so check the `message` or `help_url` to tell this error apart from a rate limit and stop retrying. See <Link href="https://docs.box.com/en/box-ai/understanding-ai-units-in-box">Understanding Box AI usage</Link>. |

### 500 Internal Server Error

| | |
| - | - |
| **Error** | `internal_server_error` |
| **Message** | Internal Server Error |
| **Solution** | Client should retry using [exponential back-off strategy](https://en.wikipedia.org/wiki/Exponential_backoff) |

### 502 Bad Gateway

| | |
| - | - |
| **Error** | `bad_gateway` |
| **Message** | |
| **Solution** | Client should retry using [exponential back-off strategy](https://en.wikipedia.org/wiki/Exponential_backoff) |

### 503 Unavailable

| | |
| - | - |
| **Error** | `unavailable` |
| **Message** | Unavailable |
| **Solution** | If a Retry-After header is provided in the response, the client should retry the request according to the header value. In rare situations, a write operation might eventually persist its changes after the 503 response is received by the client, so the client should handle this case upon retry. If the issue persists, check our [Status Site](https://status.box.com/) for any known outage information. |

[status-codes]: http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

[articles]: https://support.box.com/hc/en-us/sections/360007552913-Troubleshooting-Box-Platform


# Token & URL Expiration
Source: https://developer.box.com/guides/api-calls/permissions-and-errors/expiration



Across the Box API there are a few tokens, codes, and URLs that automatically
expire. The following is a quick overview of their respective expiration times.

| | |
| - | - |
| [Authorization Codes] | Expires after 30 seconds |
| [Access Tokens] | Expires after 60 minutes |
| [Refresh Tokens] | Expires after 60 days or 1 use |
| [Download URLs] | Expires after 15 minutes |

See each respective guide for more details.

[Authorization Codes]: /guides/authentication/oauth2

[Access Tokens]: /guides/authentication/tokens

[Refresh Tokens]: /guides/authentication/tokens/refresh

[Download URLs]: /guides/downloads


# Box API rate limits
Source: https://developer.box.com/guides/api-calls/permissions-and-errors/rate-limits

Understand Box API rate limits, 429 responses, and how to retry requests without exceeding per-user and enterprise quotas.

There are three common types of API call rate limitations that Box may use at
its discretion to best protect network resources and preserve the quality of our
customer experience.

<SignupCTA>
  A free developer account lets you start making API calls and test your integration's rate limit handling with real requests.
</SignupCTA>

## User based

These rate limits protect our service from issues that may arise when a single
user generates too much traffic. The number of API calls that a user can make in
a minute is limited as described below. These limits apply to all Box user
accounts and are the most common. Generally, they are initiated when a
user exceeds approximately 1000 API calls/minute, but certain API endpoints may
have different rate limits.

## Quality of service

These rate limits are designed to protect the quality of service of our
infrastructure. If there is resource contention in the infrastructure, we
introduce automatic rate limits to prevent system degradation and outages.
For instance, if an application happens to be accessing the same physical
database server, such as the use of a file migration tool accessing related
resources that access the same underlying physical resources, Box may impose
temporary rate-limits when load spikes and adjust them as the system recovers.

## Licensing based

All Box Business Plans come with a licensed number of permitted API calls per
enterprise per month. These license based rate limits are designed to prevent
excessive overages and misuse of network resources. If Box's infrastructure
detects that a tool used by or on behalf of a customer has exceeded that
customer's API license allocation or is intending to circumvent network
controls, additional selective rate-limiting may be imposed. You can see the
default API allocations licensed with a particular account level at our
[pricing page][pricing], but note that some customers purchase Platform API
Pricing plans that increase their allocation.

## Monitor and reduce API usage

Calls from custom applications, scripts, and integrations count toward your
enterprise's monthly allocation, including authentication requests. Calls from
Box partner integrations and native Box applications don't. For the full
definition, see the
<Link href="https://docs.box.com/en/box-admin-tools/reporting-and-insights/platform-activity-report">Platform Activity report</Link>.

To find which applications drive your usage, an admin can review the
<Link href="https://docs.box.com/en/box-admin-tools/reporting-and-insights/platform-insights">Platform Insights</Link>
dashboard or run a Platform Activity report. The report lists API calls per
application and whether they are chargeable.

To reduce the number of API calls your application makes:

* Cache access tokens and reuse them until they expire. See <Link href="/guides/authentication/best-practices">authentication best practices</Link>.
* Request only the fields you need with the `fields` query parameter. See <Link href="/guides/api-calls/request-extra-fields">request extra fields</Link>.
* Use <Link href="/guides/webhooks">webhooks</Link> or the <Link href="/guides/events">event stream</Link> instead of polling for changes.
* Use <Link href="/guides/api-calls/pagination/marker-based">marker-based pagination</Link> with a higher `limit` to retrieve large lists in fewer requests.
* Use <Link href="/guides/search/quick-start/metadata-query-api">metadata queries</Link> to find content by metadata instead of reading metadata file by file.

<Note>
  Box AI API calls consume AI Units, which are tracked separately from API
  calls. See <Link href="https://docs.box.com/en/box-ai/understanding-ai-units-in-box">Understanding Box AI usage</Link>.
</Note>

## Per API rate limits

There are currently a few distinct rate limits in place within the Box API.

* General API calls
  * 1000 API requests per minute, per user
* Uploads
  * 240 file upload requests per minute, per user
* Search
  * 6 searches per second, per user, to the <Link href="/reference/get-search">search endpoint</Link>
  * Two additional limits are applied on top of the basic rate limit
    * 60 searches per minute, per user
    * 12 searches per second, per enterprise
* Box Sign
  * Create and resend sign request: 100 requests per minute, per user
  * Get sign request: 1000 requests per minute, per user

## Rate limit error

When an application hits a rate limit, the API will return an API response with
an HTTP status code of `429 Too Many Requests`.

The response will include the following headers and JSON body.

```yaml theme={null}
retry-after: 100
```

```json theme={null}
{
  "type": "error",
  "status": 429,
  "code": "rate_limit_exceeded",
  "help_url": "/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "Request rate limit exceeded, please try again later",
  "request_id": "abcdef123456"
}
```

Please see the <Link href="/reference/resources/client-error">Client Error resource</Link> for more details.

<Note>
  The `retry-after` header provides guidance on the number of seconds to wait
  before the next API call can be retried. In general, we advise using an
  exponential back-off strategy for retrying API calls.
</Note>

## SDK retry behavior

Box's current SDKs automatically retry requests that return `429 Too Many Requests`. The retry uses an exponential back-off strategy and honors the `retry-after` header returned by the API, so you don't need to implement your own retry loop for rate-limit errors when using these SDKs. See <Link href="/guides/tooling/sdks">Box SDKs</Link> for the list of supported languages and versions.

If you use an older Box SDK version, a community SDK, or call the API directly (for example, with `curl`, Postman, or your own HTTP client), you are responsible for retrying `429` responses yourself. Wait for the number of seconds indicated by the `retry-after` header before your first retry, then apply exponential back-off if the request continues to fail.

[pricing]: https://www.box.com/pricing

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box API scopes
Source: https://developer.box.com/guides/api-calls/permissions-and-errors/scopes

Configure Box application scopes in the Developer Console so your app can call only the API endpoints it needs.

When an application is created in the Developer Console, the user must configure
application scopes. Similar to how users have permissions to access files and
folders within Box, applications have their own set of permissions to
perform certain actions on behalf of a Box user or a Box enterprise. The name
for a set of permissions for an application is a "scope". In short, an
application's scopes determine which <Link href="/reference">endpoints</Link> an application can
successfully call and are reflected in the access provided by
<Link href="/guides/authentication/tokens">Access Tokens</Link> of the application.

## User permissions and scopes

Box API scopes are the permissions you assign to an application in the Developer Console. A call succeeds only when both the app's scopes and the authenticated user's permissions allow the action.

It is important to understand that even if an application has the right scopes
to perform an action, the user associated with the Access Token making the call
needs to have permission to perform the action as well and vice versa.

For example, if your application is set up to read files, the
authenticated user does need to have permission to read the file you are
trying to access.

To learn more about how scopes, token permissions, and user permissions work
together, see our <Link href="/guides/security">security guide</Link>.

<SignupCTA>
  A free developer account gives you access to the Developer Console, where you can configure application scopes and start making API calls.
</SignupCTA>

## Scopes & OAuth 2 authorization

When sending a user through a client-side OAuth 2 flow to authorize your
application it is possible to append a set of scopes to the authorization URL to
further restrict the user's access token.

For example, if your application has the `root_readonly` and `root_readwrite`
scopes enabled, it is possible to restrict a user's access token to
`root_readonly` by specifying this scope when redirecting the user.

```js theme={null}
GET https://account.box.com/api/oauth2/authorize?scope=root_readonly&client_id=....
```

When the scope parameter is omitted the application will use the scopes that
were set when the application was created.

## Self-service scopes

These scopes are available through the Developer Console when configuring an
application. Navigate to the **Application Scopes** section of the
**Configuration** tab and select one or more of the following scopes.

### Read all files and folders

| | |
| - | - |
| **OAuth Scope** | `root_readonly` |
| **Application Scope** | Read all files and folders stored in Box. |

Gives an application the ability to read all the files/folders for the
authenticated user. Access to content is further restricted by the users' permission and Access Token used.

Although this gives an application the permission to read files and folders, the
user making the API call does need to have access to the items being accessed.

In the case of a <Link href="/guides/authentication/jwt">JWT</Link> application accessing a <Link href="/guides/getting-started/users#managed-users">Managed User's</Link>
items, the Service Account's Token will need to either use the `as-user`
<Link href="/guides/authentication/jwt/as-user">header</Link> or create a <Link href="/guides/authentication/jwt/user-access-tokens">User Access Token</Link> to directly authenticate as
the user who has access to the content.

### Read and write all files and folders

| | |
| - | - |
| **OAuth Scope** | `root_readwrite` |
| **Application Scope** | Read and write all files and folders stored in Box |

Gives an application write access for the authenticated user. This allows the
application to upload files or new file versions, download content, create new
folders, update or delete collaborations, create comments or tasks, and more.
Necessary to download files and folders. Access to content is further restricted by the users' permission and Access Token used.

Although this gives an application read/write access to items, the
user making the API call needs to have access to the content.

### Manage users

The manage users scope in the Developer Console maps to two OAuth scopes.

| | |
| - | - |
| **OAuth Scope** | `manage_managed_users` |
| **Application Scope** | Manage users |

Gives an application permission to manage <Link href="/guides/getting-started/users#managed-users">Managed Users</Link>. It
allows the app to change the user's primary login, reset their password, and
change roles for managed users.

<Note>
  Although this allows an application to manage users, for client-side applications,
  the Access Token used must be associated with an Admin or Co-Admin with the
  correct permissions.

  Additionally, for JWT applications, the application must be configured with
  **App Access + Enterprise Access** <Link href="/guides/authentication/jwt/jwt-setup/#application-access">application access</Link>.
</Note>

| | |
| - | - |
| **OAuth Scope** | `manage_app_users` |
| **Application Scope** | Manage users |

Gives an application permission to manage <Link href="/guides/getting-started/users#app-user">App Users</Link>, which means this
scope only applies to server-side authenticated (JWT) applications.

### Manage groups

| | |
| - | - |
| **OAuth Scope** | `manage_groups` |
| **Application Scope** | Manage groups |

Gives an application permission to manage an enterprise's groups. It
allows the app to create, update, and delete groups, as well as manage group
membership.

<Note>
  Although this allows an application to manage groups, for client-side applications,
  the Access Token used must be associated with an Admin or Co-Admin with the
  correct permissions.

  For JWT applications, groups the app creates itself can be managed with
  **App Access Only**. To manage groups that were not created by the app itself,
  the application must be configured with **App Access + Enterprise Access**
  <Link href="/guides/authentication/jwt/jwt-setup/#application-access">application access</Link>.
</Note>

### Manage webhooks

| | |
| - | - |
| **OAuth Scope** | `manage_webhook` |
| **Application Scope** | Manage webhooks |

Gives an application permission to create webhooks for a user.
Please review webhook <Link href="/guides/webhooks/v2/limitations-v2">limitations</Link>. Most
notably, there is a limit of 1000 webhooks per application, per user.

### Manage enterprise properties

| | |
| - | - |
| **OAuth Scope** | `manage_enterprise_properties` |
| **Application Scope** | Manage enterprise properties |

Gives an application permission to view the enterprise event stream, as well as
view and edit the enterprise's attributes and reports. It also allows the
application to edit and delete device pins.

<Note>
  Although this allows an application to manage enterprise properties, for client-side
  applications, the Access Token used must be associated with an
  Admin or Co-Admin with the correct permissions. For example, to update a Shield
  list with the <Link href="/reference/v2025.0/put-shield-lists-id">Update shield list</Link>
  endpoint, associate the Access Token with the primary admin, or with a co-admin who can
  manage Shield configurations.
</Note>

### Manage retention policies

| | |
| - | - |
| **OAuth Scope** | `manage_data_retention` |
| **Application Scope** | Manage retention policies |
| **Depends on** | `enterprise_content`-scope |

Gives an application permission to view and create retention policies
with Box Governance. This requires the enterprise to have purchased
[Box Governance][governance].

<Warning>
  This scope also requires the `enterprise_content` scope to function properly.
  These scopes can be requested by opening a ticket via our support channels.
</Warning>

### Manage signature requests

| | |
| - | - |
| **OAuth Scope** | `sign_requests.readwrite` |
| **Application Scope** | Manage signature requests |

Gives an application permission to get, create, cancel, and resend sign
requests.

This scope requires the application to also have read/write scopes, which are
automatically selected when enabled. In addition, an enterprise must have Sign
enabled.

### Manage Box AI API

| | |
| - | - |
| **OAuth Scope** | `ai.readwrite` |
| **Application Scope** | Manage AI |

Gives an application permission to send requests to
Box AI API.

### Manage Box Relay

| | |
| - | - |
| **OAuth Scope** | `manage_triggers` |
| **Application Scope** | Manage Box Relay |

Gives an application permission to interact with Box Relay endpoints and start flows of type `WORKFLOW_MANUAL_START`.

This scope requires the application to also have read/write scopes.

## Available on request

There are some additional scopes that are only available upon request. To do so,
please submit a ticket to our [support team](/support). They will review
these requests on an individual basis and only provide approval if the use case
requires the scope.

<Note>
  It is not possible to request extra scopes if your account is a free trial
  account. Before filing a support request for activation of the following
  scopes, log in to your paid enterprise account or
  [upgrade your free developer account][pricing] to an enterprise account tier.
</Note>

### Manage Legal Holds

| | |
| - | - |
| **OAuth Scope** | `manage_legal_holds` |
| **Depends on** | `enterprise_content`-scope |

Gives an application permission to create, view, edit, and delete legal hold
policies and their assignments, apply policies to content, and manage file version retentions.
For use with the Governance add-on.

<Note>
  This scope depends on the `enterprise_content` scope to function properly.
  This scope can be requested by opening a ticket via our support channels.
</Note>

### Suppress email notifications

| | |
| - | - |
| **Application Scope** | Can suppress email notifications from API calls |

Allows some types of <Link href="/guides/api-calls/suppress-notifications">email notifications</Link> to be suppressed when API
calls are made.

### Global Content Manager (GCM)

| | |
| - | - |
| **OAuth Scope** | `enterprise_content` |
| **Application Scope** | Global Content Manager |

Allows Admins, [Co-Admins][ca], and <Link href="/guides/getting-started/users#service-account">Service Accounts</Link> to retrieve any content
they do not own or are not collaborators on within their enterprise, based on
their enterprise settings.

This scope is required to manage the retention policies and legal holds.

<Danger>
  **Side effects**

  Enabling this scope on an application changes the behavior of some API calls,
  and most notably, makes it impossible to write content without explicitly
  authenticating as a user using the `as-user` header. Additionally, enabling this
  scope disables accessing content that is owned by users in another enterprise.

  For this reason, this scope will not be provisioned unless absolutely necessary.
</Danger>

## Scopes for downscoping

In some cases an Access Token needs to be <Link href="/guides/authentication/tokens/downscope">downscoped</Link> to a more strict
permission level, especially when a token needs to be exposed to a client-side,
public environment like a browser. The primary example for this is when using
[Box UI Elements][ui-elements], which require an Access Token in the user's
browser.

The following is a list of **additional** scopes that can be used with the
<Link href="/reference/post-oauth2-token">`POST /oauth2/token`</Link> endpoint to downscope an
existing access token.

| OAuth Scope | UI Element affected | Description |
| - | - | - |
| `annotation_edit` | Preview | Create, edit, and delete annotations on a specific file, and view your own annotations on it. |
| `annotation_view_all` | Preview | View annotations from all users on a specific file. |
| `annotation_view_self` | Preview | View only the authenticated user's own annotations on a specific file. |
| `base_explorer` | Explorer | Access content in the folder tree based on user/file/token permissions. |
| `base_picker` | Picker | Access content in the folder tree based on user/file/token permissions. |
| `base_preview` | Preview | Preview the file only. |
| `base_sidebar` | Sidebar | Get basic file info needed for the sidebar UI element. |
| `base_upload` | Uploader | Upload into the folder specified under `resource` when downscoping the token. |
| `item_delete` | Explorer | Delete files, folders, and file versions, including permanently deleting items from trash. Applies only to the item the downscoped token was created for. |
| `item_download` | Explorer, Preview | Download files or a folder's content. |
| `item_preview` | Explorer | Preview a file. |
| `item_rename` | Explorer | Rename files and folders. |
| `item_share` | Explorer, Picker | Share the item specified under `resource` of the token exchange. |
| `item_upload` | Picker | Upload in the content picker. |

The standard OAuth scopes are also supported when downscoping.

| OAuth Scope | Description |
| - | - |
| `ai.readwrite` | Send requests to Box AI API. |
| `manage_managed_users` | Create, view, edit, and delete managed users, including changing a user's login, resetting their password, and assigning co-admin permissions. Also grants management of any managed user's content in the enterprise. |
| `manage_app_users` | Create, view, edit, and delete app users, which are accounts created and owned by your application. For use with server-side authentication. Also grants the ability to activate and deactivate users, and the enterprise-wide user-listing permissions required to enumerate app users. |
| `manage_data_retention` | Create, view, edit, and delete retention policies and their assignments, and remove file version retentions. For use with the Governance add-on. |
| `manage_enterprise` | Broad administrative access to enterprise settings, user administration, admin event logs, group tags, and device pins. Grants a complete superset of both Manage users and Manage groups, plus co-admin permission assignment, content management for any user, terms of service management, and sandbox management. |
| `manage_enterprise_properties` | Manage enterprise-level settings other than users and groups: enterprise attributes, admin event logs, device pins, enterprise feature settings (view and edit), terms of service, and the collaboration domain allowlist. Also grants view access to SSO settings and app authorizations, and the ability to manage sandboxes, manage platform apps, create automation users, create enterprise authorizations, and sign agreements. Requires App + Enterprise Access. |
| `manage_groups` | Create, view, edit, and delete groups, manage group membership, and invite groups to collaborate. |
| `manage_webhook` | Create, view, edit, and delete webhooks, and send notifications when content changes. Limited to 1000 webhooks per application, per user. |
| `sign_requests.readwrite` | Interact with Box Sign endpoints. |

[console]: https://app.box.com/developers/console

[ui-elements]: https://github.com/box/box-ui-elements

[pricing]: https://www.box.com/pricing/platform

[governance]: https://www.box.com/security/governance-and-compliance

[ca]: https://support.box.com/hc/en-us/articles/1500005433721-Users-Groups-Settings#h_01GSE1DYJKTY9EXEWJEDKFHCNV


# Versioning errors
Source: https://developer.box.com/guides/api-calls/permissions-and-errors/versioning-errors



Box provides versioning capabilities for selected API endpoints. The version control system guarantees seamless functioning of existing endpoint versions, even if Box introduces new ones.

API versioning empowers Box to continually enhance its platform, while also offering third-party developers a reliable avenue for feature updates and deprecations.

To stay informed about the API modifications, monitor the [Changelog](/changelog) and maintain a current email address in the **App Info** section of the Developer Console.

## Error examples

When using versioned API calls, you can encounter versioning-related errors. This reference lists the most common cases when errors appear and provides you with examples of such errors.

## Calling with incorrect `box-version` header

If you call an API using an incorrect `box-version` header, the API will respond with an `HTTP error code 400 - Bad Request` error and provide the supported versions in the response message.

The response will include one of the following status messages in `message` field:

| Details | Message |
| - | - |
| `box-version` value is an unsupported API version or was sent malformed. | `Invalid API version specified in 'box-version' header.` |
| The request headers did not include `box-version` header when versioned only endpoint was called. | `Missing required box-version header.` |
| `box-version` is empty. | `Invalid (empty) API version specified in 'box-version' header.` |
| `box-version` contained multiple versions. It requires **only one** version per request. | `The 'box-version' header supports only one header value per request, do not use comas.` |
| An unsupported API version is used for an existing endpoint. | `Unsupported API version specified in 'box-version' header.` |

An example of a response with an incorrect `box-version` header:

```json theme={null}
{
  "type": "error",
  "status": 400,
  "code": "invalid_api_version",
  "help_url": "/reference/error-codes/invalid-api-version",
  "message": "Invalid API version specified in 'box-version' header. Supported API versions: [2024.0].",
  "request_id": "abcdef123456"
}
```

## Calling an incorrect API version in the URL

Box documentation specifies API URLs. For instance, the Sign Requests endpoints are accessed via: `https://api.box.com/2.0/sign_requests/`. If you mistakenly make a call to an incorrect version, such as `https://api.box.com/3.0/sign_requests/`, the response returns an `HTTP error code 404 - Not Found` error.

## Calling a deprecated API

When you use an API version that Box has marked as deprecated, the API will respond as usual. Additionally, it will append a `Deprecation` header, stating the deprecation date. For example:

```sh theme={null}
Deprecation: date="Fri, 11 Nov 2026 23:59:59 GMT"
Box-API-Deprecated-Reason: /reference/deprecated
```

You should monitor API responses to verify if the `Deprecation` header is present to accordingly plan the transition to a new API version.

## Calling a non-existent version

If you attempt to use an outdated API version, such as `2025.0` which has reached its end-of-life, the response will return an `HTTP error code 404 - Not Found`. See [Calling an incorrect API version in the URL](#calling-an-incorrect-api-version-in-the-url) for more information.


# Request extra fields
Source: https://developer.box.com/guides/api-calls/request-extra-fields

Learn about standard, mini, and full resource variants in the Box API, and how to use the fields query parameter to request additional fields.

The number of fields returned for a resource depends on the API endpoint used
to request the resource.

## Use the `fields` query parameter

To request a specific field for a resource that is not returned by default in
the standard response, append the `fields` query parameter to your request. The
value of this parameter is a comma separated list of field names.

```sh theme={null}
curl https://api.box.com/2.0/files/12345?fields=is_package,lock \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
{
  "etag": "1",
  "id": "12345",
  "is_package": false,
  "lock": null,
  "type": "file"
}
```

<Note>
  It is important to note that when a specific field is requested no other
  fields are returned except for those requested and the **base** set of fields.
  For a file, this base set is comprised of the `etag`, `id`, and `type` values.
</Note>

## Resource variants

The following resource variants are available in the Box API.

### Standard

The default set of fields returned in an API response.
The standard variant is returned when requesting a resource
through the main APIs available for that resource. For example, when requesting
the <Link href="/reference/get-files-id">`GET /files/:id`</Link> endpoint the API will return
the standard variation of a file.

```sh theme={null}
curl https://api.box.com/2.0/files/12345 \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
{
    "content_created_at": "2019-06-20T06:04:41-07:00",
    "content_modified_at": "2019-06-20T06:04:41-07:00",
    "created_at": "2019-06-20T07:28:42-07:00",
    "created_by": {
        "id": "191919191",
        "login": "joe@example.com",
        "name": "Joe Box",
        "type": "user"
    },
    "description": "",
    "etag": "1",
    "file_version": {
        "id": "56663434454334",
        "sha1": "585afa5209bbd586c79499b7336601341ad06cce",
        "type": "file_version"
    },
    "id": "12345",
    ...
    "size": 65000647,
    "trashed_at": null,
    "type": "file"
}
```

### Mini

Where a resource is returned as a nested part of another response it is often
reduced in size, only returning some of the more essential fields. This variant
is commonly known as the mini resource variant.

For example, when requesting the
<Link href="/reference/get-folders-id-items">`GET /folders/:id/items`</Link> endpoint the API
will return a mini variation of files and folders nested within the `item_collection`.

```sh theme={null}
curl https://api.box.com/2.0/folders/12345/items \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
{
  "id": "0",
  "type": "folder",
  "item_collection": {
    "entries": [
      {
        "etag": "1",
        "file_version": {
          "id": "56663434454334",
          "sha1": "585afa5209bbd586c79499b7336601341ad06cce",
          "type": "file_version"
        },
        "id": "12345",
        "name": "Video.mp4",
        "sequence_id": "1",
        "sha1": "585afa5209bbd586c79499b7336601341ad06cce",
        "type": "file"
      }
      ...
    ]
    ...
  }
  ...
}
```

<Note>
  To request more information for a nested resource we recommend calling the
  API for that resource to request it by ID, and optionally pass along the
  `fields` query parameter.

  For example, to get the owner of a file returned when listing the items in a
  folder, request that file by ID with the query parameter `fields=owned_by`.
</Note>

### Full

The total set of fields that can be returned in an API response. The full variant is returned when requesting a resource
through the main APIs available for that resource and by appending the `fields`
query parameter.

For example, when requesting the <Link href="/reference/get-files-id">`GET /files/:id`</Link>
endpoint with the `fields=is_package,lock` parameter the API will return the fields specified plus the basic fields for the file.

```sh theme={null}
curl https://api.box.com/2.0/files/12345?fields=is_package,lock \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
{
  "etag": "1",
  "id": "12345",
  "is_package": false,
  "lock": null,
  "type": "file"
}
```

<RelatedLinks title="RELATED APIS" />


# Sorting responses
Source: https://developer.box.com/guides/api-calls/sorting



Where an API returns a collection of items it often supports sorting of API
responses.

Use the `sort` and `direction` query parameters to sort the collection either in
ascending or descending order.

```sh theme={null}
curl https://api.box.com/2.0/folders/0/items?sort=size&direction=DESC \
    -H "authorization: Bearer ACCESS_TOKEN"
```

<Warning>
  Not all API endpoints that return collections have support for sorting.
  Especially endpoints that use marker-based pagination often lack support for
  sorting the results.
</Warning>

## Sorting criteria

The field to sort on is defined by the `sort` query parameter. Check the API
endpoint's documentation for the possible options for this value.

<Note>
  In some APIs the `sort` field is the second criteria by which the items are
  sorted. For example for the <Link href="/reference/get-folders-id-items">`GET /folders/:id/items`</Link>
  endpoint the results are always sorted by their type first before any other
  criteria.
</Note>

## Sorting direction

The sorting direction supports two values, either `ASC` for ascending order, or
`DESC` for the reverse.

<RelatedLinks title="RELATED APIS" />


# Status codes
Source: https://developer.box.com/guides/api-calls/status-codes



The following rules can be applied to interpret the HTTP status
codes received when using the Box API.

| HTTP Status | |
| - | - |
| `200-299` | Box received, understood, and accepted the API request. The request has either completed or is in the process of being completed. |
| `300-399` | Box received, understood, and accepted the API request, yet the client must take further action in order to complete the request. Often this includes redirect to other URLs. |
| `400-499` | A client error occurred when handling the request, often because the client either did not provide the right parameters, did not have access to the resources, or tried to perform an action that is otherwise not possible. |
| `500-599` | Box received and accepted the request, but an error occurred within Box while handling it. These errors signify a problem with Box, not a problem with the client's request |

<RelatedLinks title="RELATED GUIDES" />


# Suppress notifications
Source: https://developer.box.com/guides/api-calls/suppress-notifications



For some API calls, you can block email and webhook notifications by
including a `box-notifications: off` header with the API call.

```sh cURL theme={null}
curl -X POST https://api.box.com/2.0/folders \
    -H "box-notifications: off" \
    -H "authorization: Bearer ACCESS_TOKEN" \
    -d '{
      "name": "New Folder",
      "parent": {
        "id": "0"
      }
    }'
```

As an example, this can be used for a virus-scanning tool to download copies of
every user's files in an enterprise without every collaborator on the file
receiving an email informing them of the download.

All actions will still appear in users' updates feed and the audit-logs.

<Warning>
  **Scope requirement**

  Notification suppression is available for approved applications only. Contact
  support to request the required scopes to be enabled for your application.

  The following settings need to be configured for your application for this feature
  to properly work.

  * **Can suppress email notifications from API calls** - available on request via support
  * **Manage Enterprise Properties** - available via the developer console
  * Co-admin permissions of **Edit settings for your company**.
</Warning>

<Note>
  Some notifications can not be suppressed, most notably the creation of users,
  comments, collaborations, task assignments, and when changing a user's login.
</Note>


# Types and formats
Source: https://developer.box.com/guides/api-calls/types-and-formats



The following sections explain some basic concepts about the types and formats
that can be encountered within the Box APIs.

## Requests

The Box APIs use JSON in the request bodies. There are a few notable exceptions
to this rule:

* The <Link href="/reference/post-oauth2-token">`POST /oauth2/token`</Link> is used to request access tokens and as per the OAuth 2.0 specification it accepts the body to be sent with a content type of `application/x-www-form-urlencoded`.
* Most of the APIs that are used to upload binary data, like the <Link href="/reference/post-files-content">`POST /files/content`</Link> endpoint, expect data to be sent as form data with a content type of `multipart/form-data`.

<Note>
  Although not required, we highly recommend passing a header with each API
  request to define the content type of the data sent, for example
  `content-type: application/json`.
</Note>

### Headers

As per the HTTP specification, all request header names in the Box API are
case-insensitive and can be provided in lowercase, uppercase, or any mixed case
form. In other words, the content type header can be set as
`CONTENT-TYPE: application/json`, `content-type: application/json`,
`content-type: application/json` or even the slightly absurd
`cOnTeNt-TyPe: application/json`.

Header values **are** mostly case sensitive unless stated otherwise.

### GZip compression

By default data sent from Box is not compressed. To improve bandwidth and
response times it's possible to compress the API responses by including
an `Accept-Encoding: gzip, deflate` request header.

### Date and times

The Box APIs support [RFC 3339][rfc3339] timestamps. The preferred way to format
a date in a request is to convert the time to UTC, for example `2013-04-17T09:12:36-00:00`.

In those cases where timestamps are rounded to a given day, the time component
can be omitted. In this case, `2013-04-17T13:35:01+00:00` would become
`2013-04-17`. In those cases where timestamps support millisecond precision the expected
request format should be as follows `2013-04-17T09:12:36.123-00:00`.

The timezone can differ between different files and folders because an
enterprise's timezone can change over time. A common example is daylight saving
time. Items created during standard time would have a different timezone than
items created during daylight saving time. For this reason it's important to use
an `RFC3339`-compliant date-time parser to handle dates returned by the API.

Timestamps are restricted to dates after the start of the Unix epoch, `00:00:00
UTC` on January 1, 1970.

## Responses

The Box APIs generally return JSON in the response body. There are a few notable
exceptions to this rule as well.

* APIs that delete items return an empty body with a `204 No Content` HTTP status code.
* APIs used to request binary data either return a `200 OK` status code with the binary data attached, or a `202 Accepted`, or `302 Found` status code with no body and a `location` header pointing to the actual binary file.

<Note>
  The `content-type` response header can be used to understand the type of
  content returned in the API. Additionally, every API endpoint has its
  response type documented in our API reference documentation.
</Note>

### Headers

As per the HTTP specification, all response header names in the Box API are
case-insensitive and could change over time.

This means that the API might return responses with a content type header of
`CONTENT-TYPE: application/json`, `content-type: application/json` or
`content-type: application/json`. Ideally your application should convert header
names to a standard case upon request and then use that standardized set of
headers to look up values of the headers.

Header values **are** always case sensitive unless stated otherwise.

### Resources

Most standard API responses where only one resource is returned follow the
following format.

```json theme={null}
{
  "id": "12345",
  "type": "folder",
  ...
}
```

Every one of these resources will always return an ID and the type of the resource.

### Collections

Where an API response returns multiple items a collection is returned. Although
the exact format of these collections can change from endpoint to endpoint they
generally are formatted as follows.

```json theme={null}
{
  "total_count": 5000,
  "limit": 1000,
  "offset": 2000,
  "order": [
    {
      "by": "type",
      "direction": "ASC"
    }
  ],
  "entries": [
    {
      "id": 12345,
      "etag": 1,
      "type": "file",
      "sequence_id": 3,
      "name": "Contract.pdf"
    }
  ]
}
```

| Field | Always present? | |
| - | - | - |
| `entries` | Yes | A list of entries in the collection |
| `total_count` | No | The total numbers in the collection that can be requested. This can be larger than this page of results |
| `limit` | No | For endpoints that support offset-based pagination, this specifies the limit to the number of results returned |
| `offset` | No | For endpoints that support offset-based pagination, this specifies the offset of results returned |
| `order` | No | For endpoints that support sorting, this specifies the order the results are returned in |
| `next_marker` | No | For endpoints that support marker-based pagination, this specifies the marker for the next page that can be returned |
| `prev_marker` | No | For endpoints that support marker-based pagination, this specifies the marker for the previous page that can be returned |

### Request IDs

When your API call returns in an error, our API will return an error
object with a `request_id` field.

```json theme={null}
{
  "type": "error",
  "status": 400,
  "code": "item_name_invalid",
  "help_url": "/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "Method Not Allowed",
  "request_id": "abcdef123456"
}
```

When reaching out to support about a specific error, please provide the full API
response including the `request_id` to help our support team to quickly find your
request.

<Note>
  Most API calls also return a `box-request-id` response header. The value of
  this header should not be confused with the `request_id` value in the body of
  an error response.
</Note>

### Large numbers

In some cases the API can return extremely large numbers for a field. For
example, a folder's size might have grown to many terabytes of data and
as a result the `size` field of the folder might have grown to a very large
number.

In these cases these numbers are returned in [IEEE754][numbers] format for
example `1.2318237429383e+31`.

[numbers]: https://en.wikipedia.org/wiki/IEEE_754

[rfc3339]: https://www.ietf.org/rfc/rfc3339.txt


# Applications
Source: https://developer.box.com/guides/applications/index



Box Developer Console allows you to create applications
you can then use to integrate with Box.
**My Platform Apps** view displays a list of already created applications
and gives you quick access to their configuration details.
This way, you don't need to open
the app each time you want to generate
a Developer Token, copy the Client ID, or generate a report.

## Features

**My Platform Apps** page allows you to:

* Search through the list of already created apps.
* Filter the apps by **Enablement Status** and **Authentication Type**.
* Create <Link href="/guides/applications/platform-apps/create">a new app</Link>.
* Copy the app's <Link href="/guides/authentication/client-credentials">Client ID</Link>.
* Rename the app and access its details with one click.
* Check application <Link href="/guides/authorization/platform-app-approval#user-authentication-apps">enablement</Link> and <Link href="/guides/authorization">authorization</Link> status. Apps published to Integrations display status from Integrations.

The **Options menu** available for every entry allows you to:

* Access the configuration details of your application.
* Generate a <Link href="/guides/authentication/tokens/developer-tokens">Developer Token</Link>.
* Add collaborators to your application.
* Run the <Link href="/guides/troubleshooting/app-diagnostics-report">Platform App Diagnostics Report</Link>.

## Platform App Insights

Admins and co-admins can access the Platform Insights
dashboard that provides a comprehensive
view of the organization’s platform usage.
This includes app-related data, such as:

* The total number of API calls per application.
* A list of top applications within the enterprise.
* A list of pending application approvals.
* A list of applications awaiting enablement.

See [Platform Insights][insights] for details.

<Note>
  You need the following permissions to access
  and view Platform Insights:

  * View settings and apps for your company
  * Edit settings and apps for your company
  * Run new reports and access existing reports
</Note>

[insights]: https://support.box.com/hc/en-us/articles/20738406915219-Platform-Insights


# Integrations
Source: https://developer.box.com/guides/applications/integrations/index



[Box Integrations][app-center] is the first place for Box users to find out
about applications they can use in combination with Box. If your
application can be used by other enterprises, listing your service
under **Integrations** can be a great way to find new users.
Integrations group apps into sections so that you can
quickly find featured, most popular, or recently added apps.

<Frame>
  <img alt="Integrations" />
</Frame>

## Developing a platform app or becoming a Box Partner

If you need more information on developing a platform app for the Box Integrations or becoming a Box Partner, visit our [Box Partner Resources][bp] guides on our community site.

## Publishing a platform app

Use the following steps to publish a platform app in Box Integrations.

### Prerequisites

Your application must meet the following requirements:

* The platform app is in a finished state and ready for production usage.
* The platform app leverages OAuth 2.0 authentication, as Integrations do not support any other authentication methods.
* You are a developer with access to the platform app in the **Developer Console**.

### Steps

1. Navigate to the Developer Console > **My Platform Apps** and select the app you want to publish.

2. Select the **Publishing** tab from the top menu.

   <Frame>
     <img alt="Publishing tab for an application" />
   </Frame>

3. Read through the submission checklist and check the confirmation checkbox if your app meets all the requirements.

4. Fill in the form by providing the following details:

   * The categories your app falls under
   * A short and a long description
   * The URL for the **Add** button
   * Screenshots and an app icon
   * Supplementary information to support users

5. Use the **Preview** button in the top right corner to see how your application will look when listed.

6. Finally, submit the application for approval by clicking the **Submit for Approval** button. Once a request for approval is received, the Box Partner team will be notified and review your request as soon as possible. For any questions, email [`integrate@box.com`][email].

## Unpublishing a platform app

Once approved and published, a platform app can be unpublished from the same
control panel:

1. Navigate to the **Developer Console** and select your platform app.
2. Select the **Publishing** tab.
3. You can now unpublish the app.

[app-center]: https://app.box.com/services

[email]: mailto:integrate@box.com

[bp]: https://support.box.com/hc/en-us/sections/21356597387539-Box-Partner-Programs

<RelatedLinks title="RELATED GUIDES" />


# Create a Platform App
Source: https://developer.box.com/guides/applications/platform-apps/create



A Platform App allows for interaction with our 150+ endpoints.
For example, downloading/uploading, searching, applying metadata and more.

## Prerequisites

Access to the [Developer Console][dev-console].

## Create a Platform App

1. Navigate to the [Developer Console][dev-console].
2. Click **New App**.
3. Select an app type: **User** for apps where users link their Box accounts, or **Server** for backend services infrastructure.
4. If you selected **Server**, you may also be asked to choose an authentication method (see below for more information).
5. Click **Create**.

For **Server** apps, <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>
is always the default. The **Switch
server app auth type (CCG or JWT)** setting in **Admin Console > Enterprise Settings > Platform Apps** controls whether the
method is locked:

* When switching is **enabled** (the default for free developer accounts), the
  app is created with Client Credentials Grant and you can change it to
  <Link href="/guides/authentication/jwt">JWT</Link> - or back - afterward.
* When switching is **disabled** (the default for enterprises), the dialog shows
  a **Select Method** step with Client Credentials Grant preselected. You have the option to
  pick <Link href="/guides/authentication/jwt">JWT</Link> at creation instead.
  The method is then fixed for the life of the app.

See <Link href="/guides/authentication#choosing-between-ccg-and-jwt">Choosing between CCG and JWT</Link>
for guidance on picking the method, and <Link href="/guides/authentication/switch-server-auth-type">Switch between CCG and JWT</Link>
for how to change it later.

## Configure application settings

After you create a Platform App, the settings screen is displayed.

### General settings

* **App Name** - the name you set up during the app creation, you can change it here if needed.
* **App Description** - provide a description for your app (optional).
* **Contact Email** - this is set to the developer of the application by default.
  Keep in mind that once you publish your app, this email is publicly visible to Box users
  who view your app in the <Link href="/guides/applications/integrations">Integrations</Link>. We recommend changing it to a
  support email address, so that users can reach out to support in case of any issues with
  the integration.

### Configuration

* **Purpose** - select the purpose of your app from the drop-down list.
  Depending on the option you choose, you might need to specify further details.

| Purpose | Details |
| - | - |
| **Automation**, **Custom Portal** | Specify if the app is built by a customer or partner. |
| **Integration** | Specify the integration category, external system name if you're integrating with one, and if the app is built by a customer or partner. |
| *Other* | Specify the app purpose and if it is built by a customer or partner. |

* **Authentication Method** - how your app authenticates to the Box APIs.

| App type | Auth method | Details |
| - | - | - |
| **User Authentication** | OAuth 2.0 | Specify the client ID and client secret. |
| **Server Authentication** | Client Credentials Grant or JWT | Chosen during app creation or set in the **Configuration** tab, depending on the **Switch server app auth type (CCG or JWT)** enterprise setting. See <Link href="/guides/authentication/switch-server-auth-type">Switch between CCG and JWT</Link>. |

* **Developer Token** - a developer token is created automatically when you create a Platform App.
* **Application Scopes** - choose the scopes you want to grant to your app. See the <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes guide</Link> for detailed information on each option.
* **Advanced Features** - enable the advanced features your application requires.
* **CORS Domains** - add the domains you want to allow requests from.

[dev-console]: https://app.box.com/developers/console

<RelatedLinks title="RELATED GUIDES" />


# Platform App
Source: https://developer.box.com/guides/applications/platform-apps/index



A Platform App typically presents Box functionality to a user through a
custom interface. Box offers pre-built, customizable user interface components,
known as <Link href="/guides/embed/ui-elements">UI Elements</Link>, for functionalities like browsing, searching, and
previewing content.

## Authentication methods

When you create a Platform App, you select an app type:

* **User**: for user-facing apps that redirect users to Box to log in.
  Uses <Link href="/guides/authentication/oauth2">OAuth 2.0</Link>.
* **Server**: for backend services and automations.
  Uses <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>
  or <Link href="/guides/authentication/jwt">JWT</Link>. Depending on your enterprise
  settings, you pick the method when you create the app or set it later in the
  **Configuration** tab.

<Card href="/guides/authentication" title="Compare authentication methods" />

## When to use

Use a Platform App when you want to:

* Use <Link href="/guides/authentication/oauth2">OAuth 2.0</Link>, <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>, or <Link href="/guides/authentication/jwt">JWT</Link> for authentication.
* Upload and download files
* Access both your own files and files owned by <Link href="/guides/getting-started/users#managed-users/">managed or external users</Link>.
* List the application in the Box Integrations
* Provide integration into the Box Web App

## Use cases

Example use cases include:

* A file vault in an application that allows an end user to access files that have been shared with them, while also providing access for employees to the same files through the Box Web app.

  An example of this is a financial advisor sharing statements and investment
  prospectuses with investors that can be viewed and commented on within a
  platform application.

* A file upload feature in an application that allows an end user to submit and upload files from within a custom-built application to Box. These uploads then initiate a business process with the Box Web app.

  An example of this is a candidate submitting a PDF of a resume to a
  recruiting portal that can then be routed to an appropriate employee for
  review.

<SignupCTA>
  A free developer account gives you access to the Developer Console, where you can create Platform Apps using your preferred authentication method.
</SignupCTA>

## Approval

Platform Apps may require approval before use.

<Card href={localizeLink("/guides/authorization/platform-app-approval")} title="Learn how to approve Platform Apps" />

<RelatedLinks title="RELATED GUIDES" />


# Create Web App Integration
Source: https://developer.box.com/guides/applications/web-app-integrations/configure



This guide explains how to set up a Web App Integration with a Platform App.

<Warning>
  Server-side integration is no longer supported.
  This means the applications using server-side actions will still be working,
  but you won't be able to modify the server-side configuration options such as
  Preliminary Callback URL or Basic Authentication.
  You will be able to deactivate them and change the implementation to a new one.
</Warning>

## Create an OAuth 2.0 Application

Navigate to the [Developer Console][devconsole] and create a <Link href="/guides/applications/platform-apps/create">Platform App</Link>
that leverages <Link href="/guides/authentication/oauth2/oauth2-setup">OAuth 2.0 authentication</Link>.

## Create a New Integration

Then, navigate to the **Integrations** tab and click
**Create a Web App Integration**.

<Frame>
  <img alt="Integration Tab" />
</Frame>

## Configure Integration

To configure the integration, follow the guidance below for each value.

### App Info

| Field | Description |
| - | - |
| Integration name | The name of your integration, which users see in the Box Web App when they select the **More Options** > **Integrations** menu on a file or folder. |
| Description | The description of the integration displayed in the Box Integrations. |
| Supported file extensions | The integration will only appear as an option in the **More Options** > **Integrations** menu for the selected file extensions. |
| Permissions requirement | Determines what permissions level users need to see the integration. **Download permissions are required** allows users to download the file - they will not be able to update it. **Full permissions are required** allows users to download and update the file. |
| Integration scopes | Specifies the scope of your integration - either the file/folder from which integration is invoked, or its parent folder. |
| Display on shared pages toggle | Determines if an integration can be shown to external users on a shared page. If enabled, users who are not collaborating on the content will see the integration in the context-menu when accessing the items through a shared link. |
| Lock to only allow the current user to overwrite the file using your integration toggle | Determines if different web app integrations can edit the file at the same time. |
| Integration type | Select desired integration type. Available options are: **Files**, **Folders**, **Both**. |

### Callback Configuration

| Field | Description |
| - | - |
| Client Callback URL | Handles additional callback requests from Box after the primary request with <Link href="/guides/applications/web-app-integrations/types">Popup Integrations</Link>. If the application specifies a file parameter in the REST method, the preliminary callback URL cannot originate from the client. As a result, a second request must be made from the client to your server so the server can send the necessary interface to the user. |
| Prompt Message | Specifies the message that users see when they initiate the integration. Use this field to provide context about what happens next. The message is limited to 500 characters. |
| User Experience | Informs that the integration will open in a new window. |
| New Window Settings | Determines if the application opens in a new tab. |

### Callback Parameters

The **Callback Parameters** section configures the parameters that Box sends to
the callback URL when a user accepts a confirmation prompt. If this setting is
not configured, Box does not send any parameters to the callback URL.
To add a parameter, select the **Method** (GET or POST),
specify the **Parameter name** and add a **Parameter value**.

<Warning>
  The **File** method is no longer supported. If you already used this method,
  you cannot edit its values. You can change the **File** method to **GET**
  or **POST**, but you can't undo this action.
</Warning>

For example: **GET - `userid` - `#user_id#`**.

The following parameter values are available.

| Parameter | Method | Description |
| - | - | - |
| `user_id` | GET, POST | The Box <Link href="/guides/getting-started/locating-values/#user-ids">user ID</Link>. This information is used in Popup Integrations in which user authentication is required to complete an action. You can store the Box ID in your application to enable subsequent authentication requests from the integration. |
| `user_name` | POST | The full name or email address of the Box user. Not all Box users specify their names at all times. |
| `file_id` | GET, POST | The Box <Link href="/guides/getting-started/locating-values/#content-ids">file ID</Link>. You can use this ID to make Box API calls that affect the file. |
| `file_name` | POST | The name of the file. |
| `file_extension` | GET, POST | The extension of the file. |
| `auth_code` | GET, POST | The OAuth 2.0 <Link href="/guides/authentication/oauth2/without-sdk/#3-user-grants-application-access">authorization code</Link>, which is generated by Box upon successful authentication. Your application must then supply this authorization code to Box in exchange for an OAuth 2.0 Access Token. An authorization header containing a valid Access Token must be included in every Box API request. |
| `redirect_to_box_url` | GET, POST | In Popup Integrations, the URL to which requests are sent by the confirmation prompt. Use this URL to redirect users to the All Files page. This parameter closes the popup panel and refreshes the All Files page to reflect any changes performed by the integration. If you do not want to add this parameter to your application, you can specify the entire URL. **Success**: `#redirect_to_box_url#&status=success&message=Your%20action%20was%20successful%2E`.  **Failure**: `#redirect_to_box_url#&status=failure&message=Your%20action%20was%20unsuccessful%2E` |

### Integration Status

* **Development**: The integration is visible and available only to application collaborators listed under the **General Settings** tab. This option is best used when the application is still in development and undergoing testing.
* **Online**: The integration is visible and available to all Box users. This option is best used when development is complete and the application is ready to publish in the Integrations.
* **Maintenance**: The integration is visible and available only to application collaborators listed under the **General Settings** tab. This option is best used after the integration is published in the Integrations, but needs to perform maintenance updates or troubleshoot issues. Use this option to temporarily take the integration offline for everyone except the application's collaborators.

## Example Use Cases of Box Integrations

When a user chooses a Popup Integration, Box sends a callback request to the
primary callback URL. It sends the callback parameters that have been configured to
the server. In some cases, Box may make a second request if the
client cannot get all the data it needs from the first request.

The following example does not require a client callback URL:

* The Popup Integration performs a REST call using a `download_file_url` callback parameter.
* The user clicks **OK** in the confirmation prompt to accept the popup.
* Box sends a request to the following URL (the primary callback URL plus the callback parameter): `http://www.doceditor.com/service?apikey=abc&file=&redirect=`.
* The response from the callback URL displays a user interface to the user who made the request. The popup has all the information needed to continue the action and an additional client callback is not needed.

The following example requires a client callback URL:

* The Popup Integration performs a REST call using a file-callback parameter.
* The user clicks **OK** in the confirmation prompt to accept the popup.
* The popup displays a page where Box sends a POST request with the contents of a file, along with the callback parameters to the remote server.
* Box receives the response from the remote server and directs the client to POST the response to the client callback URL. The server identified by the URL interprets the response and redirects the user with the correct session ID.

## Client-callback URL Request Format

The POST request that Box sends to the client callback URL takes the response
from the primary callback URL and forwards it to the same URL along with the
same data as the original callback.

| Client Callback URL | Example |
| - | - |
| Two GET parameters and one POST parameter: `http://your-client-callback-url.com/?get_param1=value1&get_param2=value2` | `POST data: post_param1=value1initial_callback_response` |

The response to the client-callback request is an HTTP status 302, redirecting
the user to the correct URL or to the HTML for a UI.

Most often the URL points to a separate API or custom script developed for Web
App Integrations, which parses the result of the primary callback URL.

<Warning>
  If you want to publish your platform app for all Box customers to use, make sure that the URL is publicly accessible on the internet.
</Warning>

## Making Integration Publicly Available

To make a Box integration publicly available it needs to be listed in the App
Center. Follow the <Link href="/guides/applications/integrations">Integrations</Link> guide for more details.

[devconsole]: https://app.box.com/developers/console

[devaccount]: https://account.box.com/signup/n/developer

<RelatedLinks title="RELATED GUIDES" />


# Web App Integration
Source: https://developer.box.com/guides/applications/web-app-integrations/index



Web App Integrations allow third-party applications to
become part of the Box user experience by
allowing users to use such third-party applications
when editing or sharing files.

## Features

* **File interaction**. Users can modify, share, or edit content stored in Box using a third-party application.
* **Recommended Apps support**. Integrations can appear in the Box Preview interface under **Recommended Apps**. For details, see [Recommended Web Integrations][recommended-web-integrations].

<Frame>
  <img alt="Integration example" />
</Frame>

* **Scoped availability**. Integrations can be restricted to certain content types and file extensions.

## Visibility in Recommended Apps

Your web application integration appears in **Recommended Apps** only if it is published in Integrations.

<Card href={localizeLink("/guides/applications/web-app-integrations/configure")} title="Learn how to create a Web App Integration" />

[integrations]: /guides/applications/integrations

[custom-app]: /guides/authentication/oauth2/oauth2-setup

[oauth2]: /guides/authentication/oauth2

[devconsole]: https://app.box.com/developers/console

[recommended-web-integrations]: https://support.box.com/hc/en-us/articles/360044195533-Installing-Recommended-Apps-in-your-Enterprise


# Integrations Types
Source: https://developer.box.com/guides/applications/web-app-integrations/types



Currently, Box provides the Popup integration type.

## Popup Integrations

In a popup integration, Box opens a panel and loads the application's callback
URL configured for the integration. The application can display its own user
interface for the integration in the popup.

The integration receives a short-lived authorization code with this request,
which can be used to connect to the Box APIs, exchange the code for an Access
Token, and then use that to make API calls to Box.

<Warning>
  Popup panels use HTML `<iframe>` tags to display the embedded content. To
  protect the security of Box's content, callback URLs should use SSL, and the
  response from the callback URL should include an `X-Frame-Options` header set
  to a random string value.
</Warning>

<RelatedLinks title="RELATED GUIDES" />


# User Experience
Source: https://developer.box.com/guides/applications/web-app-integrations/user-experience



The following explains what a Web App Integration looks like from a user's point
of view.

1. Box users can discover applications in the Box Integrations. They can visit the Integrations directly, or select the **Integrations** menu from the Box Web App UI.
2. In the Integrations they select the application they would like to add. Every published Box application has a public profile page, which provides details including the integrations it provides.
3. The user adds the application to their account by clicking the **Add** button in the Integrations listing. Once an application is added to an account, all its integrations become available to the user.
4. Select an integration from the **More Actions** menu on a file or folder.
5. Box will ask the user for permission to share the file or folder with the application. The confirmation prompt must be accepted before the integration can be successfully used.
6. Upon granting access, Box passes the data to the application. Depending on the type of integration, the application will then display a popup panel or run a server-based process.


# Authentication best practices
Source: https://developer.box.com/guides/authentication/best-practices

Practical guidance on protecting your client secret, caching and refreshing access tokens, downscoping, and revoking tokens.

## Client secret security

Your client secret is confidential and needs to be protected. Because this is
how we securely identify an application's identity when obtaining an
Access Token, you do not want to freely distribute a client secret. This
includes via email, public forums and code repositories, distributed native
applications, or client-side code.

## Cache tokens

Because fetching new tokens is expensive, we recommend using a token cache
to prevent unnecessary requests.

After retrieving a token, store it in an in-memory cache, like Memcached, or a
built-in ASP.NET cache service. By default, Access Tokens are valid for 60
minutes, but we recommend setting the expiration time to around 50 minutes to
allow for a buffer.

When you need a token, first check the cache for a valid token. If the token
expired, get a new one and store it in the cache for 50 minutes.

```ruby theme={null}
def self.user_client(user_id)
    access_token=Rails.cache.fetch("box_tokens/user/#{user_id}", :expires_in => 50.minutes) do
        puts "getting new user token"
        response= Boxr::get_user_token(user_id, private_key: PRIVATE_KEY, private_key_password: ENV['JWT_PRIVATE_KEY_PASSWORD'])
        response.access_token
    end

    Boxr::Client.new(access_token)
end
```

<Tip>
  Official Box SDKs use token caching.
</Tip>

## Expired tokens

Expired tokens return a 401: Unauthorized error. This error should be handled
to refresh the token.

## Downscope tokens

It is important to follow the principle of least privilege when thinking about
Access Tokens. This can be accomplished through <Link href="/guides/authentication/tokens/downscope">downscoping</Link>, where
a fully scoped Access Token is exchanged for a more restricted Access Token that
can then be deployed to client-side code, mobile environments, or UI tools.

```java theme={null}
//Define resource/scopes that downscoped token has access to
String resource = "https://api.box.com/2.0/files/RESOURCE_ID";
List<String> scopes = new ArrayList<String>();
scopes.add("base_preview");
scopes.add("item_download");

//Preform token exchange
ScopedToken downscopedToken =
    client.getLowerScopedToken(scopes,resource);

//Downscoped token available in downscopedToken.getAccessToken()
```

## Revoke tokens

Both fully scoped Access Tokens and Downscoped Tokens can be <Link href="/guides/authentication/tokens/revoke">revoked</Link>.
This allows you to manage the lifespan of a token to reduce exposure when a user
logs out, there is suspicious activity, or when you need to push new security
enhancements.

## Developer tokens

<Link href="/guides/authentication/tokens/developer-tokens">Developer tokens</Link>
should only be used for development or testing purposes and never in production.
They expire after 60 minutes, can't be refreshed programmatically, and inherit
the access of whoever generated them.


# Setup with Client Credentials Grant
Source: https://developer.box.com/guides/authentication/client-credentials/client-credentials-setup

Create a Server app with Client Credentials Grant, configure its access level and scopes, and request an access token.

## Prerequisites

To set up a Platform App using server-side authentication, you need to ensure
you have access to the [Developer Console][devconsole] from your Box enterprise
account. Alternatively, you may sign up for a [developer account][devaccount].

Your Box account also needs [multi-factor authentication (MFA)](https://support.box.com/hc/en-us/articles/360043697154-Multi-Factor-Authentication-Set-Up-for-Your-Account)
enabled, because Box requires it before it shows the application's client secret
on the **Configuration** tab.

## App creation steps

### Create a Server Authentication app

1. Log into Box and go to the [Developer Console][devconsole].
2. Select **New App**.
3. Select **Server** as the app type.
4. Leave **Client Credentials Grant** selected under **Select Method**.
5. Select **Create**.

Client Credentials Grant (CCG) is preselected for new Server Authentication
apps, so selecting **Create** without changing the method produces a CCG app.
Your enterprise's **Switch server app auth type (CCG or JWT)** setting only
affects whether you can change the method later. It is enabled by default for
free developer accounts and disabled by default for enterprises, so in an
enterprise treat the method as fixed once the app is created.

<Info>
  When switching is enabled, you can change to
  <Link href="/guides/authentication/jwt">JWT</Link> at any time from the
  **Configuration** tab. See
  <Link href="/guides/authentication/switch-server-auth-type">Switch between CCG and JWT</Link>
  for details.
</Info>

## App authorization

Server authentication applications must be authorized before use. The authorization process depends on your account type.

**Free developer accounts**: Your app is automatically authorized when you create it. If authorization did not complete, the **Configuration** tab displays a prompt to authorize the app.

**Enterprise accounts**: After you create the app, the **Configuration** tab prompts you to submit the app for admin approval.

**Enterprise admins and co-admins**: The **Configuration** tab lets you authorize the app directly after creation.

<Card href="/guides/authorization/platform-app-approval" title="Learn more about the authorization process" />

## Basic configuration

### Application access

An application's access level determines which users and content your app may
access. By default, an application can only successfully interact with the
content of its <Link href="/guides/getting-started/users#service-account">Service Account</Link> and any <Link href="/guides/getting-started/users">App Users</Link>. To also
access existing Managed Users of an enterprise, navigate to the
**App Access Level** setting on the **Configuration** tab of the
[Developer console][devconsole] and set to **App + Enterprise Access**.

<Frame>
  <img alt="App access level" />
</Frame>

<Note>
  To authenticate as a Managed User or Admin, enable **Generate User Access Tokens** in the **Additional Configuration** section of the **Configuration** tab.
</Note>

### Application scopes

An application's scopes determine which endpoints and resources an application
can successfully call. See the <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes guide</Link> for detailed information
on each option.

<Frame>
  <img alt="App scopes" />
</Frame>

### CORS domains

If your application makes API calls from front-end browser code in
Javascript, the domain that these calls are made from needs to be
added to an allow-list due to [Cross Origin Resource Sharing][cors],
also known as CORS. If all requests are made from server-side code,
you may skip this section.

To add the full URI(s) to the allow-list, navigate to the **CORS Domain**
section at the bottom of the **Configuration** tab in the
[Developer console][devconsole].

<Frame>
  <img alt="App CORS config" />
</Frame>

## Get an access token

Post your client ID and client secret to the
<Link href="/reference/post-oauth2-token">token endpoint</Link> with a
`grant_type` of `client_credentials`, and name the subject you want to
authenticate as.

<CodeGroup>
  ```sh Service Account theme={null}
  curl -X POST https://api.box.com/oauth2/token \
      -d "grant_type=client_credentials" \
      -d "client_id=[CLIENT_ID]" \
      -d "client_secret=[CLIENT_SECRET]" \
      -d "box_subject_type=enterprise" \
      -d "box_subject_id=[ENTERPRISE_ID]"
  ```

  ```sh User theme={null}
  curl -X POST https://api.box.com/oauth2/token \
      -d "grant_type=client_credentials" \
      -d "client_id=[CLIENT_ID]" \
      -d "client_secret=[CLIENT_SECRET]" \
      -d "box_subject_type=user" \
      -d "box_subject_id=[USER_ID]"
  ```
</CodeGroup>

The same user request authenticates an App User, a Managed User, or an Admin.
Which of them you can request a token for depends on the app's configuration: an
App User needs **Generate User Access Tokens**, and a Managed User or an Admin
needs **App + Enterprise Access** as well.

## Common errors

### Grant credentials are invalid

During authentication, you can encounter the following error:

```sh theme={null}
Grant credentials are invalid [400 Bad Request] invalid_grant - Grant credentials are invalid
```

This error indicates one of the following:

* The client ID and client secret passed are incorrect or are not for the same application.

* The `box_subject_id` can't be used based on the selected [application access](#application-access).

<Warning>
  A CCG app with App Access Only can send in the `box_subject_type` of `enterprise` to authenticate as its Service Account, but it can't authenticate as a Managed User or an Admin.
</Warning>

* Your application isn't configured to generate user access tokens. Enable **Generate User Access Tokens** in the **Advanced Features** section of the **Configuration** tab.

  <Frame>
    <img alt="Generate access tokens check" />
  </Frame>

<Warning>
  Once you make changes to the app settings, don't forget to <Link href="/guides/authorization/platform-app-approval#re-authorization-on-changes">reauthorize</Link> the application in the Admin Console.
</Warning>

* Your application has not been authorized in the Box Admin Console.

## Using SDKs and Client Credentials Grant

To learn more about Client Credentials Grant for each SDK head over to:

* [.Net][.Net]

* [Java][Java]

* [Python][Python]

* [Node][Node]

* [IOS][IOS]

[.Net]: https://github.com/box/box-windows-sdk-v2/blob/legacy/docs/authentication.md#server-auth-with-ccg

[Java]: https://github.com/box/box-java-sdk/blob/legacy/doc/authentication.md#client-credentials-grant

[Python]: https://github.com/box/box-python-sdk/blob/legacy/docs/usage/authentication.md#client-credentials-grant

[Node]: https://github.com/box/box-node-sdk/blob/legacy/docs/authentication.md#client-credentials-grant-authentication

[IOS]: https://github.com/box/box-ios-sdk/blob/legacy/BoxSDK/docs/usage/authentication.md#client-credentials-grant

[devconsole]: https://app.box.com/developers/console

[devaccount]: https://account.box.com/signup/n/developer

[cors]: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Client Credentials Grant
Source: https://developer.box.com/guides/authentication/client-credentials/index

How Client Credentials Grant authenticates a Server app with a client ID and client secret, and which subjects it can request a token for.

<RelatedLinks title="REQUIRED GUIDES" />

Client Credentials Grant (CCG) is an authentication method for
<Link href="/guides/applications/platform-apps/index">Platform Apps</Link> using
**Server Authentication**. It verifies your application's identity with a client
ID and a client secret, and returns an access token without anyone signing in.
CCG is preselected for new Server apps.

## How it works

Your application posts its client ID and client secret to the
<Link href="/reference/post-oauth2-token">token endpoint</Link> with a
`grant_type` of `client_credentials`, along with the subject it authenticates as.
Box returns an access token that is valid for 60 minutes. No refresh token is
issued, so request a new access token when the current one expires.

Every token request names one of three subjects.

| Authenticate as | `box_subject_type` | `box_subject_id` | Also required |
| - | - | - | - |
| The application's <Link href="/guides/getting-started/users#service-account">Service Account</Link> | `enterprise` | Your enterprise ID | Nothing beyond app authorization |
| An App User | `user` | The App User's ID | **Generate User Access Tokens** |
| A Managed User or an Admin | `user` | The user's ID | **App + Enterprise Access** and **Generate User Access Tokens** |

Both settings live on the **Configuration** tab of your app in the Box
[Developer Console][devconsole], and changing them means you have to
<Link href="/guides/authorization/platform-app-approval#re-authorization-on-changes">reauthorize</Link>
the application.

<Warning>
  Your client secret identifies your application to Box, so treat it like a
  password. Keep it out of email, public forums, code repositories, distributed
  native applications, and client-side code. See the
  <Link href="/guides/authentication/best-practices">authentication best practices</Link>
  for how to store and rotate it.
</Warning>

## Switching to JWT

If your integration requires keypair-based authentication and your enterprise
allows switching auth types, you can
<Link href="/guides/authentication/switch-server-auth-type">change to JWT</Link>
from the **Configuration** tab at any time. If switching is disabled, the method
is set when the app is created and can't be changed later.

<SignupCTA>
  A free developer account gives you access to the Developer Console, where you can set up Client Credentials Grant authentication in minutes.
</SignupCTA>

<Card href={localizeLink("/guides/authentication/client-credentials/client-credentials-setup")} title="Set up an app with Client Credentials Grant" />

[devconsole]: https://app.box.com/developers/console

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Authentication
Source: https://developer.box.com/guides/authentication/index

Compare Box authentication methods, see which credentials and files each one needs, and learn what the access token you get back represents.

Every Box API call carries an [access token](#the-access-token), and that token tells Box which user the call acts as. Your app gets the token by exchanging its credentials with Box, and the way it makes that exchange is its **authentication method**.

The methods available to you follow from the **app type** you pick when you create a <Link href="/guides/applications/platform-apps/index">Platform App</Link> in the <Link href="https://app.box.com/developers/console">Developer Console</Link>. That choice comes down to one question: does a person sign in to Box to use your app, or does your app run on its own?

* Apps that people sign in to are **User** apps, which always use **OAuth 2.0**.
* Apps that run on their own are **Server** apps, which use either **Client Credentials Grant (CCG)** or **JWT**.

## Authentication methods at a glance

The methods differ in how your app proves who it is, and in the content the resulting token can reach.

| | [OAuth 2.0](#oauth-20) | [CCG](#client-credentials-grant) | [JWT](#jwt) |
| - | - | - | - |
| **App type** | User | Server | Server |
| **Proves identity with** | Client secret plus user consent | Client secret | Public/private keypair |
| **Requires admin authorization or enablement** | Depends on enterprise settings | Yes | Yes |
| **Can act on behalf of other users** | With extra setup | Yes | Yes |
| **Can create App Users** | No | Yes | Yes |
| **Best for** | Apps whose users sign in with their own Box accounts | Backend services, automations, and integrations | Backend services that require a public/private keypair |

A Server app has to be authorized before it can call the API. An OAuth 2.0 app needs a Box Admin or Co-Admin to enable it only when your enterprise leaves unpublished apps inactive by default. <Link href="/guides/authorization/platform-app-approval">Platform App Approval</Link> covers both cases.

<Warning>
  You can't convert a User app into a Server app, or a Server app into a User app. To move between them, create a new app.
</Warning>

<Card href={localizeLink("/guides/authentication/jwt/jwt-setup")} title="Set up JWT authentication" />

<Card href={localizeLink("/guides/authentication/tokens/access-tokens")} title="Learn about Box access tokens" />

<Card href={localizeLink("/guides/authentication/tokens/developer-tokens")} title="Generate a developer token" />

<SignupCTA>
  A free developer account gives you access to the Developer Console, where you can create apps, configure authentication, and generate access tokens.
</SignupCTA>

To try authentication without affecting production data, use a [developer sandbox](/guides/getting-started/sandbox).

## OAuth 2.0

OAuth 2.0 is an [open standard](https://oauth.net/2/) that lets people grant an application access to their data in another application. If you've ever signed in to a website with Google or Facebook, you've used it. Box follows the same flow: your app sends the user to Box, the user logs in and approves the request, and Box returns an authorization code that your app exchanges for an access token.

Because the token belongs to the person who signed in, your app reaches exactly the content that user owns or collaborates on, and the content it creates lives in that user's own account.

Choose OAuth 2.0 when your users already have Box accounts and you want them to sign in to Box themselves.

<Card href={localizeLink("/guides/authentication/oauth2")} title="Learn about OAuth 2.0 authentication" />

## Client Credentials Grant

Client Credentials Grant (CCG) verifies your application's identity with a client ID and client secret, then returns an access token directly. No one logs in, so it suits code that runs unattended. CCG is preselected when you create a Server app.

Each token request names the subject it authenticates as: the application's <Link href="#service-accounts">Service Account</Link>, or a specific user when the app is configured to allow it.

Choose CCG for a backend service, an automation, or an integration whose end users have no Box accounts of their own or sign in through your identity system. Each of those users can get an isolated App User with its own folder tree.

<Card href={localizeLink("/guides/authentication/client-credentials")} title="Learn about Client Credentials Grant" />

## JWT

Server authentication with JSON Web Tokens (JWT) has your app sign a short-lived assertion with a private key rather than send a secret on its own, then exchange that assertion for an access token. Box holds only the matching public key, so the private key never leaves your infrastructure.

JWT gives you the same Service Account model as CCG, including isolated App Users. The assertion doesn't replace your client secret, which the token request still carries, so JWT adds a second factor to the exchange rather than swapping one credential for another.

<Card href={localizeLink("/guides/authentication/jwt")} title="Learn about JWT authentication" />

## Choosing between CCG and JWT

Both methods reach the same Service Account, the same App Users, and the same content, so the choice comes down to how your app proves who it is and how much credential handling you want to own.

Choose JWT when your security review calls for keypair-based verification, or when you want the private key to stay in your infrastructure: Box stores only your public key, so a leaked client secret alone isn't enough to get a token. The cost is key management, including generating the keypair, protecting the private key and its passphrase, and uploading a new public key whenever you rotate.

Choose CCG otherwise. It needs no keys and no assertion signing, which makes it the simpler option and the one Box recommends for most Server apps.

Whether you can change the method after the app exists depends on an enterprise setting, and switching revokes the credentials tied to the previous method.

<Card href={localizeLink("/guides/authentication/switch-server-auth-type")} title="Switch an existing app between CCG and JWT" />

## Credentials for each method

Each method needs a different set of values, and all of them come from the **Configuration** tab of your app in the <Link href="https://app.box.com/developers/console">Developer Console</Link>.

| Method | Values you need | Where to get them |
| - | - | - |
| OAuth 2.0 | Client ID, client secret, and at least one redirect URI | Read the ID and secret from the **Configuration** tab. Register redirect URIs in the **OAuth 2.0 Redirect URI** section, where they have to match the `redirect_uri` you send exactly. |
| Client Credentials Grant | Client ID, client secret, and the subject to authenticate as: `box_subject_type` of `enterprise` with your enterprise ID, or `user` with a user ID | Read the ID and secret from the **Configuration** tab. See <Link href="/guides/getting-started/locating-values">Locating IDs</Link> for enterprise and user IDs. |
| JWT | Client ID, client secret, public key ID, encrypted private key, passphrase, and enterprise ID | Select **Generate a Public/Private Keypair** in the **Add and Manage Public Keys** section and Box downloads a `config.json` that holds all six values. If you generate your own keypair instead, you keep the private key and passphrase yourself and collect the other values from the **Configuration** tab. |

<Note>
  Your Box account needs [multi-factor authentication (MFA)](https://support.box.com/hc/en-us/articles/360043697154-Multi-Factor-Authentication-Set-Up-for-Your-Account) enabled to view a client secret or generate a keypair.
</Note>

### Where credential files live

JWT is the only method where Box hands you a file. When you select **Generate a Public/Private Keypair** in the Developer Console, Box downloads a `config.json` that holds both the keypair and the application details needed to authenticate. Store that file securely outside source control and load it at runtime, or load the same values from environment variables or a secrets manager. The <Link href="/guides/authentication/jwt/with-sdk">JWT with an SDK</Link> guide shows what the file contains and how to load it.

If you generate your own keypair and upload only the public key, there's no `config.json` to download. Store the private key wherever your application can read it at startup, keep the passphrase separate from the key, and read the remaining values from the **Configuration** tab. OAuth 2.0 and CCG apps have no file at all, so keep their client ID and client secret in environment variables or a secrets manager.

<Warning>
  Box does not store your private key. If you lose it, you have to reset the entire keypair.

  Never commit `config.json` or a client secret to a repository. Add them to your `.gitignore`, and keep them out of email, public forums, distributed native applications, and client-side code. To reach Box from browser code, <Link href="/guides/authentication/tokens/downscope">downscope</Link> a token first.
</Warning>

<Card href={localizeLink("/guides/authentication/best-practices")} title="Read the authentication best practices" />

## Access token

Every method ends in the same place: Box returns an access token, and your app sends it in the `Authorization` header of each API call. The token is valid for 60 minutes, and the response reports the exact lifetime in seconds as `expires_in`.

```sh theme={null}
curl https://api.box.com/2.0/users/me \
    -H "authorization: Bearer [ACCESS_TOKEN]"
```

To call an endpoint before you build any of this, generate a <Link href="/guides/authentication/tokens/developer-tokens">developer token</Link> by hand in the Developer Console. It isn't a separate authentication method: it's an ordinary access token with the same 60-minute lifetime, tied to whoever is signed in to the console, and it's meant for development only.

### How each method requests a token

Every method requests the token from the same endpoint, `https://api.box.com/oauth2/token`, and sends a different `grant_type` with the parameters that accompany it. OAuth 2.0 reaches this request last, after the user has already signed in at Box and consented.

<CodeGroup>
  ```sh OAuth 2.0 theme={null}
  curl -X POST https://api.box.com/oauth2/token \
      -d "grant_type=authorization_code" \
      -d "code=[CODE]" \
      -d "client_id=[CLIENT_ID]" \
      -d "client_secret=[CLIENT_SECRET]"
  ```

  ```sh Client Credentials Grant theme={null}
  curl -X POST https://api.box.com/oauth2/token \
      -d "grant_type=client_credentials" \
      -d "client_id=[CLIENT_ID]" \
      -d "client_secret=[CLIENT_SECRET]" \
      -d "box_subject_type=enterprise" \
      -d "box_subject_id=[ENTERPRISE_ID]"
  ```

  ```sh JWT theme={null}
  curl -X POST https://api.box.com/oauth2/token \
      -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer" \
      -d "assertion=[JWT_ASSERTION]" \
      -d "client_id=[CLIENT_ID]" \
      -d "client_secret=[CLIENT_SECRET]"
  ```
</CodeGroup>

OAuth 2.0 needs the `code` that Box returns after the user consents, and JWT needs an assertion you sign with your private key. The <Link href="/guides/authentication/jwt/without-sdk">JWT without an SDK</Link> guide walks through building that assertion, and the <Link href="/guides/authentication/tokens/sdks">SDKs</Link> handle both steps for you.

### What comes back

What arrives alongside the token differs by method, and it decides how your app keeps working once the token expires.

| Method | Token response contains | Getting the next token |
| - | - | - |
| OAuth 2.0 | An access token and a refresh token | Exchange the refresh token for a new pair |
| Client Credentials Grant | An access token | Request another one with the same client credentials |
| JWT | An access token | Sign a new assertion and exchange it |

A refresh token lasts 60 days and works only once, so an OAuth 2.0 app stores the newest refresh token for each user and sends that user through authorization again if 60 days pass without a refresh. CCG and JWT apps skip this bookkeeping, because they request a fresh token whenever they need one.

### Who the token represents

An access token always maps to one Box user, and that user determines which content your app can reach and where new content lives. What the token can do with that content is narrower still: it's the overlap between the user's own access and the <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link> you enabled for the application, so a call can fail even when the user can see the file.

| Method | Default user | Where content lives |
| - | - | - |
| OAuth 2.0 | The person who granted access | That user's own account |
| Client Credentials Grant | The Service Account | The Service Account's folder tree, or an App User's folder tree |
| JWT | The Service Account | The Service Account's folder tree, or an App User's folder tree |

Every Box account has its own folder tree, and the root of that tree is always folder ID `0`. The same upload call therefore lands in a different place depending on which token you send it with: an OAuth 2.0 token puts the file in the signed-in user's account, while a Service Account token puts it somewhere only the application can see until you share it. Nothing crosses between trees on its own, so if your app has to work with content that already exists, give the account access first.

### Service Accounts

A Service Account is a programmatic user that represents your application inside the Box enterprise. Box generates it automatically once your JWT or CCG app is <Link href="/guides/authorization/platform-app-approval">authorized</Link>, so you never create it yourself. It has no login credentials and acts only through the API, which makes it a good fit for backend integrations. You find its `@boxdevedition.com` email address in the **App Details** tab of your app, next to a link that opens the account in the Content Manager.

A Service Account starts with an empty folder tree, so it can't see your existing files until you give it access. Invite it as a collaborator using its email address, or call the <Link href="/reference/post-collaborations">create collaboration endpoint</Link> with its user ID. <Link href="/guides/getting-started/users#service-account">User types</Link> covers its storage quota, its scopes, and how an Admin browses its content.

<Warning>
  If you call the API with a Service Account token before the app is authorized, Box returns an `unauthorized_client` error with the message `This app is not authorized by the enterprise`.
</Warning>

Server apps aren't limited to the Service Account. A CCG app can request a <Link href="/guides/authentication/client-credentials">token for a specific user</Link>, and a JWT app can send the <Link href="/guides/authentication/jwt/as-user">as-user</Link> header or request a <Link href="/guides/authentication/jwt/user-access-tokens">user access token</Link>. In each case the Managed User or App User keeps their own folder tree.

<Card href={localizeLink("/guides/getting-started/users")} title="Compare Box user types" />

<Card href={localizeLink("/guides/authentication/tokens")} title="Use, refresh, revoke, and downscope tokens" />

## App token

Box has a fourth method, App Token authentication, intended for <Link href="/guides/embed/box-view">Box View</Link> previews and other Limited Access App scenarios. However, it is recommended to use [CCG](#client-credentials-grant) or [JWT](#jwt) for general server-side integrations. See <Link href="/guides/embed/box-view/setup#legacy-limited-access-apps">Legacy Limited Access Apps</Link> to move an existing app onto one of them.

## Next steps

* <Link href="/guides/authentication/oauth2/oauth2-setup">Set up an app with OAuth 2.0</Link>
* <Link href="/guides/authentication/client-credentials/client-credentials-setup">Set up an app with Client Credentials Grant</Link>
* <Link href="/guides/authentication/jwt/jwt-setup">Set up an app with JWT</Link>
* <Link href="/guides/authorization/platform-app-approval">Get your app authorized</Link>
* <Link href="/guides/authorization/common-errors">Fix common authorization errors</Link>
* <Link href="/guides/authentication/sso">See how SSO affects OAuth 2.0 sign-ins</Link>


# as-user header
Source: https://developer.box.com/guides/authentication/jwt/as-user

Act on behalf of another user from a JWT app, including the required app settings, permissions, and known limitations.

<RelatedLinks title="REQUIRED GUIDES" />

It is possible for a JWT application to act on behalf of another user
by leveraging the `as-user` header.

```sh theme={null}
curl https://api.box.com/2.0/folders/0 \
    -H "as-user: [USER_ID]" \
    -H "authorization: Bearer [ACCESS_TOKEN]"
```

<Info>
  In this situation the user ID is the Box identifier for a user. User IDs can
  be found for any user via the `GET /users` endpoint, which is only available to
  admins, or by calling the `GET /users/me` endpoint with an authenticated user
  session.
</Info>

## Preconditions

The application must be configured to perform actions as users in the
[Developer Console][devconsole]. In the **Configuration** tab of your app, in the **Additional Configuration** section, select **Make API calls using the as-user header**.

<Frame>
  <img alt="Advanced Features" />
</Frame>

Additionally, the authenticated user needs to be a user with Admin permissions,
meaning either an Admin or Co-Admin. See our guide on
<Link href="/guides/getting-started/users">User Types</Link> for more details.

## as-user using SDKs

All of the <Link href="/guides/tooling/sdks">official Box SDKs</Link> support acting on behalf of a user using the
`as-user` header.

<CodeGroup>
  ```csharp .NET theme={null}
  var userClient = client.WithAsUserHeader("[USER_ID]");
  ```

  ```java Java theme={null}
  BoxClient userClient = client.withAsUserHeader("[USER_ID]");
  ```

  ```python Python theme={null}
  user_client = client.with_as_user_header('[USER_ID]')
  ```

  ```js Node theme={null}
  const userClient = client.withAsUserHeader('[USER_ID]');
  ```
</CodeGroup>

<Warning>
  These methods return a new client instance with the as-user header applied,
  leaving the original client unmodified.
</Warning>

## Limitations

* You cannot use the `user_id` of a <Link href="/guides/getting-started/users#service-account">Service Account</Link> in the `as-user` header.
* When impersonating a managed user, access is limited to content owned or controlled by the enterprise. Content owned by external users cannot be accessed through the `as-user` header.
* The `as-user` header cannot specify the same user ID as the authenticated user. If the specified user ID matches the current user, the request fails with a `403 Forbidden` error.

[devconsole]: https://app.box.com/developers/console

<RelatedLinks title="RELATED GUIDES" />


# JWT authentication
Source: https://developer.box.com/guides/authentication/jwt/index

How server-side JWT authentication works on Box, from signing an assertion with your private key to receiving a Service Account token.

<RelatedLinks title="REQUIRED GUIDES" />

Server-side authentication using JSON Web Tokens (JWT) lets an application
authenticate to the Box API with no user present. JWT is an [open standard](https://jwt.io/)
designed to allow powerful server-to-server authentication.

<Frame>
  <img alt="The JWT flow" />
</Frame>

Server-side authentication using JWT is available to
<Link href="/guides/applications/platform-apps/index">Platform Apps</Link>.
This authentication method does not require end-user
interaction and, if granted the proper privileges, can be used
to act on behalf of any user in an enterprise.

## How it works

Instead of sending a secret on its own, your application signs a short-lived
assertion with a private key and exchanges that assertion for an access token.
Box holds only the matching public key, so the private key never leaves your
infrastructure. The flow has four steps:

1. Your application reads the application details and the keypair, usually from
   the `config.json` that Box generates for you.
2. It decrypts the private key with the passphrase that came with it.
3. It builds a JWT assertion that names the subject to authenticate as, and
   signs the assertion with the private key.
4. It exchanges the assertion for an access token that is valid for 60 minutes.

## Creating a JWT app

To use JWT, create a **Server Authentication** app and select **JWT** in the
**Create a New App** dialog, which preselects Client Credentials Grant. Your
enterprise's **Switch server app auth type (CCG or JWT)** setting decides whether
you can change the method afterward, and it is disabled by default for
enterprises. When switching is enabled, you can
<Link href="/guides/authentication/switch-server-auth-type">change between JWT and Client Credentials</Link>
at any time.

Upon authorizing a JWT application, a
<Link href="/guides/getting-started/users#service-account">Service Account</Link> is automatically generated and is the default
Access Token used when authenticating. Because the Service Account has admin-like
privileges, JWT applications must be <Link href="/guides/authorization/platform-app-approval">authorized</Link> before use.

<SignupCTA>
  A free developer account gives you access to the Developer Console, where you can create a JWT application and start authenticating server-to-server in minutes.
</SignupCTA>

<Card href={localizeLink("/guides/authentication/jwt/jwt-setup")} title="Set up an app with JWT" />

<RelatedLinks title="RELATED GUIDES" />


# Setup with JWT
Source: https://developer.box.com/guides/authentication/jwt/jwt-setup

Create a Server app with JWT, generate or upload a public/private keypair, and configure access level, scopes, and CORS domains.

This guide walks you through JWT server authentication for a Box Platform app: create the app, upload a keypair, and authorize the app in your enterprise.

A Platform App can be set up to use server-side authentication with
<Link href="/guides/authentication/jwt">JWT</Link>.

<Card href={localizeLink("/guides/authentication/jwt")} title="Learn how JWT authentication works" />

## Prerequisites

To set up a Platform App using JWT, you need to ensure
you have access to the [Developer Console][devconsole] from your Box enterprise
account. Alternatively, you may sign up for a [developer account][devaccount].

<SignupCTA>
  Don't have a Box account yet? A free developer account gives you access to the Developer Console, where you can create and configure JWT applications.
</SignupCTA>

## App creation steps

### Create a Server Authentication app

1. Log into Box and go to the [Developer Console][devconsole].
2. Select **New App**.
3. Select **Server** as the app type.
4. Select **JWT** under **Select Method**.
5. Select **Create**.

### Select JWT as the authentication method

The **Create a New App** dialog preselects **Client Credentials Grant**, so you
have to choose **JWT** yourself before you create the app.

The **Switch server app auth type (CCG or JWT)** setting decides whether you can
change the method afterward. It is enabled by default for free developer
accounts, where you can also convert an existing Client Credentials Grant app:
open the **Configuration** tab and change the authentication method to **JWT**.
It is disabled by default for enterprises, where the method is fixed once the
app exists.

<Info>
  When switching is enabled, you can change between JWT and
  <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>
  at any time from the **Configuration** tab. See
  <Link href="/guides/authentication/switch-server-auth-type">Switch between CCG and JWT</Link>
  for details on credential handling and downtime considerations.
</Info>

## Public and private key pair

Once your app is configured to use JWT, a key pair can be generated via the
**Configuration** tab in the [Developer Console][devconsole]. Alternatively, you can generate your
own and supply Box with the public key. Regardless of the method you select,
your Box account needs to have [2FA][2fa] enabled for security purposes.

<Note>
  A maximum of two key pairs can be created.
</Note>

### Generate a keypair (recommended)

If you would like to use a Box generated keypair, navigate to the
[Developer Console][devconsole] where you can generate a configuration file.
This file includes a public/private keypair and a number of other application
details that are necessary for authentication.

To generate this file, navigate to the **Configuration** tab of the
[Developer Console][devconsole] and scroll down to the
**Add and Manage Public Keys** section.

<Frame>
  <img alt="Add and Manage keys" />
</Frame>

Select **Generate a Public/Private Keypair** to have Box generate a keypair for
you. This triggers the download of a JSON configuration file that holds your
client secret, private key, and passphrase. Store the file securely outside
source control, such as in a secrets manager, and load it at runtime.

<Danger>
  For security reasons, Box does not store your private key. If you lose your
  private key, you need to reset the entire keypair.
</Danger>

### Manually add keypair

Alternatively, you may generate your own keypair and upload the public key to
the [Developer Console][devconsole].

To create a keypair using OpenSSL, open a terminal window and run the
following commands.

```shell theme={null}
openssl genrsa -des3 -out private.pem 2048
openssl rsa -in private.pem -outform PEM -pubout -out public.pem
```

<Info>
  **For Windows Systems**

  Windows users can install and use the [Cygwin][cygwin] package to run OpenSSL.
</Info>

Then, navigate to the configuration tab for your application within the
[Developer console][devconsole] and scroll down to the
**Add and Manage Public Keys** section.

<Frame>
  <img alt="Add and Manage keys" />
</Frame>

Select **Add a Public Key**, enter the public key generated using the steps
above, and select **Verify and Save**.

## App authorization

Server authentication applications must be authorized before use. The authorization process depends on your account type.

**Free developer accounts**: Your app is automatically authorized when you create it. If authorization did not complete, the **Configuration** tab displays a prompt to authorize the app.

**Enterprise accounts**: After you create the app, the **Configuration** tab prompts you to submit the app for admin approval.

**Enterprise admins and co-admins**: The **Configuration** tab lets you authorize the app directly after creation.

<Card href="/guides/authorization/platform-app-approval" title="Learn more about the authorization process" />

## Basic configuration

### Application access

An application's access level determines which users and content your app may
access. By default, an application can only successfully interact with the
content of its <Link href="/guides/getting-started/users#service-account">Service Account</Link> and any <Link href="/guides/getting-started/users">App Users</Link>.
To access existing Managed Users of an
enterprise and groups that were not created by
the app itself, navigate to the **App Access Level**
setting accessible on the **Configuration** tab of the
[Developer console][devconsole] and set
to **App + Enterprise Access**. Otherwise, access to such
Managed Users and groups is blocked.

<Frame>
  <img alt="App access level" />
</Frame>

### Application scopes

An application's scopes determine which endpoints and resources an application
can successfully call. See the <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes guide</Link> for detailed information
on each option.

<Frame>
  <img alt="App scopes" />
</Frame>

### CORS domains

If your application makes API calls from front-end browser code in
Javascript, the domain that these calls are made from needs to be
added to an allow-list due to [Cross Origin Resource Sharing][cors],
also known as CORS. If all requests are made from server-side code,
you may skip this section.

To add the full URI(s) to the allow-list, navigate to the **CORS Domain**
section at the bottom of the **Configuration** tab in the
[Developer console][devconsole].

<Frame>
  <img alt="App CORS config" />
</Frame>

[devconsole]: https://app.box.com/developers/console

[devaccount]: https://account.box.com/signup/n/developer

[devtoken]: /guides/authentication/tokens/developer-tokens

[cors]: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

[cygwin]: http://www.cygwin.com/

[app-auth]: https://support.box.com/hc/en-us/articles/360043697174-Authorizing-Apps-in-the-Box-App-Approval-Process

[2fa]: https://support.box.com/hc/en-us/articles/360043697154-Two-Factor-Authentication-Set-Up-for-Your-Account

[ccg]: /guides/authentication/jwt/without-sdk/#client-credentials-grant

<RelatedLinks title="RELATED GUIDES" />


# User access tokens
Source: https://developer.box.com/guides/authentication/jwt/user-access-tokens

Request an access token that belongs to a specific user instead of the Service Account, with and without the Box SDKs.

<RelatedLinks title="REQUIRED GUIDES" />

It is possible for a JWT application to create an Access Token for a specific
user instead of for the <Link href="/guides/getting-started/users#service-account">Service Account</Link>.

## Preconditions

The application must be configured to allow the creation of user Access Tokens.
This setting can be found in the **Configuration** tab of the
[Developer Console][devconsole].

<Frame>
  <img alt="Advanced Features" />
</Frame>

Additionally, the authenticated user needs to be a user with Admin permissions,
meaning either an Admin, Co-Admin, or Service Account. See our guide on
<Link href="/guides/getting-started/users">User Types</Link> for more details.

## User access tokens with SDKs

To create a Box SDK client that authenticates as a specific user, follow the
steps described in the <Link href="/guides/authentication/jwt/with-sdk">JWT with SDK guide</Link>,
but create a user client instead of an "Enterprise" client.

<CodeGroup>
  ```csharp .Net theme={null}
  var userId = "12345";
  var sdk = new BoxJWTAuth(config);
  var token = sdk.UserToken(appUserID);
  BoxClient client = sdk.UserClient(userToken, userId);
  ```

  ```java Java theme={null}
  String userId = "12345";
  BoxDeveloperEditionAPIConnection api = new BoxDeveloperEditionAPIConnection.getAppUserConnection(userId, config)
  ```

  ```python Python theme={null}
  user = client.user(user_id='12345')

  auth = JWTAuth(
      client_id='[CLIENT_ID]',
      client_secret='[CLIENT_SECRET]',
      user=app_user,
      jwt_key_id='[JWT_KEY_ID]',
      rsa_private_key_file_sys_path='[CERT.PEM]',
      rsa_private_key_passphrase='[PASSPHRASE]'
  )
  auth.authenticate_user()
  user_client = Client(auth)
  ```

  ```js Node theme={null}
  var sdk = BoxSDK.getPreconfiguredInstance(config);
  var client = sdk.getAppAuthClient('user', '12345');
  ```
</CodeGroup>

<Card href={localizeLink("/guides/authentication/jwt/with-sdk")} title="Learn more about using the Box SDKs with JWT" />

## User access tokens without SDKs

To create a user Access Token that authenticates as a specific user, follow the
steps as described in the
<Link href="/guides/authentication/jwt/without-sdk">JWT without SDK guide</Link> but instead of creating
a claim for the enterprise, create one for a specific user ID.

<CodeGroup>
  ```csharp .Net theme={null}
  var userId = "12345";

  var claims = new List<Claim>{
      new Claim("sub", userId),
      new Claim("box_sub_type", "user"),
      new Claim("jti", jti),
  };
  ```

  ```java Java theme={null}
  String userId = "12345";

  JwtClaims claims = new JwtClaims();
  claims.setIssuer(config.boxAppSettings.clientID);
  claims.setAudience(authenticationUrl);
  claims.setSubject(userId);
  claims.setClaim("box_sub_type", "user");
  claims.setGeneratedJwtId(64);
  claims.setExpirationTimeMinutesInTheFuture(0.75f);
  ```

  ```python Python theme={null}
  user_id = '12345'

  claims = {
      'iss': config['boxAppSettings']['clientID'],
      'sub': user_id,
      'box_sub_type': 'user',
      'aud': authentication_url,
      'jti': secrets.token_hex(64),
      'exp': round(time.time()) + 45
  }
  ```

  ```js Node theme={null}
  let user_id = '12345';

  let claims = {
      iss: config.boxAppSettings.clientID,
      sub: user_id,
      box_sub_type: "user",
      aud: authenticationUrl,
      jti: crypto.randomBytes(64).toString("hex"),
      exp: Math.floor(Date.now() / 1000) + 45
  };
  ```

  ```ruby Ruby theme={null}
  user_id = '12345'

  claims = {
    iss: config['boxAppSettings']['clientID'],
    sub: user_id,
    box_sub_type: 'user',
    aud: authentication_url,
    jti: SecureRandom.hex(64),
    exp: Time.now.to_i + 45
  }
  ```

  ```php PHP theme={null}
  $userId = '12345';

  $claims = [
    'iss' => $config->boxAppSettings->clientID,
    'sub' => $userId,
    'box_sub_type' => 'user',
    'aud' => $authenticationUrl,
    'jti' => base64_encode(random_bytes(64)),
    'exp' => time() + 45,
    'kid' => $config->boxAppSettings->appAuth->publicKeyID
  ];
  ```
</CodeGroup>

<Card href={localizeLink("/guides/authentication/jwt/with-sdk")} title="Learn more about manually using JWT authentication" />

[devconsole]: https://app.box.com/developers/console

<RelatedLinks title="RELATED GUIDES" />


# JWT with SDKs
Source: https://developer.box.com/guides/authentication/jwt/with-sdk

Read a config.json file and initialize a Box SDK client that handles JWT assertions and token renewal for you.

<RelatedLinks title="REQUIRED GUIDES" />

The official Box SDKs have built-in support for JWT authentication.

This guide will take you through user authentication using JWT with the use
of the Box SDKs. JWT authentication is designed for working directly with the
Box API without requiring a user to redirect through Box to authorize your
application.

## Overview

To complete a JWT authorization the following steps need to be completed.

1. Read the configuration file
2. Initialize an SDK client

At the end of this flow, the application has a Box SDK client that can be used to
make API calls on behalf of the application.

<Note>
  The default method of authentication through JWT is inherently tied to the Service
  Account for the application. Any API call made with this token will seem to
  come from this application and will not have access to files and folders from
  other users without explicitly getting access to them.
</Note>

## Prerequisites

Before we can get started, you will need to have completed the following steps.

* Create a Box Application within the developer console
* Create and download the private key configuration file for your application and save it as `config.json`
* Ensure your Box Application is approved for usage within your enterprise

## 1. Read JSON configuration

After creating a Box Application there should be a `config.json` file containing
the application's private key and other details. The following is an example.

```json config.json theme={null}
{
  "boxAppSettings": {
    "clientID": "abc...123",
    "clientSecret": "def...234",
    "appAuth": {
      "publicKeyID": "abcd1234",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n....\n-----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "ghi...345"
    }
  },
  "enterpriseID": "1234567"
}
```

If your SDK takes the configuration values as individual parameters instead of
reading the file, map the `config.json` fields as follows.

| `config.json` field | Value |
| - | - |
| `boxAppSettings.clientID` | Client ID |
| `boxAppSettings.clientSecret` | Client secret |
| `boxAppSettings.appAuth.publicKeyID` | JWT key ID (public key ID) |
| `boxAppSettings.appAuth.privateKey` | Private key |
| `boxAppSettings.appAuth.passphrase` | Private key passphrase |
| `enterpriseID` | Enterprise ID, used to authenticate as the Service Account |

To use this object in the application it needs to be read from file.

<CodeGroup>
  ```csharp .Net theme={null}
  var reader = new StreamReader("path/to/config.json");
  var json = reader.ReadToEnd();
  var config = BoxConfig.CreateFromJsonString(json);
  ```

  ```java Java theme={null}
  Reader reader = new FileReader("path/to/config.json");
  BoxConfig config = BoxConfig.readFrom(reader);
  ```

  ```python Python theme={null}
  from boxsdk import JWTAuth

  config = JWTAuth.from_settings_file('path/to/config.json')
  ```

  ```js Node theme={null}
  var config = require("path/to/config.json");
  ```
</CodeGroup>

<Info>
  **Parsing JSON**

  In some programming languages there is more than one way to read and parse
  JSON from a file. Refer to guides on your preferred programming language for
  more complete guides, including error handling.
</Info>

## 2. Initialize SDK client

The next step is to configure the Box SDK with the configuration and then
initialize the client to connect as the application.

<CodeGroup>
  ```csharp .Net theme={null}
  var sdk = new BoxJWTAuth(config);
  var token = sdk.AdminToken();
  BoxClient client = sdk.AdminClient(token);
  ```

  ```java Java theme={null}
  BoxDeveloperEditionAPIConnection api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(config);
  ```

  ```python Python theme={null}
  client = Client(config)
  ```

  ```js Node theme={null}
  var sdk = BoxSDK.getPreconfiguredInstance(config);
  var client = sdk.getAppAuthClient("enterprise");
  ```
</CodeGroup>

<Warning>
  **Service Accounts**

  At this point the application is authenticated as an application user, not as
  a managed or app user. Head over to our guide on <Link href="/guides/getting-started/users">User
  Types</Link> to learn more about the different types
  of users.

  **Summary**

  By now the application should be able to authorize an application using JWT
  with any of our official SDKs, by using the following steps.

  1. Read the configuration file
  2. Initialize an SDK client

  To learn how to use this client head over to the guide on <Link href="/guides/api-calls">Making API
  calls</Link>.

  **Using SDKs and JSON Web Tokens**

  To learn more about JWT for each SDK head over to:

  * [.Net][.Net]

  * [Java][Java]

  * [Python][Python]

  * [Node][Node]

  * [IOS][IOS]
</Warning>

[.Net]: https://github.com/box/box-windows-sdk-v2/blob/legacy/docs/authentication.md#server-auth-with-jwt

[Java]: https://github.com/box/box-java-sdk/blob/legacy/doc/authentication.md#server-authentication-with-jwt

[Python]: https://github.com/box/box-python-sdk/blob/legacy/docs/usage/authentication.md#server-auth-with-jwt

[Node]: https://github.com/box/box-node-sdk/blob/legacy/docs/authentication.md#server-auth-with-jwt

[IOS]: https://github.com/box/box-ios-sdk/blob/legacy/BoxSDK/docs/usage/authentication.md#server-auth-with-jwt

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# JWT without SDKs
Source: https://developer.box.com/guides/authentication/jwt/without-sdk

Decrypt your private key, build and sign a JWT assertion, and exchange it for an access token without using a Box SDK.

<RelatedLinks title="REQUIRED GUIDES" />

This guide takes you through JWT authentication without using a Box SDK.
JWT does not require end-user interaction and is designed to authenticate
directly with the Box API.

To learn how to use this token visit our guide on <Link href="/guides/api-calls">making API
calls</Link>.

<Note>
  By default, the Access Token acquired with JWT is tied to the Service
  Account for the application. Any API call made with this token will come
  from the application. This account does not have access to any existing files
  or folders until the application's Service Account is added as a collaborator.

  It is possible to <Link href="/guides/authentication/oauth2/as-user">act as another user</Link>
  using the `as-user` header or by requesting a
  <Link href="/guides/authentication/jwt/user-access-tokens">User Access Token</Link>.
</Note>

## Using a key pair

Follow the steps below if you would like to verify your application's identity
using a public and private key pair.

### Prerequisites

* A Platform Application using JWT authentication within the [Developer Console][devconsole]
* A private key configuration file named `config.json`, which can be downloaded from the configuration tab of the [Developer Console][devconsole]
* Ensure your application is <Link href="/guides/authorization">authorized</Link> within the Box Admin Console

### 1. Read JSON configuration

Your `config.json` file contains the application's private key and other
details necessary to authenticate. The following is an example of this file.

```json config.json theme={null}
{
  "boxAppSettings": {
    "clientID": "abc...123",
    "clientSecret": "def...234",
    "appAuth": {
      "publicKeyID": "abcd1234",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\n....\n-----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "ghi...345"
    }
  },
  "enterpriseID": "1234567"
}
```

To use this object in the application it needs to be read from file.

<CodeGroup>
  ```csharp .Net theme={null}
  using System;
  using System.IO;
  using Newtonsoft.Json;

  class Config
  {
      public class BoxAppSettings {
          public class AppAuth {
              public string privateKey { get; set; }
              public string passphrase { get; set; }
              public string publicKeyID { get; set; }
          }
          public string clientID { get; set; }
          public string clientSecret { get; set; }
          public AppAuth appAuth { get; set; }

      }
      public string enterpriseID { get; set; }
      public BoxAppSettings boxAppSettings { get; set; }
  }

  var reader = new StreamReader("config.json");
  var json = reader.ReadToEnd();

  var config = JsonConvert.DeserializeObject<Config>(json);
  ```

  ```java Java theme={null}
  import java.io.FileReader;

  import com.google.gson.Gson;
  import com.google.gson.GsonBuilder;

  class Config {
      class BoxAppSettings {
          class AppAuth {
              String privateKey;
              String passphrase;
              String publicKeyID;
          }

          String clientID;
          String clientSecret;
          AppAuth appAuth;
      }

      BoxAppSettings boxAppSettings;
      String enterpriseID;
  }

  FileReader reader = new FileReader("config.json");

  Gson gson = new GsonBuilder().create();
  Config config = (Config) gson.fromJson(reader, Config.class);
  ```

  ```python Python 3 theme={null}
  import json
  import os

  config = json.load(open('config.json'))
  ```

  ```js Node  theme={null}
  const fs = require("fs");

  const config = JSON.parse(fs.readFileSync("config.json"));
  ```

  ```ruby Ruby theme={null}
  require 'json'

  config = JSON.parse(
    File.read('config.json')
  )
  ```

  ```php PHP theme={null}
  $json = file_get_contents('config.json');
  $config = json_decode($json);
  ```
</CodeGroup>

<Info>
  **Parsing JSON**

  In some programming languages there is more than one way to read and parse
  JSON from a file. Refer to guides on your preferred programming language for
  more complete guides, including error handling.
</Info>

### 2. Decrypt private key

To create the JWT assertion the application needs the private key from the
configuration object. This private key is encrypted and requires a passcode to
unlock. Both the encrypted key and passcode are provided in the configuration
object.

<CodeGroup>
  ```csharp .Net theme={null}
  using System.Security.Cryptography;
  using Org.BouncyCastle.OpenSsl;
  using Org.BouncyCastle.Crypto.Parameters;
  using Org.BouncyCastle.Math;

  // https://www.bouncycastle.org/csharp/index.html
  class PasswordFinder : IPasswordFinder
  {
      private string password;
      public PasswordFinder(string _password) { password = _password; }
      public char[] GetPassword() { return password.ToCharArray(); }
  }

  var appAuth = config.boxAppSettings.appAuth;
  var stringReader = new StringReader(appAuth.privateKey);
  var passwordFinder = new PasswordFinder(appAuth.passphrase);
  var pemReader = new PemReader(stringReader, passwordFinder);
  var keyParams = (RsaPrivateCrtKeyParameters) pemReader.ReadObject();

  public RSA CreateRSAProvider(RSAParameters rp)
  {
      var rsaCsp = RSA.Create();
      rsaCsp.ImportParameters(rp);
      return rsaCsp;
  }

  public RSAParameters ToRSAParameters(RsaPrivateCrtKeyParameters privKey)
  {
      RSAParameters rp = new RSAParameters();
      rp.Modulus = privKey.Modulus.ToByteArrayUnsigned();
      rp.Exponent = privKey.PublicExponent.ToByteArrayUnsigned();
      rp.P = privKey.P.ToByteArrayUnsigned();
      rp.Q = privKey.Q.ToByteArrayUnsigned();
      rp.D = ConvertRSAParametersField(privKey.Exponent, rp.Modulus.Length);
      rp.DP = ConvertRSAParametersField(privKey.DP, rp.P.Length);
      rp.DQ = ConvertRSAParametersField(privKey.DQ, rp.Q.Length);
      rp.InverseQ = ConvertRSAParametersField(privKey.QInv, rp.Q.Length);
      return rp;
  }

  public byte[] ConvertRSAParametersField(BigInteger n, int size)
  {
      byte[] bs = n.ToByteArrayUnsigned();
      if (bs.Length == size)
          return bs;
      if (bs.Length > size)
          throw new ArgumentException("Specified size too small", "size");
      byte[] padded = new byte[size];
      Array.Copy(bs, 0, padded, size - bs.Length, bs.Length);
      return padded;
  }

  var key = CreateRSAProvider(ToRSAParameters(keyParams));
  ```

  ```java Java theme={null}
  import java.io.StringReader;
  import java.security.PrivateKey;
  import java.security.Security;

  import org.bouncycastle.asn1.pkcs.PrivateKeyInfo;
  import org.bouncycastle.jce.provider.BouncyCastleProvider;
  import org.bouncycastle.openssl.PEMParser;
  import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;
  import org.bouncycastle.openssl.jcajce.JceOpenSSLPKCS8DecryptorProviderBuilder;
  import org.bouncycastle.operator.InputDecryptorProvider;
  import org.bouncycastle.pkcs.PKCS8EncryptedPrivateKeyInfo;

  // https://www.bouncycastle.org/java.html
  Security.addProvider(new BouncyCastleProvider());

  PEMParser pemParser = new PEMParser(
      new StringReader(config.boxAppSettings.appAuth.privateKey)
  );
  Object keyPair = pemParser.readObject();
  pemParser.close();

  char[] passphrase = config.boxAppSettings.appAuth.passphrase.toCharArray();
  JceOpenSSLPKCS8DecryptorProviderBuilder decryptBuilder =
      new JceOpenSSLPKCS8DecryptorProviderBuilder().setProvider("BC");
  InputDecryptorProvider decryptProvider
      = decryptBuilder.build(passphrase);
  PrivateKeyInfo keyInfo
      = ((PKCS8EncryptedPrivateKeyInfo) keyPair).decryptPrivateKeyInfo(decryptProvider);

  PrivateKey key = (new JcaPEMKeyConverter()).getPrivateKey(keyInfo);
  ```

  ```python Python 3 theme={null}
  from cryptography.hazmat.backends import default_backend
  from cryptography.hazmat.primitives.serialization import load_pem_private_key

  appAuth = config["boxAppSettings"]["appAuth"]
  privateKey = appAuth["privateKey"]
  passphrase = appAuth["passphrase"]

  # https://cryptography.io/en/latest/
  key = load_pem_private_key(
      data=privateKey.encode('utf8'),
      password=passphrase.encode('utf8'),
      backend=default_backend(),
  )
  ```

  ```js Node  theme={null}
  let key = {
      key: config.boxAppSettings.appAuth.privateKey,
      passphrase: config.boxAppSettings.appAuth.passphrase,
  };
  ```

  ```ruby Ruby theme={null}
  require "openssl"

  appAuth = config['boxAppSettings']['appAuth']
  key = OpenSSL::PKey::RSA.new(
    appAuth['privateKey'],
    appAuth['passphrase']
  )
  ```

  ```php PHP theme={null}
  $private_key = $config->boxAppSettings->appAuth->privateKey;
  $passphrase = $config->boxAppSettings->appAuth->passphrase;
  $key = openssl_pkey_get_private($private_key, $passphrase);
  ```
</CodeGroup>

<Info>
  **An alternative to loading private key from file**

  The application might not want to keep both the private key and password
  stored on disk. An alternative option would be to pass in the password as an
  environment variable, separating the private key from the token used to unlock
  the key.
</Info>

### 3. Create JWT assertion

To authenticate to the Box API the application needs to create a signed JWT
assertion that can be exchanged for an Access Token.

A JWT assertion is an encrypted JSON object, consisting of a
`header`, `claims`, and `signature`. Let's start by creating the `claims`,
sometimes also referred to as the `payload`.

<CodeGroup>
  ```csharp .Net theme={null}
  using System.IdentityModel.Tokens.Jwt;
  using System.Security.Claims;
  using System.Collections.Generic;

  byte[] randomNumber = new byte[64];
  RandomNumberGenerator.Create().GetBytes(randomNumber);
  var jti = Convert.ToBase64String(randomNumber);

  DateTime expirationTime = DateTime.UtcNow.AddSeconds(45);

  var claims = new List<Claim>{
      new Claim("sub", config.enterpriseID),
      new Claim("box_sub_type", "enterprise"),
      new Claim("jti", jti),
  };
  ```

  ```java Java theme={null}
  import org.jose4j.jwt.JwtClaims;

  String authenticationUrl = "https://api.box.com/oauth2/token";

  JwtClaims claims = new JwtClaims();
  claims.setIssuer(config.boxAppSettings.clientID);
  claims.setAudience(authenticationUrl);
  claims.setSubject(config.enterpriseID);
  claims.setClaim("box_sub_type", "enterprise");
  claims.setGeneratedJwtId(64);
  claims.setExpirationTimeMinutesInTheFuture(0.75f);
  ```

  ```python Python 3 theme={null}
  import time
  import secrets

  authentication_url = 'https://api.box.com/oauth2/token'

  claims = {
      'iss': config['boxAppSettings']['clientID'],
      'sub': config['enterpriseID'],
      'box_sub_type': 'enterprise',
      'aud': authentication_url,
      'jti': secrets.token_hex(64),
      'exp': round(time.time()) + 45
  }
  ```

  ```js Node  theme={null}
  const crypto = require("crypto");

  const authenticationUrl = "https://api.box.com/oauth2/token";

  let claims = {
      iss: config.boxAppSettings.clientID,
      sub: config.enterpriseID,
      box_sub_type: "enterprise",
      aud: authenticationUrl,
      jti: crypto.randomBytes(64).toString("hex"),
      exp: Math.floor(Date.now() / 1000) + 45,
  };
  ```

  ```ruby Ruby theme={null}
  require 'securerandom'

  authentication_url = 'https://api.box.com/oauth2/token'

  claims = {
    iss: config['boxAppSettings']['clientID'],
    sub: config['enterpriseID'],
    box_sub_type: 'enterprise',
    aud: authentication_url,
    jti: SecureRandom.hex(64),
    exp: Time.now.to_i + 45
  }
  ```

  ```php PHP theme={null}
  $authenticationUrl = 'https://api.box.com/oauth2/token';

  $claims = [
    'iss' => $config->boxAppSettings->clientID,
    'sub' => $config->enterpriseID,
    'box_sub_type' => 'enterprise',
    'aud' => $authenticationUrl,
    'jti' => base64_encode(random_bytes(64)),
    'exp' => time() + 45,
    'kid' => $config->boxAppSettings->appAuth->publicKeyID
  ];
  ```
</CodeGroup>

| Parameter | Type | Description |
| - | - | - |
| `iss`, required | String | The Box Application's OAuth client ID |
| `sub`, required | String | The Box Enterprise ID if this app is to act on behalf of the Service Account of that application, or the User ID if this app wants to act on behalf of another user. |
| `box_sub_type`, required | String | `enterprise` or `user` depending on the type of token being requested in the `sub` claim |
| `aud`, required | String | Always `https://api.box.com/oauth2/token` |
| `jti`, required | String | A universally unique identifier specified by the application for this JWT. A unique string of at least 16 characters and at most 128 characters. |
| `exp`, required | Integer | The Unix time when this JWT is to expire. Can be set to a maximum value of 60 seconds beyond the issue time. It is recommended to set this to less than the maximum allowed. |
| `iat`, optional | Integer | Issued at time. The token cannot be used before this time. |
| `nbf`, optional | Integer | Not before. Specifies when the token will start being valid. |

Next, these claims need to be signed using the private key. Depending on the
language and library used, the `header` of the JWT is configured by defining the
encryption algorithm and the ID of the public key used to sign the claims.

<CodeGroup>
  ```csharp .Net theme={null}
  using Microsoft.IdentityModel.Tokens;

  String authenticationUrl = "https://api.box.com/oauth2/token";

  var payload = new JwtPayload(
      config.boxAppSettings.clientID,
      authenticationUrl,
      claims,
      null,
      expirationTime
  );

  var credentials = new SigningCredentials(
      new RsaSecurityKey(key),
      SecurityAlgorithms.RsaSha512
  );
  var header = new JwtHeader(signingCredentials: credentials);

  var jst = new JwtSecurityToken(header, payload);
  var tokenHandler = new JwtSecurityTokenHandler();
  string assertion = tokenHandler.WriteToken(jst);
  ```

  ```java Java theme={null}
  import org.jose4j.jws.AlgorithmIdentifiers;
  import org.jose4j.jws.JsonWebSignature;

  JsonWebSignature jws = new JsonWebSignature();
  jws.setPayload(claims.toJson());
  jws.setKey(key);

  jws.setAlgorithmHeaderValue(AlgorithmIdentifiers.RSA_USING_SHA512);
  jws.setHeader("typ", "JWT");
  jws.setHeader("kid", config.boxAppSettings.appAuth.publicKeyID);
  String assertion = jws.getCompactSerialization();
  ```

  ```python Python 3 theme={null}
  import jwt

  keyId = config['boxAppSettings']['appAuth']['publicKeyID']

  assertion = jwt.encode(
      claims,
      key,
      algorithm='RS512',
      headers={
          'kid': keyId
      }
  )
  ```

  ```js Node  theme={null}
  const jwt = require("jsonwebtoken");

  let keyId = config.boxAppSettings.appAuth.publicKeyID;

  let headers = {
      algorithm: "RS512",
      keyid: keyId,
  };

  let assertion = jwt.sign(claims, key, headers);
  ```

  ```ruby Ruby theme={null}
  require 'jwt'
  keyId = appAuth['publicKeyID']
  assertion = JWT.encode(claims, key, 'RS512', { kid: keyId })
  ```

  ```php PHP theme={null}
  use \Firebase\JWT\JWT;
  $assertion = JWT::encode($claims, $key, 'RS512');
  ```
</CodeGroup>

For the header the following parameters are supported.

| Parameter | Type | Description |
| - | - | - |
| `algorithm`, required | String | The encryption algorithm used to sign the JWT claim. This can be one of RS256, RS384, or RS512. |
| `keyid`, required | String | The ID of the public key used to sign the JWT. Not required, though essential when multiple key pairs are defined for an application. |

<Info>
  Using JWT libraries

  Signing your own JWT can be a complicated and painful process. Luckily, the
  hard work has already been done for you and libraries exist in pretty much
  every language. Head over to <Link href="https://jwt.io/">JWT.io</Link> for an overview.
</Info>

### 4. Request Access Token

The final step is to exchange the short lived JWT assertion for a more long
lived Access Token by calling the token endpoint with the
assertion as a parameter.

<CodeGroup>
  ```csharp .Net theme={null}
  using System.Net;
  using System.Net.Http;

  var content = new FormUrlEncodedContent(new[]
  {
      new KeyValuePair<string, string>(
          "grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer"),
      new KeyValuePair<string, string>(
          "assertion", assertion),
      new KeyValuePair<string, string>(
          "client_id", config.boxAppSettings.clientID),
      new KeyValuePair<string, string>(
          "client_secret", config.boxAppSettings.clientSecret)
  });

  var client = new HttpClient();
  var response = client.PostAsync(authenticationUrl, content).Result;

  class Token
  {
      public string access_token { get; set; }
  }

  var data = response.Content.ReadAsStringAsync().Result;
  var token = JsonConvert.DeserializeObject<Token>(data);
  var accessToken = token.access_token;
  ```

  ```java Java theme={null}
  import java.util.ArrayList;
  import java.util.List;

  import org.apache.http.HttpEntity;
  import org.apache.http.NameValuePair;
  import org.apache.http.client.entity.UrlEncodedFormEntity;
  import org.apache.http.client.methods.CloseableHttpResponse;
  import org.apache.http.client.methods.HttpPost;
  import org.apache.http.impl.client.CloseableHttpClient;
  import org.apache.http.impl.client.HttpClientBuilder;
  import org.apache.http.message.BasicNameValuePair;
  import org.apache.http.util.EntityUtils;

  List<NameValuePair> params = new ArrayList<NameValuePair>();

  params.add(new BasicNameValuePair(
      "grant_type", "urn:ietf:params:oauth:grant-type:jwt-bearer"));
  params.add(new BasicNameValuePair(
      "assertion", assertion));
  params.add(new BasicNameValuePair(
      "client_id", config.boxAppSettings.clientID));
  params.add(new BasicNameValuePair(
      "client_secret", config.boxAppSettings.clientSecret));

  CloseableHttpClient httpClient =
      HttpClientBuilder.create().disableCookieManagement().build();
  HttpPost request = new HttpPost(authenticationUrl);
  request.setEntity(new UrlEncodedFormEntity(params));
  CloseableHttpResponse httpResponse = httpClient.execute(request);
  HttpEntity entity = httpResponse.getEntity();
  String response = EntityUtils.toString(entity);
  httpClient.close();

  class Token {
      String access_token;
  }

  Token token = (Token) gson.fromJson(response, Token.class);
  String accessToken = token.access_token;
  ```

  ```python Python 3 theme={null}
  import json
  import requests

  params = {
      'grant_type': 'urn:ietf:params:oauth:grant-type:jwt-bearer',
      'assertion': assertion,
      'client_id': config['boxAppSettings']['clientID'],
      'client_secret': config['boxAppSettings']['clientSecret']
  }
  response = requests.post(authentication_url, params)
  access_token = response.json()['access_token']
  ```

  ```js Node  theme={null}
  const axios = require("axios");
  const querystring = require("querystring");

  let accessToken = await axios
      .post(
          authenticationUrl,
          querystring.stringify({
              grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
              assertion: assertion,
              client_id: config.boxAppSettings.clientID,
              client_secret: config.boxAppSettings.clientSecret,
          })
      )
      .then((response) => response.data.access_token);
  ```

  ```ruby Ruby theme={null}
  require 'json'
  require 'uri'
  require 'net/https'

  params = URI.encode_www_form({
    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    assertion: assertion,
    client_id: config['boxAppSettings']['clientID'],
    client_secret: config['boxAppSettings']['clientSecret']
  })

  uri = URI.parse(authentication_url)
  http = Net::HTTP.start(uri.host, uri.port, use_ssl: true)
  request = Net::HTTP::Post.new(uri.request_uri)
  request.body = params
  response = http.request(request)

  access_token = JSON.parse(response.body)['access_token']
  ```

  ```php PHP theme={null}
  use GuzzleHttp\Client;

  $params = [
    'grant_type' => 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    'assertion' => $assertion,
    'client_id' => $config->boxAppSettings->clientID,
    'client_secret' => $config->boxAppSettings->clientSecret
  ];

  $client = new Client();
  $response = $client->request('POST', $authenticationUrl, [
    'form_params' => $params
  ]);

  $data = $response->getBody()->getContents();
  $access_token = json_decode($data)->access_token;
  ```
</CodeGroup>

## Code samples

The code in this guide is available on [GitHub][samples].

[samples]: https://github.com/box-community/samples-docs-authenticate-with-jwt-api

[devconsole]: https://app.box.com/developers/console

[configfile]: /guides/authentication/jwt/jwt-setup/#jwt-keypair

[ccg]: /guides/authentication/jwt/without-sdk/#client-credentials-grant

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# as-user header
Source: https://developer.box.com/guides/authentication/oauth2/as-user

Act on behalf of another user from an OAuth 2.0 app, and the Developer Console settings and permissions this requires.

<RelatedLinks title="REQUIRED GUIDES" />

It is possible for an OAuth 2.0 application to act on behalf of another user
through the `as-user` header.

```sh theme={null}
curl https://api.box.com/2.0/folders/0 \
    -H "as-user: [USER_ID]" \
    -H "authorization: Bearer [ACCESS_TOKEN]"
```

<Info>
  In this situation the user ID is the Box identifier for a user. User IDs can be
  found for any user via the `GET /users` endpoint, which is only available to
  admins, or by calling the `GET /users/me` endpoint with an authenticated user session.
</Info>

## Preconditions

Using the `as-user` header has a few requirements. Firstly, the application
needs to be configured to perform actions as users in the [Developer
Console][devconsole].

<Frame>
  <img alt="Advanced Features" />
</Frame>

Additionally, the authenticated user needs to be a user with admin permissions,
meaning either an admin, co-admin, or service account. Co-admin users will also
need the 'Manage Users' permission scope. See our guide on [User
Types](/guides/getting-started/users) for more details.

## as-user using SDKs

<CodeGroup>
  ```csharp .NET theme={null}
  var user_client = new BoxClient(config, session, asUser: '[USER_ID]');
  ```

  ```java Java theme={null}
  client.asUser("[USER_ID]");
  // client.asSelf();
  ```

  ```python Python theme={null}
  user_to_impersonate = client.user(user_id='[USER_ID]')
  user_client = client.as_user(user_to_impersonate)
  ```

  ```js Node theme={null}
  client.asUser('[USER_ID]');
  // client.asSelf();
  ```
</CodeGroup>

<Warning>
  Please note that some of our SDKs create new clients for the other user, while
  others modify the existing client and provide a way to return to a state where
  the client authenticates for the original user itself.
</Warning>

[devconsole]: https://app.box.com/developers/console

<RelatedLinks title="RELATED GUIDES" />


# OAuth 2.0 authentication
Source: https://developer.box.com/guides/authentication/oauth2/index

How the OAuth 2.0 flow works on Box, from the authorization URL to the access token your app uses on behalf of a signed-in user.

<RelatedLinks title="REQUIRED GUIDES" />

Client-side OAuth 2.0 is one of the easiest ways to authenticate a user for the
Box API. It is an [open standard](https://oauth.net/2/) designed to allow users
to provide applications access to their data in other applications.

If you've ever logged in to a website with Twitter, Facebook, or Google you've
most likely used OAuth 2.0.

<Frame>
  <img alt="the OAuth 2.0 flow" />
</Frame>

## How it works

Client-side authentication on Box redirects a user from your application to the
Box web app, where the user logs in and grants your application access to their
data. The flow has four steps:

1. Your application builds an authorization URL from its client ID and a
   registered redirect URI, and sends the user to it.
2. The user logs in to Box and approves the scopes your application asks for.
3. Box redirects the user back to your redirect URI with a short-lived
   authorization code.
4. Your application exchanges that code, along with its client secret, for an
   access token and a refresh token.

Because the token belongs to the person who signed in, your application reaches
exactly the content that user owns or collaborates on, and any content it
creates lives in that user's own account. The
<Link href="/guides/authentication">Authentication</Link> overview compares this
with the server-side methods.

<SignupCTA>
  A free developer account gives you access to the Developer Console, where you can create an OAuth 2.0 application and start authenticating users in minutes.
</SignupCTA>

<Card href={localizeLink("/guides/authentication/oauth2/oauth2-setup")} title="Set up an app with OAuth 2.0" />

<RelatedLinks title="RELATED GUIDES" />


# Setup with OAuth 2.0
Source: https://developer.box.com/guides/authentication/oauth2/oauth2-setup

Create a User app in the Developer Console and configure its redirect URI, scopes, and CORS domains for OAuth 2.0.

<RelatedLinks title="REQUIRED GUIDES" />

A Platform App can be set up to use client-side <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> authentication.

<Card href={localizeLink("/guides/authentication/oauth2")} title="Learn how OAuth 2.0 authentication works" />

## Prerequisites

To set up a Platform App using OAuth 2.0 authentication, you will need to ensure
you have access to the [Developer Console][devconsole] from your Box enterprise
account. Alternatively, you may sign up for a [developer account][devaccount].

<SignupCTA>
  Don't have a Box account yet? A free developer account gives you access to the Developer Console, where you can create and configure OAuth 2.0 applications.
</SignupCTA>

## App creation steps

### Create an OAuth 2.0 app

1. Log into Box and go to the [Developer Console][devconsole].
2. Select **New App**.
3. Select **User** as the app type.
4. Select **Create**.

<Warning>
  Once you create an OAuth 2.0 app, you cannot change it to Server
  Authentication (or the other way around). If you need Server Authentication,
  create a new app and select **Server** instead.
</Warning>

## Basic configuration

Before the application can be used, some additional configuration is
required.

### Redirect URI

During the OAuth 2.0 flow, users are redirected to their browser to
authenticate and then authorize the application to take actions on their behalf.

Prior to redirecting the user, Box verifies that the `redirect_uri` parameter
passed into the <Link href="/reference/get-authorize/#param-redirect_uri">authorization URL</Link> matches one of the redirect
URIs configured for the application. This will be an exact match check, meaning
the URIs must be exactly the same. Localhost and loopback address redirect URIs
will be permitted to redirect to any port, but the scheme, domain, path and query
parameters must match one of the configured URIs.

You can configure these under the OAuth 2.0 Redirect URI section on the
Configuration page in the developer console. These must be valid URIs that are
HTTPS, or a less secure HTTP for localhost or loopback address. We do not
permit duplicate URIs to be saved.

<Warning>
  Starting November 29, 2021, new applications using OAuth 2.0 will
  require the URIs set in the configuration tab of the Developer Console to
  strictly match the one used during redirect. In addition, both new and
  existing applications will gain the ability to add multiple redirect URIs.

  If you configured multiple redirect URIs for the application,
  the authorization URL must include the `redirect_uri` parameter matching one
  of the URIs configured in the developer console.
  If the parameter is not specified, the user will see a `redirect_uri_missing`
  error and will not be redirected back to the app after granting application
  access.

  For existing applications, the deadline to make changes to this URL to avoid
  service disruption is May 13, 2022.
</Warning>

<Frame>
  <img alt="App name form" />
</Frame>

### Application scopes

Scopes define what permissions your application has in order to access data. See
the <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes guide</Link> for detailed information on each option.

<Frame>
  <img alt="App name form" />
</Frame>

### CORS domains

If your application makes API calls from front-end browser code in
Javascript, the domain that these calls are made from will need to be
added to an allow-list due to [Cross Origin Resource Sharing][cors],
also known as CORS. If all requests will be made from server-side code,
you may skip this section.

To add the full URI(s) to the allow-list, navigate to the **CORS Domain**
section at the bottom of the **Configuration** tab in the
[Developer Console][devconsole].

<Frame>
  <img alt="App name form" />
</Frame>

[devconsole]: https://app.box.com/developers/console

[devaccount]: https://account.box.com/signup/n/developer

[devtoken]: /guides/authentication/tokens/developer-tokens

[cors]: https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

<RelatedLinks title="RELATED GUIDES" />


# OAuth 2.0 with SDKs
Source: https://developer.box.com/guides/authentication/oauth2/with-sdk

Walk through the OAuth 2.0 flow using a Box SDK, from configuring the client to exchanging the authorization code for a token.

<RelatedLinks title="REQUIRED GUIDES" />

The Box SDKs have built-in support for client-side OAuth 2.0.

In the process a user is redirected to the Box web app in a browser where they
log in and authorize the application access to their data before they are
redirected back to the application's `redirect_url`. This last step requires the
application to be running on a web server somewhere accessible to the user.

## Overview

To complete an OAuth 2.0 flow the following steps need to be completed.

1. Configure the Box SDK
2. Redirect the user to the Box website
3. The user grants the application access
4. Exchange the authorization code for an access token

At the end of this flow, the application has an Access Token that can be used to
make API calls on behalf of this user.

<Note>
  The access token acquired through OAuth 2.0 is inherently tied to the user who
  authorized the application. Any API call made with this token will seem to
  come from this application, and the user needs to have access to any file or
  folder the application tries to access with this token.
</Note>

## Parameters

| Parameter | Description |
| - | - |
| `CLIENT_ID` | The client ID or API key for the application |
| `CLIENT_SECRET` | The client secret or API secret for the application |
| `REDIRECT_URI` | The redirect URL for your application that a user will be sent to after they have authorized the application. This can be configured in the developer console |

## 1. Configure SDK

The first step is to make sure your environment has been prepared with the SDK of
your choice.

<CodeGroup>
  ```csharp .NET theme={null}
  var redirectUrl = "[REDIRECT_URI]";
  var config = new BoxConfig("[CLIENT_ID]", "[CLIENT_SECRET]", new Uri(redirectUrl));
  var sdk = new BoxClient(config);
  ```

  ```java Java theme={null}
  import com.box.sdk.BoxAPIConnection;

  String authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code";
  ```

  ```python Python theme={null}
  from boxsdk import OAuth2, Client

  auth = OAuth2(
      client_id='[CLIENT_ID]',
      client_secret='[CLIENT_SECRET]'
  )
  ```

  ```js Node theme={null}
  var BoxSDK = require("box-node-sdk");

  var sdk = new BoxSDK({
      clientID: "[CLIENT_ID]",
      clientSecret: "[CLIENT_SECRET]",
  });
  ```
</CodeGroup>

<Card href={localizeLink("/guides/tooling/sdks")} title="Learn more about installing an SDK for your environment" />

## 2. Redirect user

Next, redirect the user to the authorization URL. Most of the SDKs support a
way to get the authorization URL for an SDK client.

<Warning>
  If you configured multiple redirect URIs for the application, the authorization
  URL must include the `redirect_uri` parameter matching one of the URIs
  configured in the developer console. If the parameter is not specified, the
  user will see a `redirect_uri_missing` error and will not be redirected back to
  the app after granting application access.
</Warning>

<CodeGroup>
  ```csharp .NET theme={null}
  var authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code";
  // redirectTo(authorizationUrl);
  ```

  ```java Java theme={null}
  String authorizationUrl = "https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&response_type=code";

  // response.redirect(authorizationUrl);
  ```

  ```python Python theme={null}
  auth_url, csrf_token = auth.get_authorization_url('[REDIRECT_URL]')

  // redirect(auth_url, code=302)
  ```

  ```js Node theme={null}
  var authorize_url = sdk.getAuthorizeURL({
      response_type: "code",
  });

  // res.redirect(authorize_url)
  ```
</CodeGroup>

<Info>
  The way in which a user is redirected to a URL depends on the application
  framework used. Most framework documentation provides extensive guidance on
  this topic.
</Info>

The <Link href="/reference/get-authorize">authorization URL</Link> can also be created manually
as follows.

```sh theme={null}
https://account.box.com/api/oauth2/authorize?client_id=[CLIENT_ID]&redirect_uri=[REDIRECT_URI]&response_type=code
```

<Info>
  Additional query parameters can be passed along when redirecting the user to
  limit down the scope, or pass along some extra state. See the [reference
  documentation](/reference/get-authorize) for more information.
</Info>

## 3. User grants application access

Once the user is redirected to the Box web app they will have to log in. After
they logged in they are presented with a screen to approve your application.

<Frame>
  <img alt="Example OAuth 2.0 approval screen" />
</Frame>

When the user accepts this request and selects the button, the browser will
redirect to your application's redirect URL as configured in the developer console.

## 4. Exchange code

The user is redirected to your application's redirect URL with a query parameter
containing a short-lived authorization code.

```sh theme={null}
https://your.domain.com/path?code=1234567
```

This code is not an <Link href="/guides/authentication/tokens/access-tokens">Access Token</Link> and is only valid for a few seconds.
The SDKs can be used to exchange the code for an actual Access Token.

<CodeGroup>
  ```csharp .NET theme={null}
  var session = await sdk.Auth.AuthenticateAsync("[CODE]");
  var client = new BoxClient(config, session);
  ```

  ```java Java theme={null}
  BoxAPIConnection client = new BoxAPIConnection(
      "[CLIENT_ID]",
      "[CLIENT_SECRET]",
      "[CODE]"
  );
  ```

  ```python Python theme={null}
  auth.authenticate('[CODE]')
  client = Client(auth)
  ```

  ```js Node theme={null}
  var code = "...";

  sdk.getTokensAuthorizationCodeGrant("[CODE]", null, function (err, tokenInfo) {
      var client = sdk.getPersistentClient(tokenInfo);
  });
  ```
</CodeGroup>

At the end of this flow, the application has an Access Token that can be used to
make API calls on behalf of this user.

## Using SDKs and OAuth 2.0

To learn more about OAuth 2.0 authentication for each SDK head over to:

* [.Net][.Net]
* [Java][Java]
* [Python][Python]
* [Node][Node]
* [IOS][IOS]

[.Net]: https://github.com/box/box-windows-sdk-v2/blob/legacy/docs/authentication.md#traditional-3-legged-oauth2

[Java]: https://github.com/box/box-java-sdk/blob/legacy/doc/authentication.md#standard-3-legged-oauth-20

[Python]: https://github.com/box/box-python-sdk/blob/legacy/docs/usage/authentication.md#traditional-3-legged-oauth2

[Node]: https://github.com/box/box-node-sdk/blob/legacy/docs/authentication.md#traditional-3-legged-oauth2

[IOS]: https://github.com/box/box-ios-sdk/blob/legacy/BoxSDK/docs/usage/authentication.md#traditional-3-legged-oauth2

[1]: https://support.box.com/hc/en-us/articles/360043693554-Box-Verified-Enterprise-Supported-Apps

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# OAuth 2.0 without SDKs
Source: https://developer.box.com/guides/authentication/oauth2/without-sdk

Build the authorization URL, redirect the user, and exchange the authorization code for an access token with direct API calls.

<RelatedLinks title="REQUIRED GUIDES" />

## Overview

While leveraging an official Box SDK removes common hurdles of authentication,
it is possible to use the Box APIs without one. This guide reviews the steps to
manually complete the OAuth 2.0 flow.

1. Build the authorization URL
2. Redirect the user to the authorization URL
3. The user grants the application access to take actions on their behalf, which, if successful, provides an authorization code
4. Redirect the user back to the application
5. Exchange the authorization code for an Access Token

At the end of this flow, the application has an <Link href="/guides/authentication/tokens/access-tokens">Access Token</Link>, which
can be used to make API calls on behalf of the user.

<Note>
  The Access Token acquired through the OAuth 2.0 flow is inherently tied to the
  user who authorized the application.

  It is possible to <Link href="/guides/authentication/oauth2/as-user">act as another user</Link>
  using the `as-user` header.
</Note>

## Prerequisites

Before continuing you will need to complete the following steps:

* Create a Platform App within the Box Developer Console, which leverages the OAuth 2.0 authentication method.
* Navigate to the configuration tab for the application to copy the `client_id` and `client_secret` values.
* Ensure at least one redirect URI is configured in the configuration tab for the application.

## 1. Build authorization URL

An <Link href="/reference/get-authorize">authorization URL</Link> is comprised of the following parameters:

| Parameter | Status | Description |
| - | - | - |
| <Link href="/reference/get-authorize/#param-client_id">`CLIENT_ID`</Link> | Required | Obtained from the configuration tab of the Developer Console |
| <Link href="/reference/get-authorize/#param-redirect_uri">`REDIRECT_URI`</Link> | Optional | Configured in the Developer Console and where the user is sent once granting access to the application |
| <Link href="/reference/get-authorize/#param-response_type">`RESPONSE_TYPE`</Link> | Required | Always set to `code` |
| <Link href="/reference/get-authorize/#param-state">`STATE`</Link> | Recommended | Protects against cross-site request forgery |

<Warning>
  If you configured multiple redirect URIs for the application, the authorization
  URL must include the `redirect_uri` parameter matching one of the URIs
  configured in the developer console. If the parameter is not specified, the
  user will see a `redirect_uri_missing` error and will not be redirected back to
  the app.
</Warning>

At the minimum this URL will always use the format:

`https://account.box.com/api/oauth2/authorize`?`client_id=CLIENTIDHERE`&`response_type=code`

<CodeGroup>
  ```csharp .Net theme={null}
  var baseUrl = "https://account.box.com/api/oauth2/authorize";
  var clientId = "[CLIENT_ID]";
  var authorizationUrl = $"{baseUrl}?client_id={clientId}&response_type=code";
  ```

  ```java Java theme={null}
  String baseUrl = "https://account.box.com/api/oauth2/authorize";
  String clientId = "[CLIENT_ID]";
  String authorizationUrl = String.format("%s?client_id=%s&response_type=code", baseUrl, clientId);
  ```

  ```python Python theme={null}
  base_url = 'https://account.box.com/api/oauth2/authorize'
  client_id = '[CLIENT_ID]'
  authorizationUrl = f'{base_url}?client_id=${client_id}&response_type=code'
  ```

  ```js Node theme={null}
  var baseUrl = "https://account.box.com/api/oauth2/authorize";
  var clientId = "[CLIENT_ID]";
  var authorizationUrl = `${baseUrl}?client_id=${clientId}&response_type=code`;
  ```
</CodeGroup>

<Card href={localizeLink("/reference/get-authorize")} title="Learn more about the authorization URL" />

## 2. Redirect the user

Next, redirect the user to the authorization URL. The way this is done depends
on the application framework. Most framework documentation provides extensive
guidance on this topic.

If the authorization URL is not valid for the app specified, the user will see
an error page rather than a grant access screen. For example, if the
`redirect_uri` parameter in the authorization URL does not match one of the URIs
configured for your app, the user will see a `redirect_uri_mismatch` error.

<CodeGroup>
  ```csharp .Net theme={null}
  var authorizationUrl = $"{baseUrl}?client_id={clientId}&response_type=code";
  // redirectTo(authorizationUrl);
  ```

  ```java Java theme={null}
  String authorizationUrl = String.format("%s?client_id=%s&response_type=code", baseUrl, clientId);

  // response.redirect(authorizationUrl);
  ```

  ```python Python theme={null}
  auth_url = f'{base_url}?client_id=${client_id}&response_type=code'
  // redirect(auth_url, code=302)
  ```

  ```js Node theme={null}
  var authorizationUrl = `${baseUrl}?client_id=${clientId}&response_type=code`;
  // res.redirect(authorize_url)
  ```
</CodeGroup>

<Info>
  Additional query parameters can be passed along when redirecting the user to
  limit down the scope, or pass along some extra state. See the authorization
  reference documentation for more information.
</Info>

## 3. User grants application access

The user is redirected to their browser to log in to their account using the Box
UI. They are then presented with the list of requested scopes and the option to
approve the application to take actions on their behalf.

<Frame>
  <img alt="Example OAuth 2.0 approval screen" />
</Frame>

When the user accepts this request by selecting **Grant access to Box**, the
browser will redirect to the configured redirect URL with a query parameter
containing a short-lived authorization code.

<Warning>
  If you configured multiple redirect URIs for the application, the authorization
  URL must include the `redirect_uri` parameter matching one of the URIs
  configured in the developer console. If the parameter is not specified, the
  user will see a `redirect_uri_missing` error and will not be redirected back to
  the app.
</Warning>

```sh theme={null}
https://your.domain.com/path?code=1234567
```

## 4. Exchange code

The provided authorization code is <Link href="/guides/api-calls/permissions-and-errors/expiration">valid for 30 seconds</Link> and must be
exchanged for an <Link href="/reference/post-oauth2-token">Access Token</Link> before expiration.

<CodeGroup>
  ```csharp .Net theme={null}
  using System.Net;
  using System.Net.Http;
  using Newtonsoft.Json;

  String authenticationUrl = "https://api.box.com/oauth2/token";
  var client = new HttpClient();

  var content = new FormUrlEncodedContent(new[]
  {
      new KeyValuePair<string, string>("grant_type", "authorization_code"),
      new KeyValuePair<string, string>("code", "[CODE]"),
      new KeyValuePair<string, string>("client_id", "[CLIENT_ID]"),
      new KeyValuePair<string, string>("client_secret", "[CLIENT_SECRET]")
  });

  var response = client.PostAsync(authenticationUrl, content).Result;

  class Token
  {
      public string access_token { get; set; }
  }

  var data = response.Content.ReadAsStringAsync().Result;
  var token = JsonConvert.DeserializeObject<Token>(data);
  var accessToken = token.access_token;
  ```

  ```java Java theme={null}
  String authenticationUrl = "https://api.box.com/oauth2/token";

  List<NameValuePair> params = new ArrayList<NameValuePair>();

  params.add(new BasicNameValuePair("grant_type", "authorization_code"));
  params.add(new BasicNameValuePair("code", "[CODE]"));
  params.add(new BasicNameValuePair("client_id", "[CLIENT_ID]"));
  params.add(new BasicNameValuePair("client_secret", "[CLIENT_SECRET]"));

  CloseableHttpClient httpClient = HttpClientBuilder.create().disableCookieManagement().build();

  HttpPost request = new HttpPost(authenticationUrl);
  request.setEntity(new UrlEncodedFormEntity(params));

  CloseableHttpResponse httpResponse = httpClient.execute(request);
  HttpEntity entity = httpResponse.getEntity();

  String response = EntityUtils.toString(entity);
  httpClient.close();

  class Token {
      String access_token;
  }

  Token token = (Token) gson.fromJson(response, Token.class);
  String accessToken = token.access_token;
  ```

  ```python Python theme={null}
  authentication_url = "https://api.box.com/oauth2/token";

  params = urlencode({
      'grant_type': 'authorization_code',
      'code': '[CODE]',
      'client_id': '[CLIENT_ID]',
      'client_secret': '[CLIENT_SECRET]'
  }).encode()

  request = Request(authentication_url, params)
  response = urlopen(request).read()
  access_token = json.loads(response)['access_token']
  ```

  ```js Node theme={null}
  const authenticationUrl = "https://api.box.com/oauth2/token";

  let accessToken = await axios
      .post(
          authenticationUrl,
          querystring.stringify({
              grant_type: "authorization_code",
              code: "[CODE]",
              client_id: "[CLIENT_ID]",
              client_secret: "[CLIENT_SECRET]",
          })
      )
      .then((response) => response.data.access_token);
  ```
</CodeGroup>

To learn how to use an Access Token visit our guide on <Link href="/guides/api-calls">Making API calls</Link>.

[1]: https://support.box.com/hc/en-us/articles/360043693554-Box-Verified-Enterprise-Supported-Apps

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box API and SSO
Source: https://developer.box.com/guides/authentication/sso

How single sign-on affects OAuth 2.0 sign-ins, and why it doesn't apply to server-side authentication.

Many Box Enterprises use **Single Sign On** (SSO) to authenticate
<Link href="/guides/getting-started/users#managed-users">Managed Users</Link> logging in to Box. The way an application built on
Box interacts with an SSO provider depends on the type of application
being built.

## Platform Apps with client-side authentication

When users authenticate with a <Link href="/guides/applications/platform-apps/index">Platform App</Link> configured to use
<Link href="/guides/authentication/oauth2">OAuth 2.0</Link> Box will detect if the enterprise is configured to use SSO.
If it is, Box will redirect the user to their browser and display the
enterprise's configured SSO log-in screen.

### SSO enabled and SSO required

Enterprises can configure their SSO in one of two ways: **SSO Required**
or **SSO Enabled**.

When SSO is enabled but not required, managed users will have the option to
either:

* log in with a Box username and password
* log in with their SSO provider

When SSO is enabled and required, Box will force all managed users to log in
with their enterprise's configured SSO provider. In this case, any
user that tries to log in must be configured on the SSO side, in addition to
having a Box account matching the email address passed via SAML.

<Warning>
  It is not possible to exempt a user from SSO in an enterprise with SSO
  set to required, even if it is only used for platform use cases.
</Warning>

## Platform Apps with server-side authentication

For <Link href="/guides/applications/platform-apps/index">Platform Apps</Link> that use <Link href="/guides/authentication/jwt/jwt-setup">JWT</Link>,
SSO is not used to authenticate with Box.

Platform Apps using server-side authentication only use server-to-server API
calls to communicate with Box. In this scenario, the way in which an end user
is authenticated is determined by the application and not by Box.

In other words, end user authentication with the application is determined by
the application, while the application's authorization to Box is a different
matter completely.

In these use cases the application authenticates not as a regular Managed User
but as a Service Account or App User. These user types do not have access to any
Managed User's data by default. For these applications to have access to other
Managed User's data they will need explicit <Link href="/guides/authorization/platform-app-approval">admin approval</Link>.

<RelatedLinks title="RELATED GUIDES" />


# Switch between CCG and JWT
Source: https://developer.box.com/guides/authentication/switch-server-auth-type

Check whether your enterprise allows changing a Server app's authentication method, and see what a switch revokes and what it preserves.

A Server app authenticates with either <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link> (CCG) or <Link href="/guides/authentication/jwt">JWT</Link>. Whether you can change that choice after the app exists depends on an enterprise setting, and the switch has consequences for credentials that are already in use.

## Whether your enterprise allows switching

The **Switch server app auth type (CCG or JWT)** enterprise setting controls whether developers can change a Server app's method after the app has been created. A Box Admin manages it in **Admin Console** > **Enterprise Settings** > **Platform Apps**, where it reads **Allow developers to switch server app auth type for existing apps**. It is enabled by default for free developer accounts and disabled by default for enterprises.

Where the setting is disabled, the method is fixed for the life of the app, so changing it means creating a new app.

## Change the method

When switching is enabled, you change the method in the <Link href="https://app.box.com/developers/console">Developer Console</Link> > **Configuration** tab > **Server Authentication Method**. You must complete [multi-factor authentication (MFA)](https://support.box.com/hc/en-us/articles/360043697154-Multi-Factor-Authentication-Set-Up-for-Your-Account) before saving the change. Re-authorization by a Box Admin is not required afterward.

<Warning>
  Changing the authentication type revokes all credentials that are specific to the previous type. That includes JWT keypairs, passphrases, and any uploaded public keys. Your developer token is not revoked.

  Changing auth type causes downtime for any production traffic, and rotating secrets afterward is your responsibility. Only do this during a maintenance window or before your app begins handling production traffic.
</Warning>

All other application configurations, including scopes, webhooks, CORS domains, and advanced features, are preserved.

<Card href={localizeLink("/guides/authentication#choosing-between-ccg-and-jwt")} title="Compare CCG and JWT before you switch" />

<Card href={localizeLink("/guides/authentication/jwt/jwt-setup")} title="Set up an app with JWT" />

<Card href={localizeLink("/guides/authentication/client-credentials/client-credentials-setup")} title="Set up an app with Client Credentials Grant" />


# Access tokens
Source: https://developer.box.com/guides/authentication/tokens/access-tokens

What Box returns in the token object for OAuth 2.0 and for server authentication, and how the two responses differ.

Instead of a user name and password, Access Tokens are the credentials used to
represent the authenticated user to the Box servers.

## Token object

### OAuth 2.0 authentication

When an Access Token is requested using OAuth 2.0, an Access Token and Refresh
Token pair are returned.

```sh theme={null}
curl -X POST https://api.box.com/oauth2/token \
    -H "content-type: application/x-www-form-urlencoded" \
    -d '...'
```

```json theme={null}
{
  "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "expires_in": 3600,
  "token_type": "bearer",
  "refresh_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

Within this object we can see the token string (`access_token`), as well
as the Refresh Token (`refresh_token`) that can be used to request a new Access
Token when the current one expires (`expires_in`).

### Server authentication

When an Access Token is requested using JWT or Client Credentials Grant, only an
Access Token is returned:

```sh theme={null}
curl --location --request POST 'https://api.box.com/oauth2/token' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode '...'
```

```json theme={null}
{
  "access_token": "DkXZmsjUKizvL2z0WiaLvMBeQ756XCGGf",
  "expires_in": 4123,
  "restricted_to": [],
  "issued_token_type": "bearer"
}
```

Within this object we can see the token string (`access_token`).
Because a Refresh Token is not returned, you must request a new token when the
Access Token expires (`expires_in`) using the <Link href="/reference/post-oauth2-token">token endpoint</Link>.


# Annotator tokens
Source: https://developer.box.com/guides/authentication/tokens/annotator-tokens

Generate an access token that ties Box View annotations to one of your own end users, with or without an SDK.

Annotations is one of the key features supported by new Box View, that allows
developers to provide collaboration capabilities right from within the embedded
Box preview in their application.

Box View supports three annotation types: highlight only, highlight
annotation, and point annotation. Annotations are only supported on document
and image previews.

<Frame>
  <img alt="How annotator tokens work" />
</Frame>

## What is an Annotator Token

An Annotator Token is an Access Token that allows an application to create a
Preview Embed Link for a file that a user can make annotations on. As an
application might not create a new App User for every one of the application's
users, the Annotator token allows the application to track which of their
own users made the annotations.

The Annotator Token is used instead of a regular Access Token or File
Token to generate a preview session (an expiring embed link) that is linked to a
unique user ID and display name.

<Warning>
  Since a preview session generated using an annotator token is tied to a
  specific external user, it is strongly recommended that an application
  generates different preview sessions using different annotator tokens for
  different end users of an application.
</Warning>

## External user info

The external display name associated with an annotation is essentially a
stateless "label" appended to the annotation. This means that once an annotation
has been added, the display name is permanently associated with the annotation
and cannot be updated unless the annotation is deleted and added again with the
updated display name.

## Create without SDKs

To create an annotator token, follow the instructions for [manually
authenticating through JWT](/guides/authentication/jwt/without-sdk) but replace the
JWT claim with the following data.

<CodeGroup>
  ```csharp .Net theme={null}
  var claims = new List<Claim>{
      new Claim("sub", '[EXTERNAL_USER_ID]'),
      new Claim("name", '[EXTERNAL_USER_DISPLAY_NAME]'),
      new Claim("box_sub_type", "external"),
      new Claim("jti", jti),
  };
  ```

  ```java Java theme={null}
  JwtClaims claims = new JwtClaims();
  claims.setIssuer(config.boxAppSettings.clientID);
  claims.setAudience(authenticationUrl);
  claims.setSubject("[EXTERNAL_USER_ID]");
  claims.setName("[EXTERNAL_USER_DISPLAY_NAME]");
  claims.setClaim("box_sub_type", "external");
  claims.setGeneratedJwtId(64);
  claims.setExpirationTimeMinutesInTheFuture(0.75f);
  ```

  ```python Python theme={null}
  claims = {
      'iss': config['boxAppSettings']['clientID'],
      'sub': '[EXTERNAL_USER_ID]',
      'name': '[EXTERNAL_USER_DISPLAY_NAME]',
      'box_sub_type': 'external',
      'aud': authentication_url,
      'jti': secrets.token_hex(64),
      'exp': round(time.time()) + 45
  }
  ```

  ```js Node theme={null}
  let claims = {
      iss: config.boxAppSettings.clientID,
      sub: "[EXTERNAL_USER_ID]",
      name: "[EXTERNAL_USER_DISPLAY_NAME]",
      box_sub_type: "external",
      aud: authenticationUrl,
      jti: crypto.randomBytes(64).toString("hex"),
      exp: Math.floor(Date.now() / 1000) + 45
  };
  ```

  ```ruby Ruby theme={null}
  claims = {
    iss: config['boxAppSettings']['clientID'],
    sub: "[EXTERNAL_USER_ID]",
    name: "[EXTERNAL_USER_DISPLAY_NAME]",
    box_sub_type: 'external',
    aud: authentication_url,
    jti: SecureRandom.hex(64),
    exp: Time.now.to_i + 45
  }
  ```

  ```php PHP theme={null}
  $claims = [
    'iss' => $config->boxAppSettings->clientID,
    'sub' => '[EXTERNAL_USER_ID]',
    'name' => '[EXTERNAL_USER_DISPLAY_NAME]',
    'box_sub_type' => 'external',
    'aud' => $authenticationUrl,
    'jti' => base64_encode(random_bytes(64)),
    'exp' => time() + 45,
    'kid' => $config->boxAppSettings->appAuth->publicKeyID
  ];
  ```
</CodeGroup>

| Parameter | Type | Description |
| - | - | - |
| `sub` | String | The external user ID to tie this annotation to. This can be any arbitrary ID tracked by the application |
| `box_sub_type` | String | `external` to signify an external user ID |
| `name` | String | The external user name to tie this annotation to. This will be displayed in the Box UI |

Then, convert this claim to an assertion according to the guide and pass this
assertion to the <Link href="/reference/post-oauth2-token">`POST /oauth2/token`</Link>
endpoint together with an existing valid Access Token or File Token,
as well as a set of scopes, and the resource for which to create the token.

<CodeGroup>
  ```csharp .Net theme={null}
  var content = new FormUrlEncodedContent(new[]
  {
      new KeyValuePair<string, string>(
          "grant_type", "urn:ietf:params:oauth:grant-type:token-exchange"),
      new KeyValuePair<string, string>(
          "resource", "https://api.box.com/2.0/files/123456"),
      new KeyValuePair<string, string>(
          "subject_token", "[ACCESS_TOKEN]"),
      new KeyValuePair<string, string>(
          "subject_token_type", "urn:ietf:params:oauth:token-type:access_token"),
      new KeyValuePair<string, string>(
          "scope", "item_preview"),
      new KeyValuePair<string, string>(
          "actor_token", "[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]"),
      new KeyValuePair<string, string>(
          "actor_token_type", "urn:ietf:params:oauth:token-type:id_token"),
  });
  ```

  ```java Java theme={null}
  List<NameValuePair> params = new ArrayList<NameValuePair>();

  params.add(new BasicNameValuePair(
      "grant_type", "urn:ietf:params:oauth:grant-type:token-exchange"));
  params.add(new BasicNameValuePair(
      "resource", "https://api.box.com/2.0/files/123456"));
  params.add(new BasicNameValuePair(
      "subject_token", "[ACCESS_TOKEN]"));
  params.add(new BasicNameValuePair(
      "subject_token_type", "urn:ietf:params:oauth:token-type:access_token"));
  params.add(new BasicNameValuePair(
      "scope", "item_preview"));
  params.add(new BasicNameValuePair(
      "actor_token", "[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]"));
  params.add(new BasicNameValuePair(
      "actor_token_type", "urn:ietf:params:oauth:token-type:id_token"));
  ```

  ```python Python theme={null}
  params = urlencode({
      'grant_type': 'urn:ietf:params:oauth:grant-type:token-exchange',
      'resource': 'https://api.box.com/2.0/files/123456',
      'subject_token': '[ACCESS_TOKEN]',
      'subject_token_type': 'urn:ietf:params:oauth:token-type:access_token',
      'scope': 'item_preview',
      'actor_token': '[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]',
      'actor_token_type': 'urn:ietf:params:oauth:token-type:id_token'
  }).encode()
  ```

  ```js Node theme={null}
  let accessToken = await axios
      .post(
          authenticationUrl,
          querystring.stringify({
              grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
              resource: "https://api.box.com/2.0/files/123456",
              subject_token: "[ACCESS_TOKEN]",
              subject_token_type: "urn:ietf:params:oauth:token-type:access_token",
              scope: "item_preview",
              actor_token: "[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]",
              actor_token_type: "urn:ietf:params:oauth:token-type:id_token"
          })
      )
      .then(response => response.data.access_token);
  ```

  ```ruby Ruby theme={null}
  params = URI.encode_www_form({
    grant_type: 'urn:ietf:params:oauth:grant-type:token-exchange',
    resource: 'https://api.box.com/2.0/files/123456',
    subject_token: '[ACCESS_TOKEN]',
    subject_token_type: 'urn:ietf:params:oauth:token-type:access_token',
    scope: 'item_preview',
    actor_token: '[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]',
    actor_token_type: 'urn:ietf:params:oauth:token-type:id_token'
  })
  ```

  ```php PHP theme={null}
  $params = [
    'grant_type' => 'urn:ietf:params:oauth:grant-type:token-exchange',
    'resource' => 'https://api.box.com/2.0/files/123456',
    'subject_token' => '[ACCESS_TOKEN]',
    'subject_token_type' => 'urn:ietf:params:oauth:token-type:access_token',
    'scope' => 'item_preview',
    'actor_token' => '[JWT_ASSERTION_FOR_ANNOTATOR_TOKEN]',
    'actor_token_type' => 'urn:ietf:params:oauth:token-type:id_token'
  ];
  ```
</CodeGroup>

| Parameter | Description |
| - | - |
| `resource` | An optional full URL path to the file the token should be restricted to. |
| `actor_token` | The JWT assertion created earlier |
| `actor_token_type` | Always set to `urn:ietf:params:oauth:token-type:id_token` |

## Create with SDKs

To create a JWT annotator token with an SDK an application can exchange any
active token for another token.

<CodeGroup>
  ```js Node theme={null}
  var options = {
      actor: {
          id: "[EXTERNAL_USER_ID]",
          name: "[EXTERNAL_USER_DISPLAY_NAME]"
      }
  };

  client
      .exchangeToken(
          "item_preview",
          "https://api.box.com/2.0/files/123456",
          options
      )
      .then(tokenInfo => {
          //=> tokenInfo.accessToken
      });
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Use a token
Source: https://developer.box.com/guides/authentication/tokens/api-calls

Pass an access token in the Authorization header of a Box API call, and check which user the token represents.

<RelatedLinks title="REQUIRED GUIDES" />

Every authenticated API call requires an Access Token to be passed in the
`Authorization` header as a `Bearer Token` or it will return a `401 Unauthorized`
HTTP status.

```sh theme={null}
curl https://api.box.com/2.0/users/me \
    -H "authorization: Bearer EGmDmRVfhfHsqesn5yVYHAqUkD0dyDfk"
```

<Info>
  Use the <Link href="/reference/get-users-me">`GET /users/me`</Link> endpoint to inspect what
  user an Access Token is authenticated for.
</Info>

The official SDKs pass the token for you once the client is initialized. For
example, to call `GET /users/me`:

<CodeGroup>
  ```typescript Node/TypeScript v10 theme={null}
  await client.users.getUserMe();
  ```

  ```python Python v10 theme={null}
  client.users.get_user_me()
  ```

  ```cs .NET v10 theme={null}
  await client.Users.GetUserMeAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.users.getUserMe()
  ```

  ```java Java v10 theme={null}
  client.getUsers().getUserMe()
  ```
</CodeGroup>

<RelatedLinks title="RELATED GUIDES" />


# Developer tokens
Source: https://developer.box.com/guides/authentication/tokens/developer-tokens

Generate a short-lived Box developer token in the Developer Console to test API calls during development. Tokens expire after 60 minutes.

<RelatedLinks title="REQUIRED GUIDES" />

A Box developer token is an access token you generate in the [Developer Console][devconsole] for development and testing. It expires after 60 minutes and you cannot refresh it programmatically. For production apps, use <Link href="/guides/authentication/tokens/access-tokens">access tokens</Link> from OAuth, JWT, or client credentials instead.

## Create a developer token

To create a Developer Token for an application:

* Navigate to the Box [Developer Console][devconsole] and select the application to create a Developer Token for.
* Select the **Configuration** tab.
* Under Developer Token, select **Generate Developer Token**.

<Info>
  You can also generate a Developer Token directly from <Link href="/guides/applications">My Platform Apps</Link>
  view, using the menu available for each app.
</Info>

<Frame>
  <img alt="Generating a Developer Token" />
</Frame>

## Use a developer token

A Developer Token can be used like any Access Token in the `Authorization`
header of an API call.

```sh theme={null}
curl https://api.box.com/2.0/users/me \
    -H "authorization: Bearer [DEVELOPER_TOKEN]"
```

<Warning>
  A Developer Token is associated with the user that is logged in to the
  Developer Console when the token is generated.
</Warning>

Our SDKs can be initialized with a Developer Token to create a basic API client,
as described in <Link href="/guides/authentication/tokens/sdks">Use a token in SDKs</Link>.

<Danger>
  **Developer tokens should not be used in production environments**

  Developer Tokens should only be used for development or testing purposes.
</Danger>

<Warning>
  When you explicitly revoke a developer token for a given app via the
  Developer console, all webhooks created by that application get deleted.
</Warning>

[devconsole]: https://app.box.com/developers/console

## Using SDKs and developer tokens

To learn more about Developer Tokens for each SDK head over to:

* [.Net][.Net]

* [Java][Java]

* [Python][Python]

* [Node][Node]

* [IOS][IOS]

[.Net]: https://github.com/box/box-windows-sdk-v2/blob/legacy/docs/authentication.md#developer-token

[Java]: https://github.com/box/box-java-sdk/blob/legacy/doc/authentication.md#developer-token

[Python]: https://github.com/box/box-python-sdk/blob/legacy/docs/usage/authentication.md#developer-token

[Node]: https://github.com/box/box-node-sdk/blob/legacy/docs/authentication.md#developer-token

[IOS]: https://github.com/box/box-ios-sdk/blob/legacy/BoxSDK/docs/usage/authentication.md#developer-token

<RelatedLinks title="RELATED GUIDES" />


# Downscope a token
Source: https://developer.box.com/guides/authentication/tokens/downscope

Exchange an access token for a more restricted one before you pass it to a browser, a mobile app, or Box UI Elements.

<RelatedLinks title="REQUIRED GUIDES" />

Downscoping is a way to exchange an existing Access Token for a new one that is
more restricted.

## Reasons to downscope

An application might need to share the Access Token with an
environment that it does not fully control. A common example of this would be
when using Box UI Elements in a web browser.

When an application needs to pass an Access Token to the browser there is a
potential security risk that needs to be resolved. In order to limit this risk the
Access Token can be exchanged for a new token with much stricter permissions.

## High-level overview

A downscoped token is a token that has fewer permissions (scopes) than the
original token, as well as the optional additional restriction to only allow
access to a specific file.

<Frame>
  <img alt="Downscoping overview" />
</Frame>

The new token takes the permissions of the original token and restricts them
to the tokens passed in, as well as the resource provided.

## Downscoping in practice

To downscope a token, pass the `POST /oauth2/token` endpoint an existing Access
Token, a list of scopes, as well as an optional file URL to restrict the token to.

| Parameter | Description |
| - | - |
| `subject_token` | The original token to downscope. This can be a token that was acquired through OAuth 2.0 or JWT token exchange. |
| `scope` | A space-delimited list of <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link> to limit the new token to. Any valid scope for the application can be used, though a special set of <Link href="/guides/api-calls/permissions-and-errors/scopes/#scopes-for-downscoping">scopes for Box UI elements</Link> is available |
| `resource` | An optional full URL path to the file the token should be restricted to. |
| `box_shared_link` | An optional <Link href="/guides/shared-links">shared link</Link> URL for a file or folder on Box. Password protected links are not supported. This option cannot be used in addition to the `resource` option nor can it be a shared link created on a weblink. |
| `subject_token_type` | Always set to `urn:ietf:params:oauth:token-type:access_token` |
| `grant_type` | Always set to `urn:ietf:params:oauth:grant-type:token-exchange` |

### Example request

Send a form-encoded `POST` to `https://api.box.com/oauth2/token`. The example
below downscopes a token to upload-only access (`item_upload`) on a single
folder, which is a common pattern for issuing narrowly scoped upload tokens to
browsers or other clients:

```sh theme={null}
curl -X POST https://api.box.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "subject_token=YOUR_ACCESS_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "scope=item_upload" \
  -d "resource=https://api.box.com/2.0/folders/FOLDER_ID"
```

Common upload-only combinations:

* `scope=item_upload` — allows uploading files through the Content Picker flow.
* `scope=base_upload` with a `resource` set to a specific folder — restricts
  uploads to that folder only, with no read, update, or delete permissions.

See [scopes for downscoping](/guides/api-calls/permissions-and-errors/scopes#scopes-for-downscoping)
for the full list of scopes you can request.

## Downscoped access token object

A downscoped Access Token returned by the `POST /oauth2/token` endpoint contains
extra information on the specific restrictions.

```json theme={null}
{
  "access_token": "1!DgsZ6V9kMWZu2StrxwQDF5BudQNen-xUmU2cfcVKArE....",
  "expires_in": 4175,
  "token_type": "bearer",
  "restricted_to": [
    {
      "scope": "item_preview",
      "object": {
        "type": "folder",
        "id": "1234567890",
        "sequence_id": "0",
        "etag": "0",
        "name": "Test"
      }
    }
  ],
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

Most importantly here is the list of `restricted_to` entries that will contain
each combination of `object` and `scope` that the new token has the permissions for.

<Warning>
  A downscoped token does not include a refresh token. To get a new downscoped
  token, refresh the original refresh token and use that new token to get a
  downscoped token.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Tokens
Source: https://developer.box.com/guides/authentication/tokens/index

Compare Box access, refresh, and developer tokens and choose the right token for OAuth, JWT, or Developer Console testing.

At the core of every Box API call is an Access Token.
Similar to using the Box Web App, you will only be able to successfully interact
with content the user associated with the Access Token is either a collaborator on
or owns. This can be further restricted by <Link href="/guides/authentication/tokens/downscope">downscoping</Link> a token.

<Warning>
  Required access scopes, application access, enabled advanced settings, user
  permissions, and endpoint-specific restrictions all work together to determine
  which API calls will be successful. For example, even if a user has
  collaborator access to a folder, a call to get information about the folder
  will not be successful if the read scope is not granted to the application.
</Warning>

## Types of tokens

| Type | Duration |
| - | - |
| <Link href="/guides/authentication/tokens/access-tokens">Access Token</Link> | 60 minutes |
| <Link href="/guides/authentication/tokens/refresh">Refresh Token</Link> | 60 days or one use |
| <Link href="/guides/authentication/tokens/developer-tokens">Developer Token</Link> | 60 minutes |

## Application types and access tokens

The following shows how each application type is expected to create an Access
Token.

| Box Application Type | How to get Access Token |
| - | - |
| Platform App + OAuth 2.0 | <Link href="/guides/authentication/oauth2/without-sdk">Explicit user grant</Link> |
| Platform App + JWT | <Link href="/guides/authentication/jwt/without-sdk">Exchange a JWT assertion</Link> |
| Platform App + Client Credentials Grant | <Link href="/guides/authentication/client-credentials">Use client ID and client secret</Link> |

[devcon]: https://app.box.com/developers/console


# Refresh a token
Source: https://developer.box.com/guides/authentication/tokens/refresh

Exchange a refresh token for a new access token, and understand the 60-day, single-use limits on refresh tokens.

<RelatedLinks title="REQUIRED GUIDES" />

An Access Token can be refreshed by using the Refresh Token that came with the
Access Token. This can be done before or after the Access Token expires.

To do this, the application passes the `refresh_token` to the [`POST
/oauth2/token`](/reference/post-oauth2-token) endpoint as follows.

<Info>
  **Usage in SDKs**

  All of the Box SDKs support automatic Access Token renewal for JWT and OAuth 2.0
  applications.
</Info>

<Danger>
  **Refresh token expiration**

  A Refresh Token is valid for 60 days and can be used to obtain a new Access
  Token and Refresh Token only once. If the Access Token and Refresh Token are
  not refreshed within 60 days, the user will need to be re-authorized.

  Every time an application uses the Refresh Token to get a new Access Token the
  Refresh Token is invalidated and a new Refresh Token is returned with the
  new Access Token.

  This new Refresh Token is then again only valid for 1 use within 60 days.
</Danger>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Revoke a token
Source: https://developer.box.com/guides/authentication/tokens/revoke

Invalidate an access token or a refresh token with the revoke endpoint, in cURL and in the Box SDKs.

<RelatedLinks title="REQUIRED GUIDES" />

An Access Token can be revoked at any time by either sending the Access Token or
Refresh Token to the <Link href="/reference/post-oauth2-revoke">`POST /oauth2/revoke`</Link> endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/oauth2/revoke" \
       -H "content-type: application/x-www-form-urlencoded" \
       -d "client_id=[CLIENT_ID]" \
       -d "client_secret=[CLIENT_SECRET]" \
       -d "token=[ACCESS_TOKEN]"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await auth.revokeTokens();
  // client's tokens have been revoked
  ```

  ```python Python v10 theme={null}
  client.auth.revoke_token()
  ```

  ```cs .NET v10 theme={null}
  await auth.RevokeTokenAsync();
  ```

  ```swift Swift v10 theme={null}
  try await auth.revokeToken()
  ```

  ```java Java v10 theme={null}
  auth.revokeToken();
  // client's tokens have been revoked
  ```

  ```python Python v4 theme={null}
  oauth.revoke()
  ```

  ```javascript Node v4 theme={null}
  client.revokeTokens("<TOKEN>")
  	.then(() => {
  		// the client's access tokens have been revoked
  	});
  ```
</CodeGroup>

<Info>
  **Usage in SDKs**

  All of the Box SDKs support manually revoking the current Access Token
  associated with the client. To revoke a specific token, first initialize a new
  SDK with that token and then call the relevant revoke method.
</Info>

<RelatedLinks title="RELATED APIS" />


# Use a token in SDKs
Source: https://developer.box.com/guides/authentication/tokens/sdks

Pass an existing access token or a developer token straight to a Box SDK client instead of configuring a full authentication flow.

<RelatedLinks title="REQUIRED GUIDES" />

The SDKs have direct support for JWT and OAuth 2.0 authentication, yet in some
cases your application might need to provide an Access Token to the SDK directly.

## Developer tokens

Similarly, developer tokens can be used directly in SDKs without needing any
further SDK configuration.

<RelatedLinks title="RELATED GUIDES" />


# Common Errors
Source: https://developer.box.com/guides/authorization/common-errors



## Unable to retrieve service of enterprise app authorization

<Frame>
  <img alt="Unable to retrieve error" />
</Frame>

This error indicates that the entered client ID is invalid.
To resolve this issue, please re-copy the Client ID from the Developer Console
and ensure you are not including any trailing characters.

## Something went wrong with adding the app authorization

This error indicates you are a Box co-admin granted privileges to view, but not
edit enterprise settings. You will need to have your Box Admin grant edit
privileges in order to successfully authorize an application.

<Frame>
  <img alt="Something went wrong error" />
</Frame>

## Disabled by Administrator

This error indicates that not all authorization requirements are satisfied.
Please review our <Link href="/guides/authorization">authorization guide</Link> to confirm the necessary steps for
a given application.

<Frame>
  <img alt="Admin error" />
</Frame>


# Authorization
Source: https://developer.box.com/guides/authorization/index



Some applications require explicit Admin authorization before use with an
enterprise. The steps an Admin needs to take are dependent on the
developer-selected authentication method and enabled enterprise settings.

## Authentication methods

The following <Link href="/guides/authentication">authentication methods</Link> always require explicit Admin
authorization:

* <Link href="/guides/authentication/jwt">Server Authentication (with JWT)</Link>
* <Link href="/guides/authentication/client-credentials">Server Authentication (with Client Credentials Grant)</Link>

These authentication methods automatically generate a <Link href="/guides/getting-started/users#service-account">Service Account</Link>.
With the right <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link> enabled, a Service Account can perform many
Admin actions, thus requiring Admin authorization before use.

<Link href="/guides/authentication/oauth2">OAuth 2.0</Link> apps may also require explicit
Admin authorization based on enabled enterprise settings.

## Enterprise settings

Subsequent steps are required if any of the following enterprise settings are
enabled:

* Enable Integrations by default — navigate to **Admin Console** > **Integrations** > **Platform Apps Manager** > **Platform Apps Settings** button.
* Disable unpublished apps by default - navigate to **Enterprise Settings** > **Platform Apps**

<Tip>
  Published Platform Apps are any applications that can be found under Integrations.
</Tip>

## Required actions

To see what steps an Admin must complete for a given app, review the following
scenarios.

**Disable published third party apps by default**:

| Authentication Method | Enabled | Disabled |
| - | - | - |
| <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> | Set to available in individual app controls | Ready for use |
| <Link href="/guides/authentication/jwt">Server Authentication (with JWT)</Link> | N/A | N/A |
| <Link href="/guides/authentication/client-credentials">Server Authentication (client credentials)</Link> | N/A | N/A |

**Disable unpublished apps by default**:

| Authentication Method | Enabled | Disabled |
| - | - | - |
| <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> | Enable in **Integrations** > **Platform Apps Manager** > **User Authentication Apps** > Select Platform App > Use **More** menu to enable the app. | Ready for use |
| <Link href="/guides/authentication/jwt">Server Authentication (with JWT)</Link> | Authorize and enable in **Integrations** > **Platform Apps Manager** > **Server Authentication Apps** Select Platform App > Use **More** menu to authorize the app. | Authorize in **Integrations** > **Platform Apps Manager** > **Server Authentication Apps** > Select Platform App > Use **More** menu to authorize the app. |
| <Link href="/guides/authentication/client-credentials">Server Authentication (client credentials)</Link> | Authorize and enable in **Integrations** > **Platform Apps Manager** > **Server Authentication Apps** > Select Platform App > Use **More** menu to authorize the app. | Authorize in **Integrations** > **Platform Apps Manager** > **Server Authentication Apps** > Select Platform App > Use **More** menu to enable the app. |

**Require manual Admin authorization for Platform Apps**:

| Authentication Method | Enabled | Disabled |
| - | - | - |
| <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> | N/A | N/A |
| <Link href="/guides/authentication/jwt">Server Authentication (with JWT)</Link> | N/A | N/A |
| <Link href="/guides/authentication/client-credentials">Server Authentication (client credentials)</Link> | N/A | N/A |

[setting]: https://support.box.com/hc/en-us/articles/360044196653-Managing-custom-apps

[ag]: /guides/applications/integrations


# Limited Access App Approval
Source: https://developer.box.com/guides/authorization/limited-access-approval



Limited Access Integrations are automatically authorized for use in an enterprise upon
creation.

However, if the enterprise setting to
**Require manual Admin authorization for Limited Access Apps** is enabled,
an Admin must perform additional steps.

## Approval Notifications

A semi-automated process to submit an app approval is available in the Developer
Console.

Navigate to the **Authorization** tab for your application in the
[Developer Console][devconsole].

<Frame>
  <img alt="Add and Manage keys" />
</Frame>

Submitting the application for approval will send an email to your
enterprise's Primary Admin to approve the application. More information on this
process is available in our [support article on app authorization][app-auth].

## Manual Approval

The following steps provide instructions on how to manually approve the
application.

### As a developer

1. Navigate to the **Configuration** tab for your application in the [Developer Console][devconsole].
2. Scroll down to the OAuth 2.0 Credentials section and copy the **Client ID** value to provide to a Box Admin.

Alternatively, hover over the application in the
<Link href="/guides/applications">My Platform Apps</Link> view to look up the **ClientID** and then
copy it using the `copy` button.

<Info>
  **Finding a Box Admin**

  If you don't know your enterprise Admin, go to your Box [Account
  Settings][settings] page and scroll to the bottom. If an admin contact is set
  you should see their contact information under **Admin Contact**.
</Info>

### As an Admin

As a Box Admin, navigate to the [Admin Console][adminconsole] and
select the **Integrations** > **Platform Apps Manager** > **Add Platform App**.

<Frame>
  <img alt="Apps tab" />
</Frame>

In the popup that appears, enter the Client ID for the application that the
developer collected from the **Configuration** tab of the Developer Console.

## Re-authorization on changes

When the application's scopes or access level change the application needs to be
re-authorized. Repeat the process above and request a new Access Token for the
new changes to take effect.

In the same section where the application was initially authorized, an Admin
can re-authorize the application by clicking on the ellipses to the right
of the application name to **Reauthorize App**.

<Frame>
  <img alt="Re-authorize app" />
</Frame>

[devconsole]: https://app.box.com/developers/console

[ccg]: /guides/authentication/client-credentials

[settings]: https://app.box.com/account

[adminconsole]: https://app.box.com/master/settings/custom

[jwt]: /guides/authentication/jwt

[app-token]: /guides/authentication/app-token

[app-auth]: https://support.box.com/hc/en-us/articles/360043697014-Authorizing-Apps-in-the-Box-App-Approval-Process


# Platform app approval
Source: https://developer.box.com/guides/authorization/platform-app-approval

Authorize or enable Box Platform apps in the Admin Console, submit apps for admin approval, and re-authorize apps after scope or access changes.

Server authentication applications using <Link href="/guides/authentication/jwt">JWT</Link> or
<Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link> must be authorized before use. For free developer accounts, authorization happens automatically when the app is created. For enterprise accounts, a Box Admin must approve the application.

Unpublished applications using <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> authentication may
require enablement by a Box Admin or Co-Admin if they are <Link href="/guides/security/#enterprise-settings-and-authorization">inactive by default</Link>.

A Box Admin or Co-Admin needs an application's Client ID to authorize or
enable it in the Admin Console.

<Info>
  Apps created by free developer (Individual) accounts are authorized
  automatically. You can use the <Link href="/guides/applications">My Platform Apps</Link> view to quickly look up
  the authorization and enablement status of your application.
</Info>

## One-click authorization

JWT and CCG authentication apps can be authorized directly from the
**Configuration** tab in the [Developer Console][devconsole]. This is
a convenient alternative to the methods described below.

### As an Admin or Co-Admin

The authorization process depends on your account type.

**Free developer accounts**: Your app is automatically authorized when you create it. If authorization did not complete, the **Configuration** tab displays a prompt to authorize the app directly.

**Enterprise developers**: After you create the app, the **Configuration** tab prompts you to submit for admin approval.

**Enterprise admins and co-admins**: After you create the app, the **Configuration** tab lets you authorize the app directly.

### As a developer

If you are not a Box Admin or Co-Admin, the **Configuration** tab displays:
**Submit app for authorization for access to the Enterprise.** Select
**Submit** to send the request. Your admin or co-admin receives an email
notification, and you receive an email when the request is approved or
denied.

## Approval notifications

### User authentication apps

A semi-automated process to submit an app approval is available in the Developer
Console for user authentication applications.

Navigate to the **Enablement** tab for your application in the [Developer Console][devconsole].

<Frame>
  <img alt="Enablement tab" />
</Frame>

Submitting the application for approval sends an email to your
enterprise's Primary Admin to approve the application.
When a Box Admin or Co-Admin approves or declines your request,
you receive an email with the decision.
More information on this process is available in our [support article on app authorization][app-auth].

## Manual approval

The following steps provide instructions on how to manually approve the
application.

### As a developer

1. Navigate to the **Configuration** tab for your application in the [Developer Console][devconsole].
2. Scroll down to the **OAuth 2.0 Credentials** section and copy the **Client ID** value to provide to a Box Admin or Co-Admin.

Alternatively, hover over the application in the
<Link href="/guides/applications">My Platform Apps</Link> view to look up the **Client ID** and then
copy it using the `copy` button.

<Info>
  **Finding a Box Admin**

  If you don't know your enterprise Admin, go to your Box [Account
  Settings][settings] page and scroll to the bottom. If an admin contact is set,
  their contact information displays under **Admin Contact**.
</Info>

### As an Admin

1. Navigate to the [Admin Console][adminconsole] and select the **Platform** tab from the left navigation panel.
2. Select the **Platform Apps** tab at the top of your screen.
3. For both Server and User Authentication Apps screens, select **Add** in the top right corner to add a new app.
4. Alternatively, you can hover over the row of your desired app and select **...** to authorize and enable apps.

In the dialog box that displays, enter the Client ID for the application that the
developer collected from the **Configuration** tab of the
[Developer Console][devconsole].

## Authorized app limit

When a new enterprise is created, it can authorize up to 10,000 custom apps.

<Info>
  If your enterprise needs to authorize more than 10,000 custom apps, contact
  [Box Support](https://support.box.com/hc/en-us/requests/new?\&referrerPageUrl=) to request an increase.
</Info>

## Re-authorization on changes

When an application's scopes or access level change, the application must be re-authorized for the changes to take effect.

**Free developer accounts**: When you save changes, the app is automatically re-authorized. If re-authorization did not complete, the **Configuration** tab displays a prompt to re-authorize the app.

**Enterprise developers**: After saving changes, submit the app for re-authorization by your Box Admin. The **Configuration** tab displays a prompt if your app's settings differ from the last authorized version.

**Enterprise admins and co-admins**: After saving changes, the **Configuration** tab prompts you to re-authorize the app directly.

Admins can also re-authorize applications by opening the **Platform Apps** tab under **Platform** in the Admin Console sidebar, then selecting **...** in the application's row and selecting **Reauthorize**.

<Frame>
  <img alt="Platform Apps tab in the Admin Console with an app's menu open and the Reauthorize option listed" />
</Frame>

[devconsole]: https://app.box.com/developers/console

[settings]: https://app.box.com/account

[adminconsole]: https://app.box.com/master/settings/custom

[app-token]: /guides/authentication/app-token

[app-auth]: https://support.box.com/hc/en-us/articles/360043697014-Authorizing-Apps-in-the-Box-App-Approval-Process


# Get File Information
Source: https://developer.box.com/guides/files/get



To get a file's information, not its content, call the
<Link href="/reference/get-files-id">`GET /files/:id`</Link> API with the `id` of the file.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/files/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.files.getFileById(uploadedFile.id, {
    queryParams: {
      fields: ['is_externally_owned', 'has_collaborations'],
    } satisfies GetFileByIdQueryParams,
  } satisfies GetFileByIdOptionalsInput);
  ```

  ```python Python v10 theme={null}
  client.files.get_file_by_id(
      uploaded_file.id, fields=["is_externally_owned", "has_collaborations"]
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Files.GetFileByIdAsync(fileId: uploadedFile.Id, queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"is_externally_owned","has_collaborations"}) });
  ```

  ```swift Swift v10 theme={null}
  try await client.files.getFileById(fileId: uploadedFile.id, queryParams: GetFileByIdQueryParams(fields: ["is_externally_owned", "has_collaborations"]))
  ```

  ```java Java v10 theme={null}
  client.getFiles().getFileById(uploadedFile.getId(), new GetFileByIdQueryParams.Builder().fields(Arrays.asList("is_externally_owned", "has_collaborations")).build())
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  BoxFile.Info info = file.getInfo();
  ```

  ```python Python v4 theme={null}
  file_id = '11111'
  file_info = client.file(file_id).get()
  print(f'File "{file_info.name}" has a size of {file_info.size} bytes')
  ```

  ```cs .NET v6 theme={null}
  BoxFile file = await client.FilesManager.GetInformationAsync(id: "11111");
  ```

  ```javascript Node v4 theme={null}
  client.files.get('11111')
  	.then(file => {
  		/* file -> {
  			type: 'file',
  			id: '11111',
  			file_version: 
  			{ type: 'file_version',
  				id: '22222',
  				sha1: '97b3dbba6eab7ad0f058240744c8636b7c7bea93' },
  			sequence_id: '1',
  			etag: '1',
  			sha1: '97b3dbba6eab7ad0f058240744c8636b7c7bea93',
  			name: 'Puppy.png',
  			description: '',
  			size: 106833,
  			path_collection: 
  			{ total_count: 2,
  				entries: 
  				[ { type: 'folder',
  					id: '0',
  					sequence_id: null,
  					etag: null,
  					name: 'All Files' },
  					{ type: 'folder',
  					id: '33333',
  					sequence_id: '0',
  					etag: '0',
  					name: 'Collaborated Folder' } ] },
  			created_at: '2016-11-16T22:01:44-08:00',
  			modified_at: '2016-11-16T22:01:51-08:00',
  			trashed_at: null,
  			purged_at: null,
  			content_created_at: '2016-10-29T18:33:50-07:00',
  			content_modified_at: '2016-10-29T18:33:50-07:00',
  			created_by: 
  			{ type: 'user',
  				id: '44444',
  				name: 'Owner',
  				login: 'owner@example.com' },
  			modified_by: 
  			{ type: 'user',
  				id: '44444',
  				name: 'Owner',
  				login: 'owner@example.com' },
  			owned_by: 
  			{ type: 'user',
  				id: '44444',
  				name: 'Owner',
  				login: 'owner@example.com' },
  			shared_link: null,
  			parent: 
  			{ type: 'folder',
  				id: '33333',
  				sequence_id: '0',
  				etag: '0',
  				name: 'Collaborated Folder' },
  			item_status: 'active' }

  		*/
  	});
  ```
</CodeGroup>

## File ID

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/file/123` the `file_id` is `123`.

## Additional fields

To get more of the fields for a file, make sure to pass along the `fields`
query parameter.

<Card href={localizeLink("/guides/api-calls/request-extra-fields")} title="Learn about requesting extra fields" />

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# File limitations
Source: https://developer.box.com/guides/files/limitations



A few limitations exist when working with files.

## Name restrictions

There are some restrictions to a file's name. Names containing non-printable
ASCII characters, forward and backward slashes (`/`, `\`), and protected names like
`.` and `..` are automatically sanitized by removing the non-allowed characters.


# Copy Folder
Source: https://developer.box.com/guides/folders/single/copy



Creates a copy of a folder within a destination folder.

The original folder will not be changed.

To copy a folder in Box you will need to provide our API with the `id` of the
`parent` folder that you would like to copy the folder into.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/folders/4353455/copy" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "parent": {
           "id": "345345"
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folders.copyFolder(folderOrigin.id, {
    parent: { id: '0' } satisfies CopyFolderRequestBodyParentField,
    name: copiedFolderName,
  } satisfies CopyFolderRequestBody);
  ```

  ```python Python v10 theme={null}
  client.folders.copy_folder(
      folder_origin.id, CopyFolderParent(id="0"), name=copied_folder_name
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Folders.CopyFolderAsync(folderId: folderOrigin.Id, requestBody: new CopyFolderRequestBody(parent: new CopyFolderRequestBodyParentField(id: "0")) { Name = copiedFolderName });
  ```

  ```swift Swift v10 theme={null}
  try await client.folders.copyFolder(folderId: folderOrigin.id, requestBody: CopyFolderRequestBody(parent: CopyFolderRequestBodyParentField(id: "0"), name: copiedFolderName))
  ```

  ```java Java v10 theme={null}
  client.getFolders().copyFolder(folderOrigin.getId(), new CopyFolderRequestBody.Builder(new CopyFolderRequestBodyParentField("0")).name(copiedFolderName).build())
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, "id1");
  BoxFolder destination = new BoxFolder(api, "id2");
  folder.copy(destination);
  ```

  ```python Python v4 theme={null}
  folder_id = '22222'
  destination_folder_id = '44444'

  folder_to_copy = client.folder(folder_id)
  destination_folder = client.folder(destination_folder_id)

  folder_copy = folder_to_copy.copy(parent_folder=destination_folder)
  print(f'Folder "{folder_copy.name}" has been copied into folder "{folder_copy.parent.name}"')
  ```

  ```cs .NET v6 theme={null}
  // Copy folder 11111 into folder 22222
  var requestParams = new BoxFolderRequest()
  {
      Id = "11111",
      Parent = new BoxRequestEntity()
      {
          Id = "22222"
      }
  };
  BoxFolder folderCopy = await client.FoldersManager.CopyAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  client.folders.copy('11111', '22222')
      .then(folderCopy => {
         /* folderCopy -> {
              type: 'folder',
              id: '1234567',
              sequence_id: '0',
              etag: '0',
              name: 'Pictures from 2017',
              created_at: '2012-12-12T10:53:43-08:00',
              modified_at: '2012-12-12T11:15:04-08:00',
              description: 'Some pictures I took',
              size: 629644,
              path_collection: 
              { total_count: 1,
                  entries: 
                  [ { type: 'folder',
                      id: '0',
                      sequence_id: null,
                      etag: null,
                      name: 'All Files' },
                    { type: 'folder',
                      id: '22222',
                      sequence_id: '3',
                      etag: '3',
                      name: 'Archives' } ] },
              created_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User'
                  login: 'user@example.com' },
              modified_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User',
                  login: 'user@example.com' },
              owned_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User',
                  login: 'user@example.com' },
              shared_link: null,
              parent: 
              { type: 'folder',
                  id: '22222',
                  sequence_id: '3',
                  etag: '3',
                  name: 'Archives' },
              item_status: 'active',
              item_collection: 
              { total_count: 1,
                  entries: 
                  [ { type: 'file',
                      id: '44444',
                      sequence_id: '0',
                      etag: '0',
                      sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
                      name: 'tigers.jpeg' } ],
                  offset: 0,
                  limit: 100 } }
          */
      });
  ```
</CodeGroup>

Optionally, you can provide a different name for the new folder.

<Note>
  **Name restrictions**

  There are some restrictions to the folder name. Names containing non-printable
  ASCII characters, forward and backward slashes (`/`, `\`), as well as names
  with trailing spaces are prohibited.

  Additionally, the names `.` and `..` are reserved names and therefore
  also prohibited.
</Note>

## Asynchronous copying

If the folder being copied contains up to 500 items the copy will happen
synchronously with the API call. The call will not return until the copy
operation has completed.

If the folder contains more than 500 items the copy operation will be run
asynchronously and the API call will return directly yet before the copy
operation has completed. We currently have no API to check when a copy operation
has finished.

## Folder locking

During this operation, part of the file tree will be locked, mainly the source
folder and all of its descendants, as well as the destination folder.

For the duration of the operation, no other move, copy, delete, or restore
operation can be performed on any of the locked folders. Most importantly, this
means that the same folder can not be copied to two different parts of the
folder tree at the same time.

## Metadata

If the destination folder has a metadata cascade policy attached to any of the
parent folders a metadata cascade operation will be kicked off asynchronously.

We currently have no API to check when this operation has finished.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create Folder
Source: https://developer.box.com/guides/folders/single/create



To create a folder in Box you will need to provide our API with a `name` for the
new folder, as well as the `id` of the `parent` folder that you would like to
create the new folder within.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/folders" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "name": "New Folder",
         "parent": {
           "id": "0"
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folders.createFolder({
    name: newFolderName,
    parent: { id: '0' } satisfies CreateFolderRequestBodyParentField,
  } satisfies CreateFolderRequestBody);
  ```

  ```python Python v10 theme={null}
  client.folders.create_folder(new_folder_name, CreateFolderParent(id="0"))
  ```

  ```cs .NET v10 theme={null}
  await client.Folders.CreateFolderAsync(requestBody: new CreateFolderRequestBody(name: newFolderName, parent: new CreateFolderRequestBodyParentField(id: "0")));
  ```

  ```swift Swift v10 theme={null}
  try await client.folders.createFolder(requestBody: CreateFolderRequestBody(name: newFolderName, parent: CreateFolderRequestBodyParentField(id: "0")))
  ```

  ```java Java v10 theme={null}
  client.getFolders().createFolder(new CreateFolderRequestBody(newFolderName, new CreateFolderRequestBodyParentField("0")))
  ```

  ```java Java v5 theme={null}
  BoxFolder parentFolder = new BoxFolder(api, "id");
  BoxFolder.Info childFolderInfo = parentFolder.createFolder("Child Folder Name");
  ```

  ```python Python v4 theme={null}
  subfolder = client.folder('0').create_subfolder('My Stuff')
  print(f'Created subfolder with ID {subfolder.id}')
  ```

  ```cs .NET v6 theme={null}
  // Create a new folder in the user's root folder
  var folderParams = new BoxFolderRequest()
  {
      Name = "New folder",
      Parent = new BoxRequestEntity()
      {
          Id = "0"
      }
  };
  BoxFolder folder = await client.FoldersManager.CreateAsync(folderParams);
  ```

  ```javascript Node v4 theme={null}
  client.folders.create('0', 'New Folder')
      .then(folder => {
          /* folder -> {
              type: 'folder',
              id: '123456',
              sequence_id: '0',
              etag: '0',
              name: 'New Folder',
              created_at: '2012-12-12T10:53:43-08:00',
              modified_at: '2012-12-12T11:15:04-08:00',
              description: '',
              size: 0,
              path_collection: 
              { total_count: 1,
                  entries: 
                  [ { type: 'folder',
                      id: '0',
                      sequence_id: null,
                      etag: null,
                      name: 'All Files' } ] },
              created_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User'
                  login: 'user@example.com' },
              modified_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User',
                  login: 'user@example.com' },
              owned_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User',
                  login: 'user@example.com' },
              shared_link: null,
              parent: 
              { type: 'folder',
                  id: '0',
                  sequence_id: null,
                  etag: null,
                  name: 'All Files' },
              item_status: 'active',
              item_collection: 
              { total_count: 0,
                  entries: [],
                  offset: 0,
                  limit: 100 } }
          */
      });
  ```
</CodeGroup>

<Note>
  **Name restrictions**

  There are some restrictions to the folder name. Names containing non-printable
  ASCII characters, forward and backward slashes (`/`, `\`), as well as names
  with trailing spaces are prohibited.

  Additionally, the names `.` and `..` are reserved names and therefore
  also prohibited.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Move Folder
Source: https://developer.box.com/guides/folders/single/move



To move a folder, update the ID of its parent folder.

## Operation details

This call will return synchronously. This holds true even
for folder moves when the folder contains a large number
of items in all of its descendants. For very large
folders, this means the call could take
minutes or hours to complete and
some parts of the tree are locked during moves.

When moving a folder, part of the file tree will
be locked, mainly the source folder and all of its descendants,
as well as the destination folder.

For the duration of the move you cannot perform
other move, copy, delete, or restore operation
on any of the locked folders.

## Moving a subfolder to a private folder

When moving a collaborated subfolder into a private folder, the `owned_by.id` value has to match the authenticated user making the API request.

If `owned_by.id` does not match the requestor’s user ID, you will get the <Link href="/guides/api-calls/permissions-and-errors/common-errors#400-bad-request">`cannot_make_collaborated_subfolder_private`</Link> error.

The Box API doesn’t support changing ownership of a collaborated folder to another user as part of a move operation.

<RelatedLinks title="RELATED GUIDES" />


# Rename Folder
Source: https://developer.box.com/guides/folders/single/rename



To rename a folder in Box you will need to provide our API with a new `name` for
the folder.

<Note>
  **Name restrictions**

  There are some restrictions to the folder name. Names containing non-printable
  ASCII characters, forward and backward slashes (`/`, `\`), as well as names
  with trailing spaces are prohibited.

  Additionally, the names `.` and `..` are reserved names and therefore
  also prohibited.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Update Folder
Source: https://developer.box.com/guides/folders/single/update



<RelatedLinks title="REQUIRED GUIDES" />

To update a folder in Box you will need to call the following API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/folders/4353455" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "name": "New folder name"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folders.updateFolderById(folderToUpdate.id, {
    requestBody: {
      name: updatedName,
      description: 'Updated description',
    } satisfies UpdateFolderByIdRequestBody,
  } satisfies UpdateFolderByIdOptionalsInput);
  ```

  ```python Python v10 theme={null}
  client.folders.update_folder_by_id(
      folder_to_update.id, name=updated_name, description="Updated description"
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Folders.UpdateFolderByIdAsync(folderId: folderToUpdate.Id, requestBody: new UpdateFolderByIdRequestBody() { Name = updatedName, Description = "Updated description" });
  ```

  ```swift Swift v10 theme={null}
  try await client.folders.updateFolderById(folderId: folderToUpdate.id, requestBody: UpdateFolderByIdRequestBody(name: updatedName, description: "Updated description"))
  ```

  ```java Java v10 theme={null}
  client.getFolders().updateFolderById(folderToUpdate.getId(), new UpdateFolderByIdRequestBody.Builder().name(updatedName).description("Updated description").build())
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, "id");
  BoxFolder.Info info = folder.new Info();
  info.setName("New Name");
  folder.updateInfo(info);
  ```

  ```python Python v4 theme={null}
  updated_folder = client.folder(folder_id='22222').update_info(data={
      'name': '[ARCHIVED] Planning documents',
      'description': 'Old planning documents',
  })
  print('Folder updated!')
  ```

  ```cs .NET v6 theme={null}
  var requestParams = new BoxFolderRequest()
  {
      Id = "11111",
      Name = "My Documents (2017)"
  };
  BoxFolder updatedFolder = await client.FoldersManager.UpdateInformationAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  client.folders.update('11111', {name: 'Pictures from 2017'})
      .then(updatedFolder => {
          /* updatedFolder -> {
              type: 'folder',
              id: '11111',
              sequence_id: '1',
              etag: '1',
              name: 'Pictures from 2017',
              created_at: '2012-12-12T10:53:43-08:00',
              modified_at: '2012-12-12T11:15:04-08:00',
              description: 'Some pictures I took',
              size: 629644,
              path_collection: 
              { total_count: 1,
                  entries: 
                  [ { type: 'folder',
                      id: '0',
                      sequence_id: null,
                      etag: null,
                      name: 'All Files' } ] },
              created_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User'
                  login: 'user@example.com' },
              modified_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User',
                  login: 'user@example.com' },
              owned_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User',
                  login: 'user@example.com' },
              shared_link: null,
              parent: 
              { type: 'folder',
                  id: '0',
                  sequence_id: null,
                  etag: null,
                  name: 'All Files' },
              item_status: 'active',
              item_collection: 
              { total_count: 1,
                  entries: 
                  [ { type: 'file',
                      id: '33333',
                      sequence_id: '3',
                      etag: '3',
                      sha1: '134b65991ed521fcfe4724b7d814ab8ded5185dc',
                      name: 'tigers.jpeg' } ],
                  offset: 0,
                  limit: 100 } }
          */
      });
  ```
</CodeGroup>

## Name restrictions

There are some restrictions to the folder name. Names containing non-printable
ASCII characters, forward and backward slashes (`/`, `\`), as well as names
with trailing spaces are prohibited.

Additionally, the names `.` and `..` are reserved names and therefore
also prohibited.

## Timeout

Timeout for this operation is 600 seconds. The operation will complete
after an `HTTP 503` has been returned.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box Platform API agent playbook
Source: https://developer.box.com/guides/getting-started/agent-playbook

Authentication, core endpoints, SDKs, rate limits, and usage instructions for coding agents integrating with the Box API.

Use this page when building integrations against the Box API. It covers authentication, core endpoints, SDKs, rate limits, error handling, pagination, and common pitfalls.

For full page-by-page navigation, see [llms.txt](https://developer.box.com/llms.txt).

## Base URL

```text theme={null}
https://api.box.com/2.0/
```

Upload endpoints use a separate domain:

```text theme={null}
https://upload.box.com/api/2.0/
```

## Authentication

Every request carries an access token in the `Authorization` header:

```bash theme={null}
curl https://api.box.com/2.0/users/me \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

### Methods

| Method | When to use | Credentials |
| - | - | - |
| **OAuth 2.0** | User-facing apps where people sign in with Box | Client ID, client secret, redirect URI |
| **Client Credentials Grant (CCG)** | Backend services, automations, unattended code | Client ID, client secret, enterprise or user ID |
| **JWT** | Server apps that need keypair-based verification | Client ID, client secret, public/private keypair |
| **Developer Token** | Quick testing only (expires in 1 hour) | Generated in the [Developer Console](https://app.box.com/developers/console) |

### Token lifecycle

* Access tokens expire after **60 minutes** (`expires_in` in the response).
* OAuth 2.0 returns a refresh token (valid 60 days, single use). Exchange it before it expires.
* CCG and JWT apps request a new token with the same credentials.
* All methods request tokens from `POST https://api.box.com/oauth2/token`.

<Warning>
  Never commit credentials. Store client secrets, private keys, and tokens in environment variables or a secrets manager.
</Warning>

Guide: [Authentication](/guides/authentication)

## Core endpoints

| Resource | Key operations |
| - | - |
| **Files** | `GET /files/{id}` · `POST /files/content` (upload ≤ 50 MB) · `PUT /files/{id}` · `DELETE /files/{id}` · `GET /files/{id}/content` (download) |
| **Folders** | `GET /folders/{id}` · `POST /folders` · `PUT /folders/{id}` · `DELETE /folders/{id}` · `GET /folders/{id}/items` |
| **Uploads** | Direct: `POST https://upload.box.com/api/2.0/files/content` · Chunked: create session → upload parts → commit |
| **Search** | `GET /search` (full text) · `POST /metadata_queries/execute_read` (metadata) |
| **Metadata** | `GET /files/{id}/metadata` · `POST /files/{id}/metadata/{scope}/{template}` · templates, instances, cascade policies |
| **Collaborations** | `POST /collaborations` · `GET /files/{id}/collaborations` · `GET /folders/{id}/collaborations` |
| **Webhooks** | `POST /webhooks` · `GET /webhooks` · `PUT /webhooks/{id}` · `DELETE /webhooks/{id}` |
| **Events** | `GET /events` (user or enterprise stream) |
| **Box AI** | `POST /ai/ask` · `POST /ai/text_gen` · `POST /ai/extract` · `POST /ai/extract_structured` |

Reference: [API reference](/reference)

## Rate limits and retry strategy

The API returns **HTTP 429** when you exceed rate limits. The response includes a `retry-after` header with the number of seconds to wait.

**Strategy:**

1. Check for `429` status on every response.
2. Read the `retry-after` header value.
3. Wait at least that many seconds before retrying.
4. Use exponential backoff with jitter for concurrent requests.
5. Do not retry more than 5 times for the same request.

Rate-limit documentation: [Rate limits](/guides/api-calls/permissions-and-errors/rate-limits)

## Error handling

Box returns errors as JSON with a `type`, `status`, `code`, and `message`:

```json theme={null}
{
  "type": "error",
  "status": 409,
  "code": "item_name_in_use",
  "message": "Item with the same name already exists."
}
```

### Common status codes

| Status | Meaning | Action |
| - | - | - |
| `400` | Bad request — malformed payload or missing required field | Fix the request body |
| `401` | Unauthorized — expired or invalid token | Refresh or re-authenticate |
| `403` | Forbidden — insufficient scopes or permissions | Check app scopes and user access |
| `404` | Not found — item does not exist or user lacks access | Verify the item ID and token |
| `409` | Conflict — name collision or version conflict | Use a unique name or check `etag` |
| `429` | Rate limited | Retry after the `retry-after` header value |

Common-errors guide: [Common errors](/guides/api-calls/permissions-and-errors/common-errors)

## Pagination

### Offset-based (default for most list endpoints)

Use `offset` and `limit` query parameters. The response includes `total_count`.

```bash theme={null}
curl "https://api.box.com/2.0/folders/0/items?offset=0&limit=100" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

<Note>
  Offset-based pagination caps at **10,000 items**. Switch to marker-based for larger sets.
</Note>

### Marker-based

Use `usemarker=true` and pass the `next_marker` value from the previous response.

```bash theme={null}
curl "https://api.box.com/2.0/folders/0/items?usemarker=true&limit=1000" \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

Pagination guide: [Pagination](/guides/api-calls/pagination)

## SDKs

| Language | Package | Install |
| - | - | - |
| Python | [boxsdk](https://pypi.org/project/boxsdk/) | `pip install "boxsdk>=10"` |
| Node.js | [box](https://www.npmjs.com/package/box) | `npm install box` |
| Java | [box-java-sdk](https://github.com/box/box-java-sdk) | `implementation 'com.box:box-java-sdk:10.9.0'` |
| .NET | [Box.V2.Core](https://www.nuget.org/packages/Box.V2.Core) | `Install-Package Box.V2.Core` |
| Swift | [box-swift-sdk-gen](https://github.com/box/box-swift-sdk-gen) | Swift Package Manager |

All SDKs are v10+. Do not use deprecated generated packages (`box-typescript-sdk-gen`, `box-sdk-gen`, or other `*-sdk-gen` artifacts).

## Common gotchas

* **Folder 0 is root.** All folder trees start at ID `0`. Do not assume any other folder ID exists.
* **Service Accounts start empty.** Invite them as collaborators to access existing content.
* **Scopes restrict tokens.** A user may have access to a file, but the token still fails if the app lacks the required scope.
* **Uploads use a different domain.** `upload.box.com`, not `api.box.com`.
* **Chunked uploads require exact part sizes** except for the last part.
* **Webhook handlers must return 2xx within 30 seconds.** Process events asynchronously if needed.
* **Webhook delivery is not ordered.** Process events idempotently.
* **Metadata templates must exist** before you apply instances to files.
* **Metadata queries are case-sensitive** for template keys and field names.
* **Box AI endpoints require the "Manage AI" scope** enabled on the app.

## OpenAPI specification

The full OpenAPI 3.1 spec is published at:

* Source: [box-openapi](https://github.com/box/box-openapi)
* Bundled JSON: [openapi.json](https://developer.box.com/openapi/openapi.json)

## Quick links

| Resource | URL |
| - | - |
| Developer docs | [developer.box.com](https://developer.box.com) |
| llms.txt | [llms.txt](https://developer.box.com/llms.txt) |
| API reference | [API reference](/reference) |
| Getting started | [Getting started](/guides/getting-started) |
| Authentication | [Authentication](/guides/authentication) |
| Box AI | [Box AI](/guides/box-ai) |
| Changelog | [Changelog](/changelog) |
| Developer Console | [Developer Console](https://app.box.com/developers/console) |
| Free developer account | [Sign up](https://account.box.com/signup/developer) |


# Box for Developers glossary
Source: https://developer.box.com/guides/getting-started/box-glossary



This glossary includes terms and definitions used in Box for Developers. If you need
to find out what a term means, this is your one stop page.

| Box Resource Type/Term | Also known as (AKA) | Description |
| - | - | - |
| Admin | Superuser, administrator, supervisor | The main admin on an enterprise account. Admins can manage users and groups, view and edit all of their organization’s files and folders, log in to any user’s account within their organization, edit settings for their organization, and run or access reports. The Box Admin is the principal account administrator. |
| [Admin Console][admin-console] | | The dashboard area for administering a particular enterprise. Accessible by the admin, group admins, and co-admins. |
| Anonymous User | | A user that is not logged in. |
| App user | | Box [app user][app user] is a specific type of user who is associated with applications or services that integrate with Box. App users are only accessible with the API, meaning they do not have login credentials. They can be created by a service account and are only applicable to applications leveraging server to server authentication. App users are tied to the application used to create them, and the user itself cannot be moved under another application. They can however collaborate on content outside of the application. |
| Bookmark / web link | Symbolic link, Symlink, soft link, reference, relationship | A clickable reference that allows you to easily access external websites or specific locations within your content structure. |
| Box Integrations | App Store | The first place for Box users to find out about applications that they can use in combination with Box. |
| Box Command Line Interface | [Box CLI][CLI] | A user-friendly command line tool that allows both technical and non-technical users to leverage the Box API to perform routine or bulk actions. |
| [Box AI][box-ai] | | Built-in AI features that analyze, summarize, extract, and generate content directly from files in Box. |
| [Box AI Studio][ai-studio] | | A workspace for configuring and deploying custom AI agents, prompts, and automations on Box content. |
| [Box Archive][archives] | | A tool that allows you to create and manage archives – folders dedicated to storing redundant, outdated, or trivial content. |
| [Box App item][app-item] | App item | A content object owned by an application that can group files and folders from different paths. That set can be shared through a collaboration. |
| [Box Doc Gen][docgen] | | A tool that allows you to generate business documents such as offer letters, contracts, invoices, or agreements from templates stored in Box, with data fields that can be filled dynamically. |
| [Box Embed][embed] | | An HTML-based framework that makes it possible to embed the Box Web App experience anywhere in the 3rd party applications. Box Embed provides the ability to upload, search, comment, share, tag, and edit files using Box Edit. |
| [Box Hubs][hubs] | | Curated, shared workspaces that organize related content and resources around a team, project, or topic. |
| [Box MCP server][box-mcp] | | A secure server that connects AI tools to Box content using permission-aware access through the Model Context Protocol. Box hosts the remote MCP server; a legacy self-hosted option is deprecated. |
| [Box for Developers][platform] | | An API-driven cloud content management and collaboration platform that provides developers with the tools and infrastructure to build platform applications, integrate workflows, and leverage powerful features for secure document storage, access control, versioning, metadata management, and real-time collaboration. |
| [Box Sample Code Catalog][code-catalog] | | Allows developers and admins to search through code repositories of tools, automation scripts, self paced workshops, and demo apps in multiple programming languages. The catalog contains more than eighty open source repositories and guides. |
| [Box Shield][shield] | | A security solution offered by Box that helps protect sensitive data, prevent unauthorized access, and detect potential threats through automated classification and proactive monitoring. |
| [Box Relay][relay] | | Box Relay allows you to create and configure workflow automations to automate and accelerate business processes centered around content. |
| [Box Verified Enterprise][bve] | BVE | Box Verified Enterprise is a certification program that ensures the security and compliance of an organization's content management system. |
| [Box UI Elements][ui-elements] | | Pre-built UI components that allow developers to add elements of the main Box web application into their own applications. They can be used to navigate through, upload, preview, and select content stored on Box and are available both as React components and framework-agnostic JavaScript libraries. |
| [Cascade policy][cascade-policy] | | Box enables you to add metadata instances to a folder, and automatically cascade them to the folder's contents so you don't need to add the instances individually. Using cascading metadata, you can quickly add metadata to multiple files and sub-folders at one time. |
| [Classification][classification] | | An instance of the classification metadata template, containing the classification applied to the file or folder. |
| Collaboration | | Working together on a file or folder. |
| [Collaborations][collaborations] | Permissions, Role-Based Access Control (RBAC), Access Control List (ACL), permission mapping | Collaborations define access permissions for users and groups to files and folders, similar to access control lists. A collaboration object grants a user or group access to a file or folder with permissions defined by a specific role. |
| Collaborator | | Someone who shares access to a file or folder. |
| Collaborated folder | Shared folder | A shared folder owned by someone within your enterprise. |
| Collaboration roles | Permission levels, access levels | The collaboration roles define the level of permissions a user has for a specific file or folder. The collaboration roles in Box are **Owner**, **Co-owner**, **Editor**, **Viewer Uploader**, **Previewer Uploader**, and **Viewer**. Collaboration levels in Box follow a "waterfall" design in which individuals have access only to the folder they are invited into and any sub-folders beneath it. You can also be invited to individual files. |
| Collection | | A collection of items, including files and folders. The contents of a collection can be explored in a similar way to which the contents of a folder are explored. |
| [Content Manager][content-manager] | | A feature in the Admin Console that allows you to: search for and download files and folders in your organization, browse by user to see the files and folders they can access, move files between folders, invite collaborators to folders, get shared links and modify access levels, and delete files and folders from any user’s trash. |
| [Co-admin][co-admin] | | A user other than the main admin, who has a subset of administrative privileges. Co-admins can perform the same duties as the organization’s admin, but they cannot make changes to the Admin’s permissions or other co-admins' permissions. The default access levels for co-admins include only the ability to manage users and groups, but they can be modified on a per-user basis. |
| \[Platform App]\[custom-app] | | A tailored application that extends the functionality of Box by integrating with other tools and systems. It's used to streamline workflows and enhance collaboration. It can be created in the Developer Console and has several authentication methods available. |
| Developer | Programmer | A skilled professional who designs, builds, and maintains software applications or systems and has access to the Developer Console. In Box, the developer can have an admin role. |
| [Developer Console][dev-console] | | A portal that allows developers to create, debug, test, and monitor their applications by providing real-time insights into code execution and system performance. |
| Enterprise | Repository, content store, file cabinet, Docbase, vault | Enterprise in Box is a comprehensive suite of tools and services provided by Box for large organizations, offering secure file storage, collaboration features, access controls, workflow automation, compliance enforcement, and analytics. It enables efficient document management and teamwork while ensuring data security within an enterprise setting. |
| [Ethical walls][info-barriers] | Information barriers | A mechanism that prevents exchanges or communication that could lead to conflicts of interest and therefore result in business activities ethically or legally questionable. |
| [Event][event] | | Result of an action taken by the user. See [Using the Enterprise Event Stream][event-stream]. |
| External collaborator | External user | A collaborator who is not part of an enterprise. |
| External collaborated folder | | A folder owned by someone outside your enterprise. |
| File | Document, unstructured data | A digital container that stores information or data in a structured format. |
| Folder | Directory, container | A directory containing files. |
| [Group admin][group-admin] | | Group admins can add existing users to their groups, create new users that will be assigned to their groups, and assign folder access to their groups. They can also run reports for their groups. |
| Group | Team | Collaborative workspace where users can share files, collaborate on documents, and communicate with each other. |
| Item | Object, Box object, content | Can represent a file, a folder or a web link. |
| [Managed user][managed-users] | | A user account that is centrally controlled and administered by an organization's admin. |
| Metadata template | Document class, document type, content type, indexes | A predefined structure that captures and organizes important information about a document or file. |
| Metadata attribute | Property, field, keyword, index Value | A metadata attribute is a piece of information that provides descriptive details about data, such as its type, format, or source. |
| Personal folder | | A folder owned by an individual user. |
| [Report][report] | | A file containing a specific data set. You can use the **Admin Console Reports** tab to run a variety of account-wide reports: usage logs, file/user statistics, and security audits. |
| Sandbox | Testing environment | Managed, trackable, non-production, testing environment for developers. |
| [Service account][service-account] | | A service account provides developers with a programmatic authentication mechanism for server-side integrations with Box. In other words, an application can authenticate to Box as the service, which is represented by a service account user. A service account can then be used to create other application specific users, called app users. |
| [Shared link][shared-link] | | A hyperlink to content stored in Box you can share with your coworkers and friends – both inside and outside of the company. Sending someone a shared link to a file or folder is a way to work together with that person around shared content. Customizable permission levels, expiration dates, and optional password-protection make Box shared links a secure, simple way to share important content. |
| Software Developer Tool | [SDK][sdk] | A collection of tools, libraries, and documentation that helps developers create software applications for specific platforms or frameworks. |
| Task | Action | A specific action or assignment that needs to be completed within the collaborative document creation editor. |
| User | Identity, person, authority | An individual who utilizes the collaborative document creation editor to create, edit, and share documents with others. |
| Unmanaged user | | A user account that is not centrally managed by an organization and has limited access and control over the content within Box. The unmanaged users may or may not also be external users. |
| Version control | | The management and tracking of different versions of a document, ensuring that everyone is working on the most up-to-date version. |
| [Webhook][webhook] | | A webhook is a way for an application to provide real-time data or notifications to another application by sending HTTP POST requests. |
| Workflow | | Workflows within Box are automated sequences of tasks that help streamline and track the progress of document-centric processes, ensuring efficient collaboration and timely completion. |

<Next>
  Next step
</Next>

[app user]: /guides/getting-started/users#app-user

[app-item]: /reference/resources/app-item

[ai-studio]: /guides/ai-studio

[archives]: /guides/archives

[box-ai]: /guides/box-ai

[box-mcp]: /guides/box-mcp

[CLI]: https://github.com/box/boxcli

[docgen]: /guides/docgen

[hubs]: /guides/hubs-api

[collaborations]: /guides/collaborations

[embed]: /guides/embed/box-embed

[ui-elements]: /guides/embed/ui-elements

[cascade-policy]: https://support.box.com/hc/en-us/articles/360044195873-Cascading-metadata-in-folders

[content-manager]: https://docs.box.com/en/box-admin-tools/managing-content/content-manager/about-content-manager

[co-admin]: https://support.box.com/hc/en-us/articles/360043694174-Understanding-Administrator-and-Co-Administrator-Permissions

[info-barriers]: https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers

[event]: /reference/resources/event

[event-stream]: https://support.box.com/hc/en-us/articles/8391393127955-Using-the-Enterprise-Event-Stream

[group-admin]: https://support.box.com/hc/en-us/articles/360043694174-Understanding-Administrator-and-Co-Administrator-Permissions

[managed-users]: https://support.box.com/hc/en-us/articles/360044194353-Understanding-User-Management

[shared-link]: https://docs.box.com/en/box-fundamentals/for-users/collaborating/using-shared-links/creating-shared-links

[sdk]: /sdks-and-tools

[code-catalog]: /sample-code

[relay]: https://support.box.com/hc/en-us/articles/360044196213

[bve]: https://support.box.com/hc/en-us/articles/4401823156883-Box-Verified-Enterprise

[report]: https://docs.box.com/en/box-admin-tools/reporting-and-insights/running-reports

[dev-console]: https://cloud.app.box.com/developers/console

[admin-console]: https://app.box.com/master

[platform]: https://www.box.com/en-gb/platform

[shield]: https://www.box.com/en-gb/shield

[classification]: /guides/metadata/classifications

[platform-app]: /guides/applications/platform-apps/index

[webhook]: /guides/webhooks

[service-account]: /guides/getting-started/users#service-account


# Create your first application
Source: https://developer.box.com/guides/getting-started/first-application

Create, configure, and publish (optional) your first application.

After you test Box APIs with the pre-built application in the <Link href="/guides/getting-started">Quick Start</Link>, create your own application in the Developer Console and configure it for your use case.

## Before you begin

Make sure you have:

* A Box developer account with access to the <Link href="https://cloud.app.box.com/developers/console">Developer Console</Link>
* A sense of how your application runs: as a **server** backend or a **user-facing** app (see <Link href="/guides/getting-started/plan-your-integration#choose-an-application-type">choose an application type</Link>)

<Note>
  On a free developer account, a default CCG application is created and authorized automatically. See <Link href="/guides/getting-started/free-developer-plan#default-application-and-authorization">default application and authorization</Link> on the free developer plan page. The steps below apply when you create additional applications or when an enterprise admin must authorize your app.
</Note>

## Create your first application

1. Go to the <Link href="https://cloud.app.box.com/developers/console">Developer Console</Link>.
2. Select **New App**.
3. Enter your application name.
4. Choose the application type: **Server** or **User**.
   * **Server**: Select the authentication method: **Client Credentials Grant (CCG)** or **JSON Web Token (JWT)**.
   * **User**: The authentication method is automatically set to **OAuth 2.0**.
5. Select **Create**.

After you create the application, Box opens the **Configuration** tab. Complete the settings in the following sections before you call production APIs.

## Configure the application

On the **Configuration** tab, set the options your application needs:

1. **App Access Level** — Controls whether the app can act only as its service account or also on behalf of enterprise users. See <Link href="/guides/authentication/client-credentials/client-credentials-setup#application-access">Application Access</Link> for Client Credentials Grant apps.
2. **Application Scopes** — Enable only the permissions your app requires. Add scopes before you authorize the app in the Admin Console.
3. **Additional Configuration** — Toggle advanced features such as **Generate User Access Tokens** when your server app must act as a specific user.
4. **CORS Domains** — Add domains if your application accesses Box resources from a browser on another origin.

<Warning>
  Changing scopes, access level, or advanced features after authorization of a CCG or JWT app requires an administrator to reauthorize the app in the Admin Console under **Integrations > Platform Apps**.
</Warning>

## App details and credentials

Still on the **Configuration** tab, open **App Details** to view and copy credentials:

* **Application status**
* **Service accounts** (for authorized server applications)
* **Client ID**, **Client Secret**, and **Developer Token**
* **Collaborators** (if you added any)
* **Properties**, including your user ID and enterprise ID

<Note>
  Your user ID and enterprise ID appear in the **Properties** section. To find IDs for other users, files, or folders, see <Link href="/guides/getting-started/locating-values">Locating IDs</Link>.
</Note>

Application **collaborators** are other Box users you invite to help configure the app in the Developer Console. Add them by email in **App Details** or from the **Options** menu on **My Platform Apps**. See <Link href="/guides/applications">applications</Link> for an overview.

<Note>
  **Free developer accounts:** You can add application collaborators who **already have a Box account** (for example, a teammate's developer account, personal account, or enterprise account). To collaborate with a larger team in an isolated environment, ask your Box admin about a <Link href="/guides/getting-started/sandbox">developer sandbox</Link> or <Link href="/guides/getting-started/free-developer-plan#upgrade-your-free-developer-plan">upgrade your plan</Link>.

  This is separate from **content collaborators** on files and folders. You can still invite existing Box users to content through the web app or <Link href="/guides/collaborations/share-content">collaborations API</Link>.
</Note>

### Other Developer Console tabs

After configuration, use the other tabs as needed:

* **Webhooks** — Register event triggers for your application
* **App Diagnostics** — Review recent API activity for the application

## Optional: Publish to Integrations

When your app is ready for customers, see <Link href="/guides/getting-started/plan-your-integration#publish-your-app">publish your app</Link> for the Developer Console submission flow and <Link href="/guides/applications/integrations">Box Integrations</Link> for the full checklist, assets, and partner review.

## What's next

* <Link href="/guides/authentication">Choose an authentication method</Link> and wire it into your codebase
* <Link href="/guides/getting-started/sandbox">Developer sandbox</Link> to test before production deployment
* <Link href="/guides/getting-started/locating-values">Locating IDs</Link> for user, enterprise, file, and folder IDs used in API calls
* <Link href="/guides/getting-started/free-developer-plan#upgrade-your-free-developer-plan">Upgrade your free developer plan</Link> when you need more storage, higher limits, or additional features


# Free developer plan
Source: https://developer.box.com/guides/getting-started/free-developer-plan

Build and test full-featured Box applications at no cost with a free developer plan.

Build and test full-featured Box applications with enterprise-grade APIs at no cost. The free developer plan allows you to prototype, integrate, and validate your workflows before you scale.

With a free developer plan, you get:

* **1,000 AI units** per month for Box AI features like asking questions, extracting structured and freeform metadata, and generating text
* **10 GB** storage, a **250 MB** file upload limit, and **1** file version
* **Box Sign** with **5** documents for e-signature per month
* Full API access with OAuth 2.0, JWT, and Client Credentials Grant (CCG) authentication
* Developer Console access to create apps, generate credentials, and manage your integration
* Support through the <Link href="https://community.box.com/">Box Community forum</Link>

### Included APIs

With the free developer plan, you can access key endpoints including:

* <Link href="/reference/post-ai-ask">**AI**</Link>: Ask questions, extract structured and freeform metadata, and generate text
* <Link href="/reference/post-oauth2-token">**Authorization**</Link>: Implement OAuth 2.0, JWT, or Client Credentials Grant (CCG)
* <Link href="/reference/files-resources">**Content**</Link>: Upload, download, preview, version, and manage files and <Link href="/reference/folders-resources">folders</Link>
* <Link href="/reference/hubs-resources">**Hubs**</Link>: Create content portals, curate the items they contain, and manage hub collaborations
* <Link href="/reference/post-metadata-templates-schema">**Metadata**</Link>: Read, write, and extend metadata on files and folders
* <Link href="/reference/post-webhooks">**Webhooks**</Link>: Build real-time, event-driven applications
* <Link href="/reference/get-search">**Search**</Link>: Implement powerful content discovery features
* <Link href="/reference/post-sign-documents">**Sign**</Link>: Send documents for e-signature and track request status
* <Link href="/reference">**Users & Groups**</Link>: Create users, manage group memberships, and control access

<Note>
  Not every endpoint is available on this plan. In the <Link href="/reference">API reference</Link>, each endpoint that requires a paid plan includes a callout explaining that the endpoint is not available for free developers.
</Note>

## Sign up as a Box developer

1. Visit the <Link href="https://app.box.com/signup/developer">developer signup page</Link>.
2. Enter your name, email address, and create a password.
3. Accept the terms and select **Get Started**.

Confirm your email address to activate your developer account. Now you have access to the <Link href="https://cloud.app.box.com/developers/console">Developer Console</Link>, where you can create applications, generate credentials, and start exploring APIs.

### Default application and authorization

A default application using Client Credentials Grant (CCG) authentication is created for you automatically. On a free developer account, this app is also authorized automatically, so you don't need separate admin approval before making API calls.

## Upgrade your free developer plan

1. Log into your Box account and select **Back to My Account**, if not already in Box Drive.
2. From the top of the screen, select **Upgrade Plan**.
3. Choose the plan that aligns with your requirements.
4. Complete checkout and enter payment information to activate your upgraded features immediately.

Your existing developer applications, API credentials, and integrations stay the same during the upgrade process. You do not need to reconfigure or redeploy.

## Select the right plan

Upgrading from the free developer plan unlocks higher storage and upload limits, multi-user enterprise administration, licensed API capacity, direct support, and access to additional Box products. Exact limits change over time, so use the <Link href="https://www.box.com/pricing">Plans and Pricing</Link> page as the source of truth before you commit to production.

### What paid plans add in general

Compared with the free developer plan, paid Business and Enterprise accounts typically include:

* **More capacity** — Higher storage, per-file upload limits, file version history, and Box Sign volume.
* **Enterprise administration** — Admin Console, managed users and groups, platform app authorization workflows, and optional <Link href="/guides/getting-started/sandbox">developer sandboxes</Link> for team-based testing.
* **Access to more Box products** — Higher tiers and add-ons unlock <Link href="/guides/box-ai">Box AI</Link>, <Link href="/guides/ai-studio">Box AI Studio</Link>, <Link href="/guides/box-sign">Box Sign</Link>, <Link href="/guides/docgen">Box Doc Gen</Link>, <Link href="/guides/hubs-api">Box Hubs</Link>, <Link href="/guides/box-relay">Box Relay</Link>, <Link href="/guides/retention-policies">Box Governance</Link>, <Link href="/guides/events/event-triggers/shield-alert-events">Box Shield</Link>, <Link href="/guides/archives">Box Archive</Link>, and <Link href="/guides/box-automate">Box Automate</Link>. The tiers below show where each becomes available.
* **Licensed API usage** — Business plans include a monthly API call allocation per enterprise; see <Link href="/guides/api-calls/permissions-and-errors/rate-limits#licensing-based">licensing-based rate limits</Link> and the pricing page for defaults.
* **Direct support** — Business and Enterprise plans include technical support options that differ by tier.

### Business and Business Plus

Best when you need a multi-user production environment with core platform APIs:

| Area | What you gain |
| - | - |
| **Platform APIs** | Full content, metadata, search, webhooks, users, and groups APIs at production scale |
| **Box Sign** | <Link href="/guides/box-sign">Box Sign API</Link> on Business, Business Plus, Enterprise, Enterprise Suites, Enterprise Plus, and Enterprise Advanced |
| **Box AI** | <Link href="/guides/box-ai">Box AI API</Link> (ask, extract, text generation) on Business plans and above |
| **Metadata** | Custom metadata templates on Business Plus and above |
| **Upload limits** | Up to **5 GB** per file on Business and **15 GB** on Business Plus ([direct upload limits](/guides/uploads/direct)) |

### Enterprise, Enterprise Plus, and Enterprise Advanced

Best when you need higher scale, advanced automation, or specialized products:

| Plan tier | Notable limits | Box products and APIs commonly unlocked |
| - | - | - |
| **Enterprise** | Up to **50 GB** per-file upload limit | Box Sign, Box AI, <Link href="/guides/box-relay">Box Relay</Link> API (when Relay is enabled), <Link href="/guides/hubs-api">Box Hubs</Link> API (when Hubs is enabled) |
| **Enterprise Plus** | Up to **150 GB** per-file upload limit | Same core products as Enterprise, with higher capacity |
| **Enterprise Advanced** | Up to **500 GB** per-file upload limit | <Link href="/guides/docgen">Box Doc Gen</Link>, <Link href="/guides/ai-studio">Box AI Studio</Link>, <Link href="/guides/archives">Box Archive</Link>, and <Link href="/guides/box-automate">Box Automate</Link> (when enabled for your organization) |

<Note>
  Enterprise Advanced is required for several APIs documented in this developer site, including Box Doc Gen, Box AI Studio, and Box Archive. Box Automate and Box Hubs also depend on your plan and how your admin enables the product.
</Note>

### Add-on products

Some capabilities are sold as add-ons and enabled separately in the Admin Console:

| Add-on | Available on | Developer-facing capabilities |
| - | - | - |
| **Box Governance** | Business Plus, Enterprise, or Enterprise Advanced (add-on) | <Link href="/guides/retention-policies">Retention policies</Link> and <Link href="/guides/legal-holds">legal holds</Link> APIs |
| **Box Shield** | Purchased add-on for qualifying enterprises | Security classifications, threat detection, and related <Link href="/guides/events/event-triggers/shield-alert-events">Shield event</Link> triggers |

Other factors to consider when you choose a plan:

* Enterprise plans offer advanced security, compliance, and custom configurations
* Higher-tier Enterprise plans include increased AI query limits and advanced capabilities
* Business and Enterprise plans support unlimited storage and direct technical support, with support offerings that differ depending on the plan

For further guidance on selecting the right plan, contact <Link href="https://www.box.com/about-us/contact-us">Box's sales team</Link> or visit the <Link href="https://www.box.com/pricing">Plans and Pricing</Link> page.


# Box for Developers quick start
Source: https://developer.box.com/guides/getting-started/index

Sign up for a Box free developer account, generate the developer token and make your first API call.

[Box](https://www.box.com) is a cloud-based, intelligent content management and file sharing platform for storing, accessing, and collaborating on content from anywhere.

## Sign up for a free account

<SignupCTA>
  A free developer account gives you access to the Developer Console, APIs, and AI Units, for everything you need to follow along with developer guides.
</SignupCTA>

Confirm your email address to activate your developer account.

## Upload a file to Box and list all files in the root folder

The [Upload file](/reference/post-files-content) endpoint allows you to upload a single file to Box through the upload domain `https://upload.box.com/api/2.0/files/content`.

<Note>
  The maximum file size is 50MB. For larger files, use the <Link href="/guides/uploads/chunked">chunked upload APIs</Link>.
</Note>

A pre-built application using Client Credentials Grant (CCG) authentication is created for you to get started. This app is authorized automatically, so you don't need separate admin approval before making API calls.

Create a developer token to authenticate your requests. Go to the [Developer Console](https://cloud.app.box.com/developers/console) > your pre-built application and find the **App Details** section. Locate the **Developer Token** field, select **Generate Developer Token**, and copy it. For more detail, see <Link href="/guides/authentication/tokens/developer-tokens">Developer tokens</Link>.

<img alt="App Details" />

<Warning>
  Developer tokens expire one hour after you generate them.
</Warning>

We prepared an example invoice document for you to upload. Create a root folder for your project, download the file <Link href="/static/quickstarts/extract/files/demo-invoice-20tax-2.pdf">here</Link>, and save it in the folder.

<Tabs>
  <Tab title="Python">
    Create and activate a Python virtual environment.

    ```shell theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    Install the Box Python SDK by running the following command using <Link href="https://pypi.org/project/pip/">pip</Link>.

    ```shell theme={null}
    pip install "boxsdk>=10"
    ```

    <Note>
      Make sure you use the most up-to-date version number of the Python SDK. Refer to the
      <Link href="https://pypi.org/project/boxsdk/">Python SDK Open Source page</Link>.
    </Note>

    Obtain a `client` with your developer token:

    ```python theme={null}
    from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth, UploadFileAttributes, UploadFileAttributesParentField
    import json

    auth = BoxDeveloperTokenAuth(token="YOUR_DEVELOPER_TOKEN")
    client = BoxClient(auth=auth)
    ```

    <Warning>
      For a production codebase, always store your credentials in a `.env` file and add `.env` to your `.gitignore`.
    </Warning>

    Then call the upload API as follows.

    ```python theme={null}
    with open("demo-invoice-20tax-2.pdf", "rb") as file_content_stream:
        uploaded_file = client.uploads.upload_file(
            UploadFileAttributes(
                name="demo-invoice-20tax-2.pdf",
                parent=UploadFileAttributesParentField(id="0"),
            ),
            file_content_stream,
        )

    items = client.folders.get_folder_items("0")
    print(json.dumps(items.to_dict(), indent=2))
    ```

    The `get_folder_items` command lists all files in the root folder. Execute the script to upload the file and list all files.
  </Tab>

  <Tab title="Node.js">
    Install the Box Node.js SDK by running the following command using <Link href="https://www.npmjs.com/package/box">npm</Link>. The [box](/guides/tooling/box-npm-package) package installs the Box Node SDK and the [Box CLI](/guides/cli) as direct dependencies. Node.js 22 or later is required.

    ```shell theme={null}
    npm install box
    ```

    <Info>
      Existing projects can keep using `npm install box-node-sdk` — that package is still supported.
    </Info>

    Import the SDK:

    ```javascript theme={null}
    import BoxSDK from 'box/sdk';  // ESM
    const BoxSDK = require('box/sdk');  // CommonJS
    ```

    A pre-built application is created for you to get started. Create a developer token to authenticate your requests. Go to the [Developer Console](https://cloud.app.box.com/developers/console) > your pre-built application and find the **App Details** section. Locate the **Developer Token** field, select **Generate Developer Token**, and copy it. For more detail, see <Link href="/guides/authentication/tokens/developer-tokens">Developer tokens</Link>.

    Obtain a `client` with your developer token:

    ```javascript theme={null}
    const { BoxClient, BoxDeveloperTokenAuth } = require('box/sdk');
    const auth = new BoxDeveloperTokenAuth({ token: 'YOUR_DEVELOPER_TOKEN' });
    const client = new BoxClient({ auth });
    ```

    <Warning>
      Developer tokens expire one hour after you generate them.
    </Warning>

    ```javascript theme={null}
    const fs = require('fs');

    const attrs = { name: 'demo-invoice-20tax-2.pdf', parent: { id: '0' } };
    const body = {
      attributes: attrs,
      file: fs.createReadStream('demo-invoice-20tax-2.pdf'),
    };
    const files = await client.uploads.uploadFile(body);
    const file = files.entries[0];
    console.log(`File uploaded with id ${file.id}, name ${file.name}`);

    const items = await client.folders.getFolderItems('0');
    console.log(JSON.stringify(items, null, 2));
    ```

    The `getFolderItems` command lists all files in the root folder. Execute the script to upload the file and list all files.
  </Tab>

  <Tab title="Swift">
    Install the Box Swift SDK by running the following command using <Link href="https://github.com/box/box-swift-sdk-gen">Swift Package Manager</Link>.

    ```shell theme={null}
    swift package update
    ```

    A pre-built application is created for you to get started. Create a developer token to authenticate your requests. Go to the [Developer Console](https://cloud.app.box.com/developers/console) > your pre-built application and find the **App Details** section. Locate the **Developer Token** field, select **Generate Developer Token**, and copy it. For more detail, see <Link href="/guides/authentication/tokens/developer-tokens">Developer tokens</Link>.

    <Warning>
      Developer tokens expire one hour after you generate them.
    </Warning>

    Obtain a `client` with your developer token:

    ```swift theme={null}
    import BoxSdkGen

    let auth = BoxDeveloperTokenAuth(token: "YOUR_DEVELOPER_TOKEN")
    let client = BoxClient(auth: auth)
    ```

    Create a request body with the required parameters: attributes (`name` and `parent id`) and a file stream.

    ```swift theme={null}
    guard let fileStream = InputStream(url: URL(fileURLWithPath: "demo-invoice-20tax-2.pdf")) else {
        fatalError("Could not read a file")
    }

    let requestBody = UploadFileRequestBody(
        attributes: UploadFileRequestBodyAttributesField(
            name: "demo-invoice-20tax-2.pdf",
            parent: UploadFileRequestBodyAttributesParentField(id: "0")
        ),
        file: fileStream
    )

    let files = try await client.uploads.uploadFile(requestBody: requestBody)

    if let file = files.entries?[0] {
        print("File uploaded with id \(file.id), name \(file.name!)")
    }

    let items = try await client.folders.getFolderItems(folderId: "0")
    if let entries = items.entries {
        for entry in entries {
            switch entry {
            case let .fileMini(file):
                print("file \(file.name!) [\(file.id)]")
            case let .folderMini(folder):
                print("folder \(folder.name!) [\(folder.id)]")
            case let .webLinkMini(webLink):
                print("webLink \(webLink.name!) [\(webLink.id)]")
            }
        }
    }
    ```

    The `getFolderItems` command lists all files in the root folder. Execute the script to upload the file and list all files.
  </Tab>

  <Tab title="Java">
    A pre-built application is created for you to get started. Create a developer token to authenticate your requests. Go to the [Developer Console](https://cloud.app.box.com/developers/console) > your pre-built application and find the **App Details** section. Locate the **Developer Token** field, select **Generate Developer Token**, and copy it. For more detail, see <Link href="/guides/authentication/tokens/developer-tokens">Developer tokens</Link>.

    <Warning>
      Developer tokens expire one hour after you generate them.
    </Warning>

    **Gradle**

    Install the Box Java SDK by adding the following dependency to the `build.gradle` file.

    ```shell theme={null}
    implementation 'com.box:box-java-sdk:10.9.0'
    ```

    <Info>
      Make sure you use the most up-to-date version number of the Java SDK. Refer to the
      <Link href="https://opensource.box.com/box-java-sdk/">Java SDK Open Source page</Link>.
    </Info>

    **Maven**

    Then add the following Maven dependency.

    ```xml theme={null}
    <dependency>
        <groupId>com.box</groupId>
        <artifactId>box-java-sdk</artifactId>
        <version>10.9.0</version>
    </dependency>
    ```

    Obtain a `client` with your developer token:

    ```java theme={null}
    BoxDeveloperTokenAuth auth = new BoxDeveloperTokenAuth("YOUR_DEVELOPER_TOKEN");
    BoxClient client = new BoxClient(auth);
    ```

    Pass **`new UploadFileRequestBody`** to **`client.getUploads().uploadFile`**: attributes (**`UploadFileRequestBodyAttributesField`** with name and **`UploadFileRequestBodyAttributesParentField`** for folder id) and an **`InputStream`** for the file bytes.

    ```java theme={null}
    FileInputStream fileContentStream = new FileInputStream("demo-invoice-20tax-2.pdf");
    client.getUploads().uploadFile(
        new UploadFileRequestBody(
            new UploadFileRequestBodyAttributesField(
                "demo-invoice-20tax-2.pdf",
                new UploadFileRequestBodyAttributesParentField("0")
            ),
            fileContentStream
        )
    );

    client.getFolders().getFolderItems("0").getEntries().forEach(item -> {
        System.out.println(item);
    });
    ```

    The `getFolderItems` command lists all files in the root folder. Execute the script to upload the file and list all files.
  </Tab>

  <Tab title=".NET">
    **.NET Framework**

    To install the .NET SDK in the .NET framework, run the following command using
    the <Link href="https://www.nuget.org/packages/Box.V2.Core">Nuget</Link> package manager.

    ```shell theme={null}
    PM> Install-Package Box.V2.Core
    ```

    A pre-built application is created for you to get started. Create a developer token to authenticate your requests. Go to the [Developer Console](https://cloud.app.box.com/developers/console) > your pre-built application and find the **App Details** section. Locate the **Developer Token** field, select **Generate Developer Token**, and copy it. For more detail, see <Link href="/guides/authentication/tokens/developer-tokens">Developer tokens</Link>.

    <Warning>
      Developer tokens expire one hour after you generate them.
    </Warning>

    **.NET Core**

    To install the .NET SDK in the .NET Core framework, run the following command using
    the <Link href="https://www.nuget.org/packages/Box.V2.Core">Nuget</Link> package manager.

    ```shell theme={null}
    PM> Install-Package Box.V2.Core
    ```

    Obtain a `client` with your developer token:

    ```csharp theme={null}
    using Box.Sdk.Gen;

    var auth = new BoxDeveloperTokenAuth(token: "YOUR_DEVELOPER_TOKEN");
    var client = new BoxClient(auth: auth);
    ```

    Await **`client.Uploads.UploadFileAsync`** with **`new UploadFileRequestBody`**: **`UploadFileRequestBodyAttributesField`** (`name` and `parent id`) and a **`Stream`** (for example from **`File.OpenRead`**).

    ```csharp theme={null}
    using var fileContentStream = File.OpenRead("demo-invoice-20tax-2.pdf");
    var files = await client.Uploads.UploadFileAsync(
        requestBody: new UploadFileRequestBody(
            attributes: new UploadFileRequestBodyAttributesField(
                name: "demo-invoice-20tax-2.pdf",
                parent: new UploadFileRequestBodyAttributesParentField(id: "0")),
            file: fileContentStream));
    var file = files.Entries[0];
    Console.WriteLine($"File uploaded with id {file.Id}, name {file.Name}");

    var items = await client.Folders.GetFolderItemsAsync(folderId: "0");
    if (items.Entries != null)
    {
        foreach (var item in items.Entries)
        {
            if (item.FileFull != null)
            {
                Console.WriteLine(item.FileFull.Name);
            }
            else if (item.FolderMini != null)
            {
                Console.WriteLine(item.FolderMini.Name);
            }
            else if (item.WebLink != null)
            {
                Console.WriteLine(item.WebLink.Name);
            }
        }
    }
    ```

    The `getFolderItems` command lists all files in the root folder. Execute the script to upload the file and list all files.
  </Tab>
</Tabs>

Congratulations! You've uploaded your first file to Box and listed all files in the root folder.

## Use cases

Unsure if your use case is a good fit for Box? You're in the right place if:

* Content is in the center of your use case
* Your process involves moving content from one place to another
* Your workflow can abide by [waterfall permissions](https://docs.box.com/en/box-apps/box-apps-for-box-admins/box-apps-permissions#permissions)
* Your process involves administrative tasks that can be automated

Some common customer solutions include:

* Marketing asset management
* Secure document vaults
* Wealth management portals
* Automatic folder creation based on user provisioning
* Adding relevant metadata using machine learning
* Claim reviews with built-in approval/rejection flows
* Event monitoring for security and auditing

## What's next

Explore the following resources:

* [What a free developer plan offers](/guides/getting-started/free-developer-plan)
* [User types](/guides/getting-started/users) to understand managed users, app users, and service accounts.
* [Developer sandboxes](/guides/getting-started/sandbox) to build and test without affecting production data.
* [Authentication methods](/guides/authentication) to understand the different authentication methods available.
* [Set up JWT authentication](/guides/authentication/jwt/jwt-setup) for server-to-server Platform Apps.
* [Box CLI](/guides/cli) to help you build your application.
* [Box glossary](/guides/getting-started/box-glossary) to understand the key concepts of Box for Developers.
* [Changelog](/changelog/) to stay up to date with the latest changes.


# Locating IDs
Source: https://developer.box.com/guides/getting-started/locating-values

Find user IDs, enterprise IDs, and file or folder IDs in the Box web app, Admin Console, Developer Console, and API.

## User IDs

### As a developer

To locate your own user ID in the Box web app, navigate to your **All Files** page. Select your avatar and choose **Account Settings** from the dropdown menu. Your user ID is the **Account ID** value listed in the **Account Details** section of the **Account** tab.

### As an admin

If your account type provides access to the <Link href="https://docs.box.com/en/box-admin-tools/managing-content/content-manager/about-content-manager">Content Manager</Link>, select the user in question from the user list. The URL reveals their user ID. For example, in `https://app.box.com/master/content/2267862105/0/0`, the user ID is `2267862105`.

To find user IDs using the API, navigate to the Developer Console and generate a Developer Token or obtain an Access Token for yourself. Then call the <Link href="/reference/get-users">list enterprise users</Link> endpoint. This returns a list of all users in your enterprise.

## Enterprise ID

### As a developer

To find your enterprise ID, select your account icon in the top-right of the <Link href="https://cloud.app.box.com/developers/console">Developer Console</Link> and choose **Copy Enterprise ID**.

### As an admin

From the **Admin Console**, navigate to the **Account & Billing** tab. The Enterprise ID is located under the **Account Information** section.

## Content IDs

### As a developer

To locate a file ID via the Box web app, navigate to the file's preview in your browser and look at the URL. For example, the file ID of `https://app.box.com/file/1234567890` is `1234567890`.

To locate a folder ID via the Box web app, navigate into the folder and look at the URL. For example, the folder ID of `https://app.box.com/folder/9876543210` is `9876543210`.

To locate content IDs via the API, start by listing all items at the All Files level by passing `0` as the `folder_id` of the <Link href="/reference/get-folders-id-items">list items in folder</Link> endpoint.

### As an admin

If you have access to the Content Manager, select the user in question from the user list and then navigate to the content. The URL reveals the folder and/or file ID. For example, in `https://app.box.com/master/content/1987212562/88560510648/0/532181212706`:

* User ID: `1987212562`
* Folder ID: `88560510648`
* File ID: `532181212706`


# Plan your integration
Source: https://developer.box.com/guides/getting-started/plan-your-integration

Assess whether your use case fits Box, then choose the application type that matches how your app runs.

If you are still deciding whether Box can solve the problem, start with [why Box for developers](/guides/getting-started/why-box).

## Assess your use case

Content-centric processes perform best on Box. Ask yourself:

* Is content always involved in the process?
* Does the process involve:
  * moving content from one place to another,
  * collecting e-signatures,
  * generating documents,
  * automating multi-step review, approval, or routing workflows,
  * answering questions about content or extracting metadata with AI,
  * building purpose-built agents or custom AI extractions,
  * publishing governed knowledge portals for teams or departments,
  * classifying, protecting, or monitoring sensitive content for threats,
  * or applying retention schedules, legal holds, or other compliance controls?
* Can the workflow abide by <Link href="https://docs.box.com/en/box-fundamentals/for-users/collaborating/collaborating-by-inviting-others/understanding-folder-permissions">waterfall permissions</Link>?
* Does the process involve administrative tasks that may be automated?

If you answered **yes** to these questions, you most likely have a strong use case for Box.

Many teams also build on Box for **AI-first** workflows: agents that work across authorized content, curated knowledge shared at org scale, and documents generated from templates.

Common solutions include:

| Use case | Example Box products |
| - | - |
| Agentic file system | <Link href="/guides/box-mcp">Box MCP server</Link> and the <Link href="/guides/box-ai">Box AI API</Link> so agents search, reason over, and act on files a user can access; <Link href="/ai/agent-skills">Box Agent Skills</Link> for building integrations with coding assistants; <Link href="/guides/webhooks">webhooks</Link> and <Link href="/guides/events">events</Link> to trigger downstream automation. |
| Company Brain | <Link href="/guides/hubs-api">Box Hubs</Link> as governed knowledge portals, <Link href="/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub">Box AI Ask</Link> for permissions-aware answers across hub content, <Link href="/guides/ai-studio">Box AI Studio</Link> for purpose-built agents, and <Link href="/guides/metadata">metadata</Link> for structured context. |
| Team and department knowledge portals (Hubs) | <Link href="/guides/hubs-api">Box Hubs API</Link> to create and populate portals programmatically, <Link href="/guides/box-ai">Box AI</Link> for natural-language search within a hub, and <Link href="/guides/embed/box-embed">Box Embed</Link> to surface hubs in internal apps — see the <Link href="/tutorials/sales-rfp-answer-bank">sales RFP answer bank tutorial</Link>. |
| Template-based document generation | <Link href="/guides/docgen/docgen-getting-started">Box Doc Gen</Link> to merge structured data into Word templates and output PDFs; often paired with <Link href="/guides/box-sign">Box Sign</Link> for approval and signature — see the <Link href="/tutorials/offer-letter-creation">offer letter automation tutorial</Link>. |
| Marketing asset management | <Link href="/guides/hubs-api">Box Hubs</Link> for curated libraries, <Link href="/guides/metadata">metadata</Link> and <Link href="/guides/search">search</Link> for discovery, and <Link href="/guides/embed/ui-elements">UI Elements</Link> for browse and preview experiences. |
| Secure document vaults | <Link href="/guides/security">Box Shield</Link> for classification and threat detection, <Link href="/guides/retention-policies">Box Governance</Link> for retention and <Link href="/guides/legal-holds">legal holds</Link>, plus <Link href="/guides/metadata/classifications">classifications</Link> on files and folders. |
| Content classification | <Link href="/guides/metadata/classifications">Classifications</Link> to label files and folders by sensitivity, <Link href="/guides/box-ai">Box AI</Link> to suggest or auto-apply labels at scale, and <Link href="/guides/security">Box Shield</Link> to enforce classification-based access policies and detect threats. |
| Wealth management portals | Custom Platform Apps with <Link href="/guides/embed/ui-elements">UI Elements</Link> or <Link href="/guides/embed/box-embed">Box Embed</Link>, <Link href="/guides/box-sign">Box Sign</Link> for client agreements, and metadata for client or account context. |
| Automatic folder creation based on user provisioning | <Link href="/guides/folders/single/create">folders</Link>, <Link href="/guides/users">users</Link>, and <Link href="/guides/collaborations/groups">groups</Link> APIs, plus <Link href="/guides/webhooks">webhooks</Link> to react to user lifecycle events. |
| Adding relevant metadata using AI | <Link href="/guides/box-ai">Box AI</Link> to extract or suggest metadata, <Link href="/guides/ai-studio">Box AI Studio</Link> for custom agents. |
| Claim reviews with built-in approval and rejection flows | <Link href="/guides/box-relay">Box Relay</Link> for review workflows, <Link href="/guides/box-sign">Box Sign</Link> for approvals and signatures, and <Link href="/guides/docgen/docgen-getting-started">Box Doc Gen</Link> to generate claim or decision letters. |
| Event monitoring for security and auditing | <Link href="/guides/events">events</Link> and <Link href="/guides/webhooks">webhooks</Link> for real-time activity, <Link href="/guides/events/event-triggers/shield-alert-events">Box Shield</Link> alerts, and Box Governance reporting for retention and hold activity. |

<Note>
  Product availability depends on your Box plan and enterprise entitlements. Not every product is included on the free developer plan. See <Link href="/guides/getting-started/free-developer-plan#select-the-right-plan">select the right plan</Link> for paid tiers and add-on products.
</Note>

Still not sure if you have a good use case? Reach out to your Box account team or our sales team at [`sales@box.com`](mailto:sales@box.com).

## Choose an application type

Box applications support different capabilities and authentication options.

### Platform App

<Link href="/guides/applications/platform-apps">Platform Apps</Link> cover most use cases. They let you present Box functionality in a custom interface, including <Link href="/guides/embed/ui-elements">UI Elements</Link> for browsing, searching, and previewing content.

When you create a Platform App, you select an app type:

* **User** — for user-facing apps (OAuth 2.0)
* **Server** — for backend services using Client Credentials Grant or JWT

Platform Apps are a good fit when you need to access your own files and others' files, upload and download content, and optionally list the app in Box Integrations.

### Web App Integrations

<Link href="/guides/applications/web-app-integrations">Web App Integrations</Link> let third-party applications work inside the Box user experience. Users can edit, share, or modify Box content with your app, and you can surface the integration in Recommended Web Integrations in Box Preview.

## Publish your app

<Link href="/guides/applications/integrations">Box Integrations</Link> is where Box users discover apps that work with Box. Listing your app is an effective way to reach new users, especially for apps meant for other enterprises.

To publish, make sure your app is production-ready and uses OAuth 2.0. Submit it for approval in the Developer Console:

1. Select **Apps**.
2. Select **Submit for Approval**.
3. Fill out the form and select **Submit**.

Approved apps can appear in featured, most popular, or recently added sections.

For the submission checklist, required assets, and partner review process, see <Link href="/guides/applications/integrations">Box Integrations</Link>.

<Warning>
  Non-OAuth integrations cannot use that listing flow as-is; the guide describes using an OAuth listing as a marketing redirect when needed.
</Warning>

Questions about publishing: [`integrate@box.com`](mailto:integrate@box.com).

## Next steps

* <Link href="/guides/applications/integrations">Submit your app to Box Integrations</Link> — review the full listing checklist, required assets, and partner review process
* <Link href="/guides/applications/web-app-integrations">Reach users inside Box with Web App Integrations</Link>
* <Link href="/tutorials">Explore tutorials</Link> to build a working integration end to end


# Box developer sandboxes
Source: https://developer.box.com/guides/getting-started/sandbox

Build, test, and collaborate on Box applications in an isolated developer sandbox that mirrors your enterprise plan and add-ons.

Developer sandboxes in Box provide a secure, controlled environment where developers can build, test, and collaborate on applications without affecting the actual data of your enterprise. They offer a safe space to experiment with Box APIs, test settings, try new integrations, and work alongside external partners.

<Note>
  Developer sandboxes are included with Box **Business** plans and above. Each sandbox reflects your enterprise's existing plan and add-on products (such as Box Shield or Box Zones), and you can have up to **10** sandboxes per enterprise. See <Link href="https://docs.box.com/en/box-platform/box-platform-for-administrators/managing-developer-sandboxes-for-box-admins">Managing developer sandboxes for Box admins</Link> for details.
</Note>

## What is a developer sandbox

A developer sandbox is an environment isolated from your production (live) enterprise setup that keeps development activities separate from real business data.

## Why use a sandbox

Using a sandbox allows you to:

* Safely build apps within an enterprise-linked environment instead of a free standalone account.
* Collaborate securely with both internal teams and external collaborators. Contractors, partners, and other external users can join the sandbox without accessing live systems and compromising security.
* Test apps under realistic testing conditions, as sandboxes inherit your enterprise's plan and add-ons at creation time. If there are any changes to the plan or add-ons, they can be <Link href="https://docs.box.com/en/box-platform/box-platform-for-administrators/managing-developer-sandboxes-for-box-admins#synchronizing-sandbox-with-production">manually synced</Link> by an enterprise admin.

## Accessing your sandbox

Sandboxes in Box are created by enterprise admins. See <Link href="https://docs.box.com/en/box-platform/box-platform-for-administrators/managing-developer-sandboxes-for-box-admins">Managing developer sandboxes for Box admins</Link> to learn how to create a sandbox. When you are assigned as a primary admin of a sandbox, you receive a log-in email from Box with your sandbox user ID.

To access the <Link href="https://cloud.app.box.com/developers/console">Developer Console</Link> inside the sandbox environment and set up a password, select the link in the email. You can also access your sandbox by logging in with your sandbox credentials on <Link href="https://developer.box.com">developer.box.com</Link>.

The sandbox's primary admin can create individual sandbox accounts, giving developers access to a new Box environment that matches the plan of their parent Box enterprise.

### Accessing multiple sandboxes

As a primary admin, you can log into multiple sandboxes. If you want to use this functionality for existing sandboxes, you can remove the unique email address and get a system-generated email.


# User types
Source: https://developer.box.com/guides/getting-started/users

Learn which Box user type your app authenticates as, and how Managed Users, Service Accounts, and App Users differ.

The type of user your application authenticates as determines what content it can access and what actions it can take. Which user type you get depends on the <Link href="/guides/getting-started/plan-your-integration">application type</Link> you create and the <Link href="/guides/authentication">authentication method</Link> you choose.

## User types at a glance

| User type | Has login credentials? | How it's created | Visible in Admin Console? | Best for |
| - | - | - | - | - |
| [**Managed User**](#managed-users) | Yes | Provisioned by enterprise | Yes | Employees with licensed Box accounts |
| [**External User**](#external-users) | Yes | Has an existing Box account (personal or another enterprise) | Yes, **External Users** tab (**External Users** filter) | Cross-enterprise or free-account collaboration |
| [**Unmanaged User**](#unmanaged-users) | Yes | Self-provisioned using a managed domain email | Yes, **External Users** tab (**Unmanaged Users** filter) | Domain users outside enterprise control |
| [**Service Account**](#service-account) | No (API only) | Auto-generated when a server-auth app is <Link href="/guides/authorization/platform-app-approval">authorized</Link> | Content Manager only | Server-to-server integrations, content owned by the app |
| [**App User**](#app-user) | No (API only) | Created by a Service Account using the <Link href="/reference/post-users">API</Link> | Yes (Users & Groups + Content Manager) | Per-user content isolation without Box accounts |

## Admin and Co-Admin roles

Admin and Co-Admin are roles that can be assigned to Managed Users, not separate user types. A user must first be a Managed User before they can be given either role.

Managed Users with the Admin or Co-Admin role can manage the Box enterprise through the <Link href="https://docs.box.com/en/box-admin-tools/admin-console/about-the-admin-console">Admin Console</Link>. They can perform actions unavailable to other users, such as managing security policies, running reports, and configuring integrations.

<Note>
  Some applications require Admin-level permissions to operate. For example, a security application that monitors <Link href="/reference/get-events">enterprise events</Link> needs an Admin or a Co-Admin with reporting permissions.
</Note>

## Managed Users

Managed Users belong to your enterprise and consume a standard Box license. Each enterprise has a unique enterprise ID, and all Managed Users share that ID. They typically share the same email domain.

## External Users

External Users are collaborators from outside your organization — Box users whose accounts are not created from within your Admin Console and whose email addresses are not associated with your managed domain. They can belong to a different enterprise, or they can have a free personal Box account with no enterprise affiliation.

Admins cannot manage External Users' account settings or the content they own, but they can manage collaborations — including granting or revoking access to your enterprise's content. External Users appear in the Admin Console under **Users & Groups** > **External Users**. An Admin can <Link href="https://docs.box.com/en/box-admin-tools/managing-users/users-and-groups/invite-users">invite</Link> them to become Managed Users in your organization, provided they are not already part of another Box enterprise.

## Unmanaged Users

Unmanaged Users are Box users who:

* Have unlicensed personal Box accounts acquired independently of an Admin or Co-Admin, and that do not belong to your Box organization
* Use email addresses from your domain or verified domains (domains owned or controlled by your organization)

Unmanaged Users appear in the Admin Console under **Users & Groups** > **External Users** when you select the **Unmanaged Users** filter. Admins can identify and <Link href="https://docs.box.com/en/box-admin-tools/managing-users/users-and-groups/converting-unmanaged-users-to-managed-users">convert them to Managed Users</Link> to bring them under organizational control.

## Service Account

A Service Account is a programmatic user that represents your application in the Box enterprise. It authenticates server-to-server without login credentials, which makes it ideal for backend integrations and automated workflows.

```mermaid theme={null}
flowchart TB
  subgraph BoxEnterprise["Box Enterprise"]
    request["Developer sends app<br/>authorization request"]
    admin(["Box Primary Admin*"])
    managed(["Managed User"])
    console["Developer Console"]
    app1[("Application 1")]
    app2[("Application 2")]
    app3[("Application 3")]
    appn[("Application n")]
    auth{"Authorized<br/>by Admin"}
    notAuth{"Not Authorized"}
    service(["Service Account**"])
    appUser1(["App User 1"])
    appUserN(["App User n"])

    request -->|API Key| admin
    managed --> console
    console --> app1
    console --> app2
    console --> app3
    console --> appn
    app1 --> auth
    app2 --> notAuth
    auth --> service
    service --> appUser1
    service --> appUserN
  end
```

<sub>\* One per enterprise; can manage enterprise settings and authorize applications.</sub>

<br />

<sub>\*\* One per authorized application; can own content and processes, and can create and manage app users.</sub>

### When to use

* **Content migration**: Move content between on-premises systems and the cloud
* **Event monitoring**: Watch enterprise events for compliance or to trigger workflows
* **Content distribution**: Upload and share files with users regardless of their authentication status
* **System integrations**: Connect on-premises systems and devices to Box
* **Content archiving**: Store infrequently accessed content

### Creation

A Service Account is **automatically generated** when an Admin <Link href="/guides/authorization/platform-app-approval">authorizes</Link> your JWT or CCG application in the Admin Console. You don't create it manually.

Box assigns the Service Account an email address in the format:
`AutomationUser_AppServiceID_RandomString@boxdevedition.com`

For example: `AutomationUser_123456_6jCo6Pqwo@boxdevedition.com`. The number between the underscores is the **Service ID**, which matches the ID in your app's <Link href="https://app.box.com/developers/console">Developer Console</Link> URL (for example, `https://example.app.box.com/developers/console/app/123456`).

You can find the Service Account email in the **App Details** tab of your app in the <Link href="https://app.box.com/developers/console">Developer Console</Link>.

<Warning>
  If you attempt API calls with a Service Account token before the app is authorized, you receive an `unauthorized_client` error: `"This app is not authorized by the enterprise"`.
</Warning>

### Viewing content

Only **Primary Admins** can view a Service Account's content:

1. Open the <Link href="https://docs.box.com/en/box-admin-tools/managing-content/content-manager/about-content-manager">Content Manager</Link> in the Admin Console.
2. Search for the application name.
3. Right-click the result and select **Log in to user's account**.

Service Accounts are **not** visible in the **Users & Groups** tab. They only appear in the Content Manager.

<Note>
  Co-Admins can't log in as a Service Account. This mirrors how Co-Admins can't manage each other.
</Note>

### Permissions and collaboration

The API endpoints a Service Account can call are determined by the <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link> configured in the <Link href="https://app.box.com/developers/console">Developer Console</Link>. With the right scopes, a Service Account can perform Admin-level actions.

<Warning>
  Because a Service Account can have elevated permissions, JWT and CCG applications require explicit <Link href="/guides/authorization/platform-app-approval">Admin approval</Link> before they can be used in an enterprise.
</Warning>

A Service Account has its own folder tree, which starts empty. To give it access to existing content:

* **By email**: Invite the Service Account using its assigned email address, just as you would invite any other collaborator.
* **By API**: Use the <Link href="/reference/post-collaborations">create collaboration endpoint</Link> with the Service Account's user ID (returned by the <Link href="/reference/get-users-me">get current user endpoint</Link>).

<Tip>
  You can assign a Service Account an email alias to make collaboration invitations easier to remember.
</Tip>

By default, Service Accounts receive 10 GB of storage based on the **New User Default Settings** in the Admin Console. To change this, call the <Link href="/reference/put-users-id">update user endpoint</Link> with the `space_amount` parameter.

## App User

An App User is a programmatic user that your Service Account creates through the API. Like Service Accounts, App Users don't have login credentials and can only interact with Box through your application. Each App User gets their own folder tree, which gives you per-user content isolation.

App Users are tied to the application that created them and can't be transferred to another application.

### When to use

* **Customer portals**: Give clients or patients a place to access and store sensitive documents without needing a Box account
* **Vendor portals**: Distribute content like price lists, contracts, and marketing materials to partners, organized by vendor tier
* **Branded applications**: Build customer-facing features with per-user permissions, auditing, and <Link href="/reference/get-events">reporting</Link> — especially valuable for regulated industries like financial services and healthcare
* **Identity mapping**: Map users from your own identity provider (like Auth0 or Okta) to individual Box user accounts

### Creation

**Prerequisites**: You need a JWT or CCG application that has been <Link href="/guides/authorization/platform-app-approval">authorized</Link> in the Admin Console, which gives you a Service Account.

To create an App User, use the Service Account's access token to call the <Link href="/reference/post-users">create user endpoint</Link>. Set the `is_platform_access_only` body parameter to `true` — otherwise, a Managed User is created instead.

Box assigns each App User an email address in the format:
`AppUser_AppServiceID_RandomString@boxdevedition.com`

For step-by-step instructions and code samples, see <Link href="/guides/users/create-app-user">Create an App User</Link>.

### Viewing content

App Users are visible in two places in the Admin Console:

1. **Users & Groups** tab: Use the view options button, then filter by **Role > App Users**.

<Frame>
  <img alt="Filter for App Users" />
</Frame>

2. **Content Manager**: Search for the App User by name or email to browse their folder tree.

### Permissions and collaboration

App Users **can't** see the Service Account's folder tree or any other content unless you explicitly add them as a collaborator.

Each App User has their own folder tree, which starts empty. To give an App User access to content:

* **By email**: Invite the App User using their assigned email address.
* **By API**: Use the <Link href="/reference/post-collaborations">create collaboration endpoint</Link> with the App User's ID and an access token for a user who already has access to the target content.

## Service Account vs. App User

Use this decision guide to pick the right approach for your application:

| Question | If yes... |
| - | - |
| Does your app need to own and manage content without tying it to individual users? | Use a **Service Account** as the content owner. |
| Do you need per-user content isolation (each user has their own files)? | Create an **App User** for each user. |
| Are your users transient, but the content needs to persist? | Use a **Service Account** to own the content. |
| Do you want to map users from your own identity provider to Box? | Create an **App User** for each identity. |
| Is this a system-to-system integration with no end-user interaction? | Use the **Service Account** directly. |

## As-User

If you use OAuth 2.0, JWT, or CCG authentication, you can make `as-user` calls to act on behalf of another user. Even though your application originally authenticated as yourself or as a Service Account, subsequent calls can impersonate a different user.

This is useful for automating administrative tasks like folder reorganization or employee provisioning. To enable `as-user` calls, turn on the appropriate scope in the <Link href="https://app.box.com/developers/console">Developer Console</Link>.

<Frame>
  <img alt="As User" />
</Frame>

## Next steps

* <Link href="/guides/users/create-app-user">Create an App User</Link>
* <Link href="/guides/authentication">Choose an authentication method</Link>
* <Link href="/guides/getting-started/first-application">Create your first application</Link>


# Why Box for developers
Source: https://developer.box.com/guides/getting-started/why-box

Learn when to use Box to build applications, AI agents, and workflows on governed enterprise content.

Box gives developers a governed content layer for applications, workflows, and AI agents. Files in Box already have permissions, versions, metadata, collaboration, and audit history. Your application can use those controls instead of rebuilding them around a file store or AI pipeline.

Use Box when your product needs to work with documents, images, contracts, scans, presentations, or other unstructured content that people create and update as part of their work.

<SignupCTA>
  Create a free developer account to call Box APIs, test Box AI, and connect developer tools to sample content.
</SignupCTA>

## When should developers use Box?

Box is a good fit when your application needs one or more of these capabilities:

* **Content APIs:** Upload, download, preview, search, share, and organize files and folders.
* **Access controls:** Use Box users, groups, collaborations, scopes, and waterfall permissions.
* **Business context:** Add metadata to files, query that metadata, and respond to content events.
* **AI on enterprise content:** Ask questions, summarize files, and extract structured data without removing content from Box.
* **Agent access:** Connect external AI agents through the Box MCP server or Box CLI.
* **Document workflows:** Combine content intake, AI, review, document generation, and signature.
* **Embedded experiences:** Add file browsing, preview, upload, and metadata views to your application with UI Elements.

If your application only needs private object storage behind an access model you already own, a cloud object store may be simpler. Box is most useful when files are shared work objects that need permissions, collaboration, business context, or governance.

## How does Box prepare unstructured content for AI?

AI systems produce better answers when they use content that is current, relevant, and safe to access. A useful content preparation process has four parts:

<Steps>
  <Step title="Centralize access">
    Put the content your application needs in Box folders, or curate selected files and folders into [Box Hubs](/guides/hubs-api). You do not need to expose the whole enterprise to an AI system. Start with the smallest collection that supports the use case.
  </Step>

  <Step title="Add business context">
    File names and timestamps rarely explain what a document means. [Metadata](/guides/metadata) adds fields such as document type, owner, account, approval status, or review date. Use [Box AI Extract](/guides/box-ai/ai-tutorials/extract-metadata-structured) when those values are trapped inside the document.
  </Step>

  <Step title="Curate what AI can use">
    Separate approved content from drafts, stale files, and records that should not enter the workflow. Hubs give people and Box AI a curated knowledge set while preserving permissions on the source files. See the [answer bank tutorial](/tutorials/sales-rfp-answer-bank) for a working example.
  </Step>

  <Step title="Keep permissions in the request path">
    Box AI, Box Hubs, and the Box MCP server use the access available to the requesting user or application. Connecting an agent does not grant that agent access to every file in the enterprise. The identity, scopes, and file collaborations still determine what it can read or change.
  </Step>
</Steps>

## Choose an implementation path

| Goal | Box path | Start here |
| - | - | - |
| Build a content application | Platform Apps, SDKs, APIs, and UI Elements | [Platform Apps](/guides/applications/platform-apps) |
| Build grounded AI | Box AI Ask and Box AI Extract | [Box AI](/guides/box-ai) |
| Build a knowledge base | Governance metadata, Box Hubs, and Box AI | [Build your company brain](/tutorials/company-brain) |
| Connect an external agent | Box MCP search, content, metadata, and AI tools | [Box MCP server](/guides/box-mcp) |
| Automate document work | Content intake, AI, review, generation, and signature | [Intelligent workflow](/guides/intelligent-workflow) |
| Use your own retrieval stack | Selected Box content with an external vector database or model | [Build RAG over Box content](/ai/rag) |

## Box-managed retrieval or your own RAG pipeline?

Start with Box-managed retrieval when the source content already lives in Box and permission-aware answers are the main requirement.

<Columns>
  <Card title="Box-managed retrieval" icon="box">
    Use [Box Hubs](/guides/hubs-api) with [Box AI Ask](/guides/box-ai/ai-tutorials/ask-questions) when you need:

    * A curated set of source documents
    * Answers grounded in files the requesting user can access
    * Citations back to source content
    * Less retrieval infrastructure to operate
  </Card>

  <Card title="Your own RAG pipeline" icon="server">
    Build your own retrieval-augmented generation (RAG) pipeline when you need:

    * A retrieval engine or embedding model that Box AI does not provide
    * One index that combines Box content with data from other systems
    * Custom chunking, ranking, or evaluation logic
    * A model hosting or inference setup that you control
  </Card>
</Columns>

If you export Box content, your pipeline must enforce permissions and keep its index current as files, versions, and collaborations change. See [Build RAG over enterprise documents stored in Box](/ai/rag).

## Does the Box MCP server bypass Box permissions?

No. The [Box MCP server](/guides/box-mcp) acts through an authenticated Box user. Integration scopes set the maximum actions the client can request. Box permissions then decide which files and folders that user can access.

Use a dedicated test account and sample content while you develop. Before production, choose the user or application identity deliberately and request only the scopes the agent needs. See [permission-aware agent access](/guides/box-mcp/permission-aware-access) and [set up the MCP server](/guides/box-mcp/setup).

## What should you build first?

Start with the smallest path that proves Box fits the job:

1. Complete the [Quick Start](/guides/getting-started) to create an account, generate a developer token, and upload your first file.
2. [Plan your integration](/guides/getting-started/plan-your-integration) and choose an application type.
3. Pick one working use case from the [tutorials](/tutorials).
4. Replace the developer token with a production [authentication method](/guides/authentication) before deployment.

<Note>
  Product availability depends on your Box plan and enterprise settings. See [free developer plan information](/guides/getting-started/free-developer-plan) for included features and upgrade paths.
</Note>

## Learn more about AI-ready content

For the enterprise strategy behind content centralization, metadata-first curation, governance, and AI data quality, read [How companies centralize unstructured data for AI](https://blog.box.com/how-companies-centralize-unstructured-data-ai).


# Create Slack Integration Mapping
Source: https://developer.box.com/guides/integration-mappings/slack-mappings/create-mapping



Use the `POST integration_mappings/slack/:integration_mapping_id`
call to create a mapping. To make it work,
you need `box_item` and `partner_item` parameters,
which refer to a Box folder and a Slack channel, respectively.

<Info>
  Remember that before the mapping can be created,
  this service account must be set as a co-owner
  role on the folder that is being mapped.
  If you encounter any errors, see the <Link href="/guides/integration-mappings/slack-mappings/troubleshooting">troubleshooting guide</Link>.
</Info>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST "https://api.box.com/2.0/integration_mappings/slack" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H 'content-type: application/json' \
       -d '{
            "partner_item": {
                "id": "C987654321",
                "type": "channel",
                "slack_workspace_id": "T5555555"
            },
            "box_item": {
                "id": "123456789",
                "type": "folder"
            }
        }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.createSlackIntegrationMapping({
    partnerItem: new IntegrationMappingPartnerItemSlack({
      id: slackPartnerItemId,
      slackOrgId: slackOrgId,
    }),
    boxItem: new IntegrationMappingBoxItemSlack({ id: folder.id }),
  } satisfies IntegrationMappingSlackCreateRequest);
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.create_slack_integration_mapping(
      IntegrationMappingPartnerItemSlack(
          id=slack_partner_item_id, slack_org_id=slack_org_id
      ),
      IntegrationMappingBoxItemSlack(id=folder.id),
  )
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.CreateSlackIntegrationMappingAsync(requestBody: new IntegrationMappingSlackCreateRequest(partnerItem: new IntegrationMappingPartnerItemSlack(id: slackPartnerItemId) { SlackOrgId = slackOrgId }, boxItem: new IntegrationMappingBoxItemSlack(id: folder.Id)));
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.createSlackIntegrationMapping(requestBody: IntegrationMappingSlackCreateRequest(partnerItem: IntegrationMappingPartnerItemSlack(id: slackPartnerItemId, slackOrgId: slackOrgId), boxItem: IntegrationMappingBoxItemSlack(id: folder.id)))
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().createSlackIntegrationMapping(new IntegrationMappingSlackCreateRequest(new IntegrationMappingPartnerItemSlack.Builder(slackPartnerItemId).slackOrgId(slackOrgId).build(), new IntegrationMappingBoxItemSlack(folder.getId())))
  ```

  ```javascript Node v4 theme={null}
  const mapping = await client.integrationMappings.createSlackIntegrationMapping({
  	partner_item: {
  		type: 'channel',
  		id: 'C12378991223',
  		slack_org_id: 'E1234567'
  	},
  	box_item: {
  		id: '12345',
  		type: 'folder',
  	}
  });
  console.log(
      `Slack integration mapping with id ${mapping.id} was created`
  );
  ```
</CodeGroup>

You can provide options that change the default settings for the
created mapping. For example setting `is_access_management_disabled` to
`true` will disable collaboration management. Slack channel members will
not become collaborators on the channel folder and no shared links will
be created for channels with 1000+ members.

## Create Slack Integration Mapping with Box SDK

Use Box SDK to automatically create the Integration Mapping,
including a co-owner collaboration of the
service account on the Slack channel - Box folder mapping.
To do so, use this script:

```js theme={null}
const BoxSDK = require('box-node-sdk');
const axios = require('axios');

const integrationMappingsApiUrl = 'https://api.box.com/2.0/integration_mappings/slack'
const boxFolderId = 'PASTE YOUR FOLDER ID HERE';
const slackChannelId = 'PASTE YOUR CHANNEL ID HERE';
const slackOrgId = 'PASTE YOUR SLACK ORG ID HERE (CHANGE TO WORKSPACE ID IF NECESSARY)';
const developerToken = 'PASTE YOUR DEVELOPER TOKEN HERE';

let serviceAccountId = '<PLACEHOLDER>';

const client = BoxSDK.getBasicClient(developerToken);

async function postIntegrationMappingSlack(){
    return axios.post(integrationMappingsApiUrl, {
        partner_item: {
            id: slackChannelId,
            slack_org_id: slackOrgId, // change slack_org_id to slack_workspace_id if Box for Slack is installed on the workspace level
            type: "channel"
        },
        box_item: {
            id: boxFolderId,
            type: "folder"
        }
    }, {
        headers: {
            'Authorization': `Bearer ${developerToken}`
        }
    });
}

function isPlaceholder(str){
    return str === '<PLACEHOLDER>';
}

async function addCoowner(serviceAccountId, folderId){
    try {
        await client.collaborations.createWithUserID(serviceAccountId, folderId, 'co-owner')
    } catch (error){
        if(error.response.body.code === 'user_already_collaborator'){
            console.log('Service account already collaborated in the co-owner role.')
        } else {
            throw error;
        }
    }
}

async function logServiceAccountId() {
    try {
        await postIntegrationMappingSlack();
    } catch (error) {
        console.log(`Replace the value of serviceAccountId with: ${error.response.data.context_info.service_account_id} and re-run the script.`)
    }
}

async function createSlackIntegrationMapping() {
    if(isPlaceholder(serviceAccountId)){
        await logServiceAccountId();
    } else {
        await addCoowner(serviceAccountId, boxFolderId);
        await postIntegrationMappingSlack();
    }
}

module.exports = { createSlackIntegrationMapping }
```

<Note>
  Make sure to replace `PLACEHOLDER` with the logged value of
  `serviceAccountId`.
</Note>


# Delete Slack Integration Mapping
Source: https://developer.box.com/guides/integration-mappings/slack-mappings/delete-mapping



The `DELETE integration_mappings/slack/:integration_mapping_id`
call removes the mapping between the channel and the folder.
A new mapping and a new folder in the default folder structure will
be created when the next file is uploaded to the channel.
Deleting the mapping does not delete the Box folder, or the Slack channel.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X DELETE "https://api.box.com/2.0/integration_mappings/slack/512521" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.deleteSlackIntegrationMappingById(
    slackIntegrationMapping.id,
  );
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.delete_slack_integration_mapping_by_id(
      slack_integration_mapping.id
  )
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.DeleteSlackIntegrationMappingByIdAsync(integrationMappingId: slackIntegrationMapping.Id);
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.deleteSlackIntegrationMappingById(integrationMappingId: slackIntegrationMapping.id)
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().deleteSlackIntegrationMappingById(slackIntegrationMapping.getId())
  ```

  ```javascript Node v4 theme={null}
  await client.integrationMappings.deleteSlackIntegrationMappingById({
  	integration_mapping_id: 123456
  });
  ```
</CodeGroup>


# Slack Integration Mappings
Source: https://developer.box.com/guides/integration-mappings/slack-mappings/index



When [Box as the Content Layer][1] is enabled, a Box folder is created for
each channel, and all files uploaded to this channel are stored in this folder.
The <Link href="/reference/resources/integration-mapping-slack">Integration Mappings API</Link> allows the Box Enterprise Admin (EA) to
customize the upload folder of the Slack channel to any folder within
the enterprise instead of relying on the default one.

[1]: https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack


# List Slack Integration Mappings
Source: https://developer.box.com/guides/integration-mappings/slack-mappings/list-mappings



Use the `GET /integration_mappings/slack` call to
fetch and filter the mappings,
both the ones created manually by the admin
and those created
automatically by the integration.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X GET "https://api.box.com/2.0/integration_mappings/slack?partner_item_id=C987654321&box_item_id=123456789" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.getSlackIntegrationMapping();
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.get_slack_integration_mapping()
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.GetSlackIntegrationMappingAsync();
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.getSlackIntegrationMapping()
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().getSlackIntegrationMapping()
  ```

  ```javascript Node v4 theme={null}
  const integrationMappings = await client.integrationMappings.getSlackIntegrationMappings();
  console.log(`There are ${integrationMappings.entries.length} Slack integration mappings`);
  ```
</CodeGroup>


# Slack Integration Mappings Setup
Source: https://developer.box.com/guides/integration-mappings/slack-mappings/setup



Before starting work with Integration Mappings API, perform
the following steps.

## Roles

Make sure you have an Admin or a Co-admin role.

## Install and configure Box for Slack

1. Install [Box for Slack][1] in the relevant Slack workspace or organizations.
2. Enable the [Box as Content Layer for Slack][2].
3. Make sure the service account you are using is a collaborator on the folder that will be mapped. To do so, use the `Invite People` folder option to invite the service account as a collaborator.

If you encounter any errors, see the <Link href="/guides/integration-mappings/slack-mappings/troubleshooting">troubleshooting guide</Link>.

## Create Box application

1. Create a <Link href="/guides/authentication/oauth2/oauth2-setup">platform app with OAuth authentication</Link> in the [Box developer console][5].
2. Open the application and enable the **Manage enterprise properties** application scope under **Configuration** > **Required Access Scopes**.

<Info>
  For Slack-side channel validation, the <Link href="/reference/get-integration-mappings-slack">Integration Mappings API</Link>
  is calling the Slack API.
</Info>

## Authorization

To authorize your Integration Mappings requests:

1. Navigate to the <Link href="/guides/applications/platform-apps/index">platform app</Link> that you have created as one of the prerequisites.
2. Generate a <Link href="/guides/authentication/tokens/developer-tokens">developer token</Link> and add it to the HTTP header of each request:

```bash theme={null}
Authorization: Bearer {developer_token}
```

<Info>
  The developer token is valid for 60 minutes. After that time you need
  to generate it again.
</Info>

[1]: https://support.box.com/hc/en-us/articles/360044195313-Installing-and-Using-the-Box-for-Slack-Integration

[2]: https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack

[5]: https://app.box.com/developers/console


# Slack Integration Mappings Troubleshooting
Source: https://developer.box.com/guides/integration-mappings/slack-mappings/troubleshooting



As the Integration Mappings API performs different types of
validation, some errors might occur. You can find descriptions
and solutions to these common errors below.

## Service account is not a co-owner of the folder

The [Box as Content Layer for Slack][1] service account must be added
as an owner or co-owner of the folder to manage collaborations and uploads.

```sh theme={null}
Box as File Storage for Slack (user id: 123, user email:
user@example.com) must be a collaborator in role co-owner or owner
of the folder example123, before it can be mapped to the channel
example123. Please create a collaboration or ensure the ownership for
Box as File Storage for Slack and retry.`
```

To resolve this error use the data in the response to make sure the
service account has the necessary role to perform the mapping.

```json theme={null}
"context_info": {
  "service_account_id": "12345678",
  "service_account_email": "AutomationUser_12345678_gdueygwe@boxdevedition.com",
}
```

Perform the following steps:

1. Copy the `service_account_email` from `context_info`.
2. In the folder settings, use the `Invite People` option to invite the service account as a co-owner.

## Channel is already mapped to a folder in Box

API returns the following error when you attempt to create
a mapping for a channel that already has a Box folder mapped:

```sh theme={null}
Channel: example123 is already mapped to a folder in Box.
```

If you wanted to start using a new folder, use `GET` to retrieve
the `id` of the mapping and then the `UPDATE` method to update the
target Box folder.

## Channel was not found

API returns this error if the Slack bot associated with the integration
can not retrieve information about the channel.

```sh theme={null}
Channel: example123 was not found. If it is a private channel, ensure that Box has been added to the channel.
```

Ensure that the `partner_item` is correct - make sure you provide `slack_org_id`
for org installations and `slack_workspace_id` for workspace ones. If the
channel is private, ensure that the Slack bot has been added to the channel.

## Channel not suitable for Custom File Storage (CFS)

```sh theme={null}
Channel: example123 is not suitable for CFS. Slack Connect channels with
a pending Connect status can not be mapped to Box folders.
```

Slack Connect channels (cross enterprise channels) are currently not supported
as a part of Box as a Content Layer for Slack.

## Box folder externally owned

Box folder selected for mapping must be owned by the enterprise that the Admin
is part of.

```sh theme={null}
Box folder: example123 cannot be mapped, because it is externally owned. Mapped folder must belong to the enterprise: example_enterprise.
```

## Custom File Storage (CFS) turned off

API returns this error when you're trying to create the mapping for an
enterprise that has Box for Slack installed, but did not enable
[Box as a Content Layer for Slack][1].

## Box enterprise mismatch

API returns this error when there is a mismatch between the Admin’s enterprise
and Box for Slack configuration. See [Installing and using Box for Slack][2]
for information on how to enable Box for Slack.

[1]: https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack

[2]: https://support.box.com/hc/en-us/articles/360044195313-Installing-and-Using-the-Box-for-Slack-Integration


# Update Slack Integration Mapping
Source: https://developer.box.com/guides/integration-mappings/slack-mappings/update-mapping



Use the `PUT integration_mappings/slack/:integration_mapping_id`
call to update the existing mapping or the target Box folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X PUT "https://api.box.com/2.0/integration_mappings/slack/512521" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
           "options": {
              "is_access_management_disabled": true
          }
      }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.updateSlackIntegrationMappingById(
    slackIntegrationMapping.id,
    {
      requestBody: {
        boxItem: new IntegrationMappingBoxItemSlack({ id: folder.id }),
      } satisfies UpdateSlackIntegrationMappingByIdRequestBody,
    } satisfies UpdateSlackIntegrationMappingByIdOptionalsInput,
  );
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.update_slack_integration_mapping_by_id(
      slack_integration_mapping.id, box_item=IntegrationMappingBoxItemSlack(id=folder.id)
  )
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.UpdateSlackIntegrationMappingByIdAsync(integrationMappingId: slackIntegrationMapping.Id, requestBody: new UpdateSlackIntegrationMappingByIdRequestBody() { BoxItem = new IntegrationMappingBoxItemSlack(id: folder.Id) });
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.updateSlackIntegrationMappingById(integrationMappingId: slackIntegrationMapping.id, requestBody: UpdateSlackIntegrationMappingByIdRequestBody(boxItem: IntegrationMappingBoxItemSlack(id: folder.id)))
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().updateSlackIntegrationMappingById(slackIntegrationMapping.getId(), new UpdateSlackIntegrationMappingByIdRequestBody.Builder().boxItem(new IntegrationMappingBoxItemSlack(folder.getId())).build())
  ```

  ```javascript Node v4 theme={null}
  const mapping = await client.integrationMappings.updateSlackIntegrationMapping({
  	box_item: {
  		id: '12345',
  		type: 'folder'
  	},
  	options: {
  		is_access_management_disabled: true
  	}
  }, {
  	integration_mapping_id: integrationMappingId
  });

  console.log(
      `Slack integration mapping with id ${mapping.id} was updated`
  );
  ```
</CodeGroup>


# Create Teams integration mappings
Source: https://developer.box.com/guides/integration-mappings/teams-mappings/create-mappings



Use the `POST integration_mappings_teams` call to create a mapping.
To make it work, you need the `box_item` and the `partner_item` parameters,
which refer to a Box folder and a Teams channel, respectively.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST "https://api.box.com/2.0/integration_mappings/teams" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H 'content-type: application/json' \
       -d '{
            "partner_item": {
                "id": "19%3ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2",
                "type": "channel",
                "team_id": "hjgjgjg-bhhj-564a-b643-hghgj685u",
                "tenant_id": "E1234567"
            },
            "box_item": {
                "id": "42037322",
                "type": "folder"
            }
        }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.createTeamsIntegrationMapping({
    partnerItem: {
      type: 'channel' as IntegrationMappingPartnerItemTeamsCreateRequestTypeField,
      id: partnerItemId,
      tenantId: tenantId,
      teamId: teamId,
    } satisfies IntegrationMappingPartnerItemTeamsCreateRequest,
    boxItem: new FolderReference({ id: folder.id }),
  } satisfies IntegrationMappingTeamsCreateRequest);
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.create_teams_integration_mapping(
      IntegrationMappingPartnerItemTeamsCreateRequest(
          type=IntegrationMappingPartnerItemTeamsCreateRequestTypeField.CHANNEL,
          id=partner_item_id,
          tenant_id=tenant_id,
          team_id=team_id,
      ),
      FolderReference(id=folder.id),
  )
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.CreateTeamsIntegrationMappingAsync(requestBody: new IntegrationMappingTeamsCreateRequest(partnerItem: new IntegrationMappingPartnerItemTeamsCreateRequest(type: IntegrationMappingPartnerItemTeamsCreateRequestTypeField.Channel, id: partnerItemId, tenantId: tenantId, teamId: teamId), boxItem: new FolderReference(id: folder.Id)));
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.createTeamsIntegrationMapping(requestBody: IntegrationMappingTeamsCreateRequest(partnerItem: IntegrationMappingPartnerItemTeamsCreateRequest(type: IntegrationMappingPartnerItemTeamsCreateRequestTypeField.channel, id: partnerItemId, tenantId: tenantId, teamId: teamId), boxItem: FolderReference(id: folder.id)))
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().createTeamsIntegrationMapping(new IntegrationMappingTeamsCreateRequest(new IntegrationMappingPartnerItemTeamsCreateRequest(IntegrationMappingPartnerItemTeamsCreateRequestTypeField.CHANNEL, partnerItemId, tenantId, teamId), new FolderReference(folder.getId())))
  ```
</CodeGroup>


# Delete Teams integration mappings
Source: https://developer.box.com/guides/integration-mappings/teams-mappings/delete-mappings



The `DELETE integration_mappings_teams_id` call removes the mapping between
the channel and the folder.
A new mapping and a new folder in the default folder structure will be created
when the next file is uploaded to the channel.
Deleting the mapping does not delete the Box folder or the Teams channel.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X DELETE "https://api.box.com/2.0/integration_mappings/teams/342423" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.deleteTeamsIntegrationMappingById(
    integrationMappingId,
  );
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.delete_teams_integration_mapping_by_id(
      integration_mapping_id
  )
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.DeleteTeamsIntegrationMappingByIdAsync(integrationMappingId: integrationMappingId);
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.deleteTeamsIntegrationMappingById(integrationMappingId: integrationMappingId)
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().deleteTeamsIntegrationMappingById(integrationMappingId)
  ```
</CodeGroup>


# Teams integration mappings
Source: https://developer.box.com/guides/integration-mappings/teams-mappings/index



Before you can start working with [Teams][2] integration mapping API,
perform the steps below.

## Prerequisites

* Admin or Co-Admin role
* [Box for Microsoft Teams][1] integration installed

## Create a Box application

1. Create a <Link href="/guides/authentication/oauth2/oauth2-setup">platform app with OAuth authentication</Link> in the [Box developer console][3].
2. Open the application and enable the **Manage enterprise properties** application scope under **Configuration** > **Required Access Scopes**.

## Authorize integration mappings requests

1. Navigate to the <Link href="/guides/applications/platform-apps/index">platform app</Link> that you have created as one of the prerequisites.
2. Generate a <Link href="/guides/authentication/tokens/developer-tokens">developer token</Link> and add it to the HTTP header of each request:

```bash theme={null}
Authorization: Bearer {developer_token}
```

<Info>
  The developer token is valid for 60 minutes. After that time, you need
  to generate it again.
</Info>

[1]: https://support.box.com/hc/en-us/articles/360050737154-Assigning-a-Default-Box-Folder-to-a-Teams-Channel-or-Chat

[2]: https://support.box.com/hc/en-us/articles/360044667034-Introducing-Box-for-Microsoft-Teams

[3]: https://app.box.com/developers/console


# List Teams integration mappings
Source: https://developer.box.com/guides/integration-mappings/teams-mappings/list-mappings



Use the `GET /integration_mappings/teams` call to fetch and filter the mappings,
both the ones created manually by the admin and those created automatically by the
integration.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X GET "https://api.box.com/2.0/integration_mappings/teams" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.getTeamsIntegrationMapping();
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.get_teams_integration_mapping()
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.GetTeamsIntegrationMappingAsync();
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.getTeamsIntegrationMapping()
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().getTeamsIntegrationMapping()
  ```
</CodeGroup>


# Update Teams integration mappings
Source: https://developer.box.com/guides/integration-mappings/teams-mappings/update-mappings



Use the `PUT integration_mappings_teams_id` call to update the
existing mapping of the target Box folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X PUT "https://api.box.com/2.0/integration_mappings/teams/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "box_item": {
           "type": "folder",
           "id": "1234567"
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.integrationMappings.updateTeamsIntegrationMappingById(
    integrationMappingId,
    {
      requestBody: {
        boxItem: new FolderReference({ id: '1234567' }),
      } satisfies UpdateTeamsIntegrationMappingByIdRequestBody,
    } satisfies UpdateTeamsIntegrationMappingByIdOptionalsInput,
  );
  ```

  ```python Python v10 theme={null}
  user_client.integration_mappings.update_teams_integration_mapping_by_id(
      integration_mapping_id, box_item=FolderReference(id="1234567")
  )
  ```

  ```cs .NET v10 theme={null}
  await userClient.IntegrationMappings.UpdateTeamsIntegrationMappingByIdAsync(integrationMappingId: integrationMappingId, requestBody: new UpdateTeamsIntegrationMappingByIdRequestBody() { BoxItem = new FolderReference(id: "1234567") });
  ```

  ```swift Swift v10 theme={null}
  try await userClient.integrationMappings.updateTeamsIntegrationMappingById(integrationMappingId: integrationMappingId, requestBody: UpdateTeamsIntegrationMappingByIdRequestBody(boxItem: FolderReference(id: "1234567")))
  ```

  ```java Java v10 theme={null}
  userClient.getIntegrationMappings().updateTeamsIntegrationMappingById(integrationMappingId, new UpdateTeamsIntegrationMappingByIdRequestBody.Builder().boxItem(new FolderReference("1234567")).build())
  ```
</CodeGroup>


# Connect SSO identities to app users
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-identities



Your SSO service will have a unique user record for each person using it within
your company. When accessing a Box application through this SSO service, if
we're creating a Box user for each SSO user, then we need to create an
association between the SSO user and Box user records.

When a user logs in to Box through the SSO service we will first search for the
user by the association. If a Box user record is found we can begin making
calls as that user to Box APIs. If there is no Box user found we will then create
a new Box user with the association to the unique SSO user account.

Exploring the top level of a Box <Link href="/reference/resources/user">user object</Link> we can see
the available options for adding the unique identifier from the SSO service
user object into the Box user object to bind the two together.

```json theme={null}
{
  "address": "900 Jefferson Ave, Redwood City, CA 94063",
  "avatar_url": "https://www.box.com/api/avatar/large/181216415",
  "can_see_managed_users": true,
  "created_at": "2012-12-12T10:53:43-08:00",
  "enterprise": { .. },
  "external_app_user_id": "my-user-1234",
  "hostname": "https://example.app.box.com/",
  "id": 11446498,
  "is_exempt_from_device_limits": true,
  "is_exempt_from_login_verification": true,
  "is_external_collab_restricted": true,
  "is_platform_access_only": true,
  "is_sync_enabled": true,
  "job_title": "CEO",
  "language": "en",
  "login": "ceo@example.com",
  "max_upload_size": 2147483648,
  "modified_at": "2012-12-12T10:53:43-08:00",
  "my_tags": [ .. ],
  "name": "Aaron Levie",
  "notification_email": { ... },
  "phone": 6509241374,
  "role": "admin",
  "space_amount": 11345156112,
  "space_used": 1237009912,
  "status": "active",
  "timezone": "Africa/Bujumbura",
  "tracking_codes": [{ .. }],
  "type": "user"
}
```

There are two recommended methods for creating a binding between a unique user
within the SSO service and a Box user, placing the unique SSO user ID within
the Box user `external_app_user_id` field, or using the unique SSO email address
as the login email for the new user.

## Using `external_app_user_id` (recommended method)

The `external_app_user_id` field was designed to hold a string identifier to
associate a Box user record with an external service, such as an SSO provider
user record.

<Warning>
  You can retrieve app users for a specific application only if such app
  users were created by this application.
  If you use one application to search for users
  created by a different one, no data will be returned.
</Warning>

Using the `external_app_user_id` field for associating the unique SSO user
account with a Box user account is the preferred method of connecting the two
accounts over email, for a number of reasons:

* Email association is only viable for <Link href="/guides/getting-started/users#managed-users">managed users</Link>. <Link href="/guides/getting-started/users#app-user">App users</Link> are automatically assigned an email address by Box, meaning that you cannot assign the `login` to be the email from the SSO service.
* Emails have to be unique in Box. This means that if your SSO service user signed up for Box using the same email address, which is not within your Box enterprise, then you will not be able to create a user with that email and won't be able to connect to that existing user.
* The `external_app_user_id` field was designed for this purpose.

## Using `login` (alternative method)

Using the `login` field of a user object to create an account association is
viable under a few conditions:

* Only the <Link href="/guides/getting-started/users#managed-users">managed users</Link> type is being used, not <Link href="/guides/getting-started/users#app-user">app users</Link>.
* All email addresses and Box account creation requests are managed by your enterprise, meaning that users cannot independently create Box accounts with those email addresses.

<Warning>
  Email addresses used for users in Box, under the `login` field, must be
  unique. Making a request to create a user with an email that already exists
  for another account will result in a `409 Conflict` error, stating that
  `user_login_already_used`
</Warning>

<RelatedLinks title="RELATED APIS" />


# Configure Box (Okta integration)
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-box



<ProgressBar />

Once we have created a login experience with Okta we need to have a Box
application available that will permit us to use the Box APIs to search for and
create users that are associated with the Okta user account.

## Set up a Box app

<Grid>
  <Choose>
    # Create a new Box app

    Create and configure a new Box JWT application to start with a clean user list.
  </Choose>

  <Choose>
    # Use an existing approved app

    Use one of your existing admin approved Box JWT applications from the Box developer
    console.
  </Choose>
</Grid>

<Choice>
  # Create a new Box app

  To create a new Box application that may be used to call the Box APIs, use
  the following steps.

  1. Go to the [Developer Console][devconsole]
  2. Select **Create Platform App**
  3. Select **Platform App** as the type of application to create, and click **Next**
  4. Select **OAuth 2.0 with JWT** as the authentication method, and click **Next**
  5. Give your Box app a unique name and click **Create App**
  6. Go to the app's configuration by clicking **View Your App**.
  7. Scroll to the **Required Access Scopes** section of the same screen and ensure that at least the following scopes are enabled:
     * Read and write all files and folders stored in Box
     * Manage Users
  8. Under **Advanced Features** ensure that both options are enabled to perform actions as users and generate user access tokens.
  9. At the top of the page click the button to **Save Changes**

  <Warning>
    Once the application is created it will still need to be approved by an
    enterprise admin before you will be able to make calls to the Box APIs.
  </Warning>

  Follow <Link href="/guides/authorization/platform-app-approval">this guide</Link> to have the
  application approved in your enterprise.
</Choice>

<Choice>
  # Use an Existing JWT Box application

  If you have an existing JWT based Box application in your
  [developer console][devconsole] that you would like to use, ensure that the
  following options are set in the **Configuration** section of your
  application.

  * Authentication Method: Should be set to OAuth 2.0 with JWT (Server Authentication).
  * Application Scopes: Set at least the following scopes.
    * Read and write all files and folders stored in Box
    * Manage Users
  * Advanced Features: Both options should be enabled to perform actions as users and generate user access tokens.
</Choice>

## Download Required Data

To begin working with the Box SDKs used in this tutorial, you will need the
application configuration file from the **Configuration** page of your
application. This will include all information needed to verify your
application to start making API requests with the Box SDKs.

Within the **Add and Manage Public Keys** section of the **Configuration**
page, click to **Generate a Public/Private Keypair**. This will send you
through 2FA verification before downloading the configuration file for your
application.

Store that file as `config.json` in a location accessible by your application.

## Summary

* You created a new, or are using an existing, Box app which is approved by an enterprise admin.
* You downloaded your application configuration file and stored it in a location accessible by your application.

<Observe>
  <Next>I downloaded my application configuration file</Next>
</Observe>

[devconsole]: https://cloud.app.box.com/developers/console


# Configure Okta
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta



<ProgressBar />

Our next step in the Okta / Box integration is to create and configure the Okta
application and users, then extract a few pieces of information that we will
need to connect to Okta in our application.

<Frame>
  <img alt="Okta Application Dashboard" />
</Frame>

For this tutorial we will be starting with a blank Okta application and user
dashboard to avoid any negative effects on existing installations that may be
in place, and to ensure that we have admin rights to the instance.

## Create an Okta Application

Starting from the [Okta developer site][okta-dev], sign up for a new developer
account, or log in under your personal account if you already have one.

If you're logging in with an existing account, you should see the Okta
dashboard. Click on the **Admin** button at the top right.

<Frame>
  <img alt="Okta Application Dashboard" />
</Frame>

If you've created a new developer account rather than logging into an existing
account, you will have already been redirected to the admin dashboard.

You should now see the admin panel. Click on the **Applications** option at the
top.

<Frame>
  <img alt="Okta Admin Dashboard" />
</Frame>

On the application page, click the **Add Application** button. Select **Web**
as the application type and click the **Next** button.

<Frame>
  <img alt="Okta App Types" />
</Frame>

Okta employs both [OAuth 2][oauth2] and [OpenID Connect][openid-connect] (OIDC)
for application authorization and user authentication, respectively. The OpenID
Connect integration allows us to use baked in OIDC connectors within a number
of popular language frameworks to simplify application and user management by
handling the callback routes and providing methods for logging in,
logging out, and protecting routes into your application.

To simplify this first integration, we're going to use the default callback
routes and settings for the language and framework OIDC connector. Depending on
your preferred integration type, the configuration settings will slightly
change.

Fill out the application details with the following configuration settings:

<Choice>
  * Name: Any
  * Base URIs: `http://localhost:3000/`
  * Login redirect URIs: `http://localhost:3000/authorization-code/callback`
  * Logout redirect URIs: `http://localhost:3000/logout`
  * Grant type allowed: Only **Authorization Code** selected

  <Frame>
    <img alt="Okta App Configuration" />
  </Frame>
</Choice>

<Choice>
  * Name: Any
  * Base URIs: `http://localhost:8080/`
  * Login redirect URIs: `http://localhost:8080/authorization-code/callback`
  * Logout redirect URIs: `http://localhost:8080/logout`
  * Grant type allowed: Only **Authorization Code** selected

  <Frame>
    <img alt="Okta App Configuration" />
  </Frame>
</Choice>

<Choice>
  * Name: Any
  * Base URIs: `http://127.0.0.1:5000/`
  * Login redirect URIs: `http://127.0.0.1:5000/oidc/callback`
  * Logout redirect URIs: `http://127.0.0.1:5000/logout`
  * Grant type allowed: Only **Authorization Code** selected

  <Frame>
    <img alt="Okta App Configuration" />
  </Frame>
</Choice>

<Choice>
  * Name: Any
  * Base URIs: `https://localhost:5001/`
  * Login redirect URIs: `https://localhost:5001/authorization-code/callback`
  * Logout redirect URIs: `https://localhost:5001/logout`
  * Grant type allowed: Only **Authorization Code** selected

  <Frame>
    <img alt="Okta App Configuration" />
  </Frame>
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

Click the **Done** button to create the application and be dropped on to the
general settings of the application.

## Copy Application Credentials

Using the configuration files set up in the last step, we next have to add in
the Okta application org and app details within the files.

Most Okta application information can be found on the general settings page,
with the exception of the `Org URL` that is used in the configuration URIs to
reference back to your Okta organization. To obtain the `Org URL`, go to the
dashboard of your Okta admin console. The `Org URL` will be in the top right
corner of the screen.

Depending on the language and framework previously chosen, we'll set up the
appropriate configuration files.

<Frame>
  <img alt="Okta Org URL" />
</Frame>

<Choice>
  * Open `config.json` within the local application directory in your preferred editor.
  * Update the following line items with the appropriate Okta configuration info:
    * `oktaClientId`: Obtained from the **Client Credentials** section of the application general settings.
    * `oktaClientSecret`: Obtained from the **Client Credentials** section of the application general settings.
    * `oktaOrgUrl`: Obtained from the top right of the main admin dashboard page.
  * Save the file.

  Your `config.json` file should look similar to the following.

  ```js theme={null}
  const oktaClientId = exports.oktaClientId = '0oa48567frkg5KW4x6';
  const oktaClientSecret = exports.oktaClientSecret = 'cugDJy2ERfIQHDXv-j2134DfTTes-Sa3';
  const oktaOrgUrl = exports.oktaOrgUrl = 'YOURDOMAIN.okta.com';
  const oktaBaseUrl = exports.oktaBaseUrl = 'http://localhost:3000';
  const oktaRedirect = exports.oktaRedirect = '/authorization-code/callback';
  ```
</Choice>

<Choice>
  * Open the `/src/main/resources/application.properties` file and update the following lines:
    * `okta.oauth2.issuer`: Your Org URL, obtained from the top right of the main admin dashboard page, followed by `/oauth2/default`. For example, if your Org URL was `https://dev-123456.okta.com`, the issuer string should be `https://dev-123456.okta.com/oauth2/default`.
    * `okta.oauth2.clientId`: Obtained from the **Client Credentials** section of the application general settings.
    * `okta.oauth2.clientSecret`: Obtained from the **Client Credentials** section of the application general settings.
  * Save the file.

  Your `/src/main/resources/application.properties` file should look similar to
  the following.

  ```java theme={null}
  okta.oauth2.redirect-uri=/authorization-code/callback
  okta.oauth2.issuer=https://YOURDOMAIN.okta.com/oauth2/default
  okta.oauth2.clientId=0oa48567frkg5KW4x6
  okta.oauth2.clientSecret=cugDJy2ERfIQHDXv-j2134DfTTes-Sa3
  security.oauth2.sso.loginPath=/authorization-code/callback
  ```
</Choice>

<Choice>
  In addition to the standard configuration information for the org and app, the
  Python / Flask integration requires an additional auth token.

  To create an auth token:

  * Go to the **API** -> **Token** section of the Okta admin dashboard.
  * Click the **Create Token** button.
  * Enter a name for the token and click **Create**.
  * Copy the token that is generated.

  Next, update the local application configuration file.

  * Open `config.py` within the local application directory in your preferred editor.
  * Update the following line items with the appropriate Okta configuration info:
    * `okta_client_secret`: Obtained from the **Client Credentials** section of the application general settings.
    * `okta_org_url`: Obtained from the top right of the main admin dashboard page.
    * `okta_auth_token`: The token created above.
  * Save the file.

  Your `config.py` file should look similar to the following.

  ```python theme={null}
  okta_client_id = '0oa48567frkg5KW4x6'
  okta_client_secret = 'cugDJy2ERfIQHDXv-j2134DfTTes-Sa3'
  okta_org_url = 'http://YOURDOMAIN.okta.com'
  okta_auth_token = '01KkTQTRfs1yKLr4Ojy26iqoIjK_4fHyq132Dr5T'
  okta_callback_route = '/oidc/callback'
  ```

  Lastly, update the Flask configuration file.

  * Open `client_secrets.json` within the local application directory in your preferred editor.
  * Update the following line items with the appropriate Okta configuration info:
    * `client_id`: Obtained from the **Client Credentials** section of the application general settings.
    * `client_secret`: Obtained from the **Client Credentials** section of the application general settings.
    * `auth_uri`: Your Org URL, obtained from the top right of the main admin dashboard page, followed by `/oauth2/default/v1/authorize`. For example, if your Org URL was `https://dev-123456.okta.com`, the issuer string should be `https://dev-123456.okta.com/oauth2/default/v1/authorize`.
    * `token_uri`: Your Org URL, obtained from the top right of the main admin dashboard page, followed by `/oauth2/default/v1/token`. For example, if your Org URL was `https://dev-123456.okta.com`, the issuer string should be `https://dev-123456.okta.com/oauth2/default/v1/token`.
    * `issuer`: Your Org URL, obtained from the top right of the main admin dashboard page, followed by `/oauth2/default`. For example, if your Org URL was `https://dev-123456.okta.com`, the issuer string should be `https://dev-123456.okta.com/oauth2/default`.
    * `userinfo_uri`: Your Org URL, obtained from the top right of the main admin dashboard page, followed by `/oauth2/default/userinfo`. For example, if your Org URL was `https://dev-123456.okta.com`, the issuer string should be `https://dev-123456.okta.com/oauth2/default/userinfo`.
  * Save the file.

  Your `client_secrets.json` file should look similar to the following.

  ```json theme={null}
  {
    "web": {
      "client_id": "0oa48567frkg5KW4x6",
      "client_secret": "cugDJy2ERfIQHDXv-j2134DfTTes-Sa3",
      "auth_uri": "https://YOURDOMAIN.okta.com/oauth2/default/v1/authorize",
      "token_uri": "https://YOURDOMAIN.okta.com/oauth2/default/v1/token",
      "issuer": "https://YOURDOMAIN.okta.com/oauth2/default",
      "userinfo_uri": "https://YOURDOMAIN.okta.com/oauth2/default/userinfo",
      "redirect_uris": [
        "http://127.0.0.1:5000/oidc/callback"
      ]
    }
  }
  ```
</Choice>

<Choice>
  * Open `Startup.cs` within the local application directory in your preferred editor.
  * Update the following line items within the `ConfigureServices` method with the appropriate Okta configuration info:
    * `OktaDomain`: Obtained from the top right of the main admin dashboard page.
    * `ClientId`: Obtained from the **Client Credentials** section of the application general settings.
    * `ClientSecret`: Obtained from the **Client Credentials** section of the application general settings.
  * Save the file.

  Your `ConfigureServices` method should look similar to the following.

  ```csharp theme={null}
  services.AddControllersWithViews();
  services.AddAuthentication(options =>
  {
      options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
      options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
      options.DefaultChallengeScheme = OktaDefaults.MvcAuthenticationScheme;
  })
  .AddCookie()
  .AddOktaMvc(new OktaMvcOptions
  {
      OktaDomain = "https://YOURDOMAIN.okta.com",
      ClientId = "0oa48567frkg5KW4x6",
      ClientSecret = "cugDJy2ERfIQHDXv-j2134DfTTes-Sa3"
  });
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Create a User

Our last step in the Okta setup is to create a test user that we will use to
log in to the application.

1. Go to the **Users** section of the Okta admin dashboard.
2. Click on the **Add Person** button.
3. Enter all appropriate user info. Under password, select **Set by admin** and input a password for the user. Also deselect the **User must change password on first login** option. You will use the username and password to log in. These settings will only be used for testing purposes and are not best practices for user creation and security.
4. Click the **Save** button to create the user.

## Summary

* You created an Okta application.
* You updated the Okta configuration information in the local application.
* You created a test Okta user.

<Observe>
  <Next>I've created my Okta app and set up user / local configuration</Next>
</Observe>

[okta-dev]: https://developer.okta.com/

[oauth2]: https://oauth.net/2/

[openid-connect]: https://openid.net/


# Find or create Box app users
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/find-or-create-box-users



<ProgressBar />

At this point we have application code that will handle traffic from users
visiting, forward them to Okta to login, provide Okta user information, before
finally handing off to a yet to be created handler for Box.

This section will cover the final Box components:

* Validating if an Okta user has an associated Box app user account.
* Creating a new app user for the associated Okta record if they don't.
* Fetching tokens for the Box user to make user-specific API calls.

## Create Platform App Users

Before validating users we need a method for creating an associated Box user
account if one doesn't already exist for the Okta user.

<Choice>
  In your local application directory, load the `server.js` file created in
  step 1.

  Add the following `box` object into the file and save.

  ```js theme={null}
  const box = (() => {
      const configJSON = JSON.parse(fs.readFileSync(path.resolve(__dirname, './config.json')));
      const sdk = boxSDK.getPreconfiguredInstance(configJSON);
      const client = sdk.getAppAuthClient('enterprise');

      let oktaRecord = {};
      let userId = '';
      let userClient;

      function validateUser(userInfo, res) {
          // TODO: VALIDATE USER
      }

      function createUser(res) {
          // TODO: CREATE USER
      }

      return {
          validateUser,
          createUser
      };
  })();
  ```

  This object defines a number of items:

  * Configuration: A new instance of the Box Node SDK is instantiated and made available to the object functions, along with a number of variables.
  * `validateUser` function: Will house the code to validate whether a Box user exists for an associated Okta user.
  * `createUser` function: Creates a new Box user bound to the associated Okta user ID.

  With that structure defined, replace the `// TODO: CREATE USER` section with
  the following code.

  ```js theme={null}
  const spaceAmount = 1073741824;   // ~ 1gb

  client.enterprise.addAppUser(
      this.oktaRecord.name,
      {
        space_amount: spaceAmount,
        external_app_user_id: this.oktaRecord.sub
      }
  ).then(appUser => {
      res.send(`New user created: ${appUser.name}`);
  });
  ```

  This code will create a new Box app user and will set the
  `external_app_user_id` parameter of the user object to the unique Okta user ID,
  which will define the binding between the two user records.
</Choice>

<Choice>
  In your local application directory, load the
  `/src/main/java/com/box/sample/Application.java` file created in step 1, or
  similar directory if an alternate application name was used.

  Within the `public class Application` definition, add the following methods:

  ```java theme={null}
  static String validateUser(OidcUser user) throws IOException {
      // TODO: VALIDATE USER
  }

  static String createUser(OidcUser user) {
      // TODO: CREATE USER
  }
  ```

  These methods will handle the Box user validation and creation. Breaking them
  down:

  * `validateUser`: Will house the code to validate whether a Box user exists for an associated Okta user.
  * `createUser`: Creates a new Box user bound to the associated Okta user ID.

  With those methods defined, replace `# TODO: CREATE USER` with the following
  code:

  ```java theme={null}
  String oktaName = (String) user.getAttributes().get("name");
  Object oktaSub = user.getAttributes().get("sub");

  CreateUserParams params = new CreateUserParams();
  params.setExternalAppUserId((String) oktaSub);
  BoxUser.Info createdUserInfo = BoxUser.createAppUser(api, oktaName, params);

  return "New User Created: " + createdUserInfo.getName();
  ```

  This code will create a new Box app user and will set the
  `external_app_user_id` parameter of the user object to the unique Okta user ID,
  which will define the binding between the two user records.
</Choice>

<Choice>
  In your local application directory, load the `server.py` file created in step
  1\.

  Add the following `Box` class object to the existing code, below the route
  definitions.

  ```python theme={null}
  # Box user class
  class Box(object):
      def __init__(self):
          # Instantiate Box Client instance
          auth = JWTAuth.from_settings_file('../config.json')
          self.box_client = Client(auth)

      # Validate if Box user exists
      def validateUser(self, g):
          # TODO: VALIDATE USER

      # Create new Box user
      def createUser(self, ouser):
          # TODO: CREATE USER
  ```

  This class defines:

  * `init`: When initialized, a new instance of the Box Python SDK is instantiated and made available to the object methods.
  * `validateUser` method: Accepting a user object as input, this will house the code to validate whether a Box user exists for an associated Okta user.
  * `createUser` method: Accepting a user object as input, this creates a new Box user bound to the associated Okta user ID.

  With that class defined, replace the `# TODO: CREATE USER` section with
  the following code.

  ```python theme={null}
  user_name = f'{ouser.profile.firstName} {ouser.profile.lastName}'
  uid = ouser.id
  space = 1073741824

  user = self.box_client.create_user(user_name, None, space_amount=space, external_app_user_id=uid)
  return f'New user created: {user_name}'
  ```

  This code will create a new Box app user and will set the
  `external_app_user_id` parameter of the user object to the unique Okta user ID,
  which will define the binding between the two user records.
</Choice>

<Choice>
  Within the `Controllers` > `AccountController.cs` file, inside the associated
  `AccountController` class, add the following method.

  ```csharp theme={null}
  static async Task validateUser(string name, string sub)
  {
      // Configure Box SDK instance
      var reader = new StreamReader("config.json");
      var json = reader.ReadToEnd();
      var config = BoxConfig.CreateFromJsonString(json);
      var sdk = new BoxJWTAuth(config);
      var token = sdk.AdminToken();
      BoxClient client = sdk.AdminClient(token);

      // Search for matching Box app user for Okta ID
      BoxCollection<BoxUser> users = await client.UsersManager.GetEnterpriseUsersAsync(externalAppUserId:sub);
      System.Diagnostics.Debug.WriteLine(users.TotalCount);

      if (users.TotalCount > 0)
      {
           // TODO: VALIDATE USER
      }
      else
      {
          // TODO: CREATE USER
      }
  }
  ```

  Within the code block a new Box .NET SDK client is created using the
  `config.json` file downloaded in step 2. In the case of this code sample, that
  `config.json` file is stored at the root of the local application directory.

  That client is then used to search all users in the Box enterprise, passing in
  the Okta `sub` unique ID as the `externalAppUserId` search parameter. The
  number of users returned is then checked to see if a valid user was found.

  With that structure defined, replace the // TODO: CREATE USER section with the
  following code.

  ```csharp theme={null}
  var userRequest = new BoxUserRequest()
  {
      Name = name,
      ExternalAppUserId = sub,
      IsPlatformAccessOnly = true
  };
  var user = await client.UsersManager.CreateEnterpriseUserAsync(userRequest);
  System.Diagnostics.Debug.WriteLine("New user created: " + user.Name);
  ```

  This code will create a new Box app user and will set the
  `external_app_user_id` parameter of the user object to the unique Okta user ID,
  which will define the binding between the two user records.

  A diagnostic message is then written back stating that the new user was created.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Validate Okta Users

With the create user functionality defined, let's turn our attention to
defining the code for validating whether an Okta user record has an associated
Box user record by searching all Box enterprise users for the associated
`external_app_user_id`.

<Choice>
  Replace the `// TODO: VALIDATE USER` comment with the following:

  ```js theme={null}
  this.oktaRecord = userInfo

  client.enterprise.getUsers({ "external_app_user_id": this.oktaRecord.sub })
      .then((result) => {
          if (result.total_count > 0) {
              // TODO: MAKE AUTHENTICATED USER CALL
          } else {
              // User not found - create user
              this.createUser();
          }
      });
  ```

  Using the Box Node SDK, we call `enterprise.getUsers` to search all enterprise
  users, and pass in the unique Okta user ID as the `external_app_user_id` value
  to search specifically for that user.

  If found (number of records is greater than 0) we can make an
  authenticated call to the Box APIs using that user record, which will be
  defined in the next section.

  If not found, we call the `createUser` function we defined in the last section
  to create a new Box user with that `external_app_user_id` association.
</Choice>

<Choice>
  Replace the `// TODO: VALIDATE USER` comment with the following:

  ```java theme={null}
  // Set up Box enterprise client
  Reader reader = new FileReader("config.json");
  BoxConfig config = BoxConfig.readFrom(reader);
  api = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(config);

  // Get Okta user sub for unique ID attachment to Box user
  Object oktaSub = user.getAttributes().get("sub");

  // Check enterprise users for matching external_app_user_id against Okta sub
  URL url = new URL("https://api.box.com/2.0/users?external_app_user_id=" + oktaSub);
  BoxAPIRequest request = new BoxAPIRequest(api, url, "GET");
  BoxJSONResponse jsonResponse = (BoxJSONResponse) request.send();
  JsonObject jsonObj = jsonResponse.getJsonObject();
  JsonValue totalCount = jsonObj.get("total_count");

  // Set return string
  String outputString = "";

  if (totalCount.asInt() > 0) {
      // TODO: MAKE AUTHENTICATED USER CALL
  } else {
      outputString = createUser(user);
  }

  return outputString;
  ```

  Using the Box Java SDK generic request method, we make a call directly to the
  `https://api.box.com/2.0/users` endpoint to search enterprise users, passing in
  the unique Okta user ID as the `external_app_user_id` value to search
  specifically for that user.

  If found (number of records is greater than 0) we can make an
  authenticated call to the Box APIs using that user record, which will be
  defined in the next section.

  If not found, we call the `createUser` function we defined in the last section
  to create a new Box user with that `external_app_user_id` association.
</Choice>

<Choice>
  Replace the `# TODO: VALIDATE USER` comment with the following:

  ```python theme={null}
  # Fetch Okta user ID
  uid = g.user.id

  # Validate is user exists
  url = f'https://api.box.com/2.0/users?external_app_user_id={uid}'
  response = self.box_client.make_request('GET', url)
  user_info = response.json()

  # If user not found, create user, otherwise fetch user token
  if (user_info['total_count'] == 0):
      self.createUser(g.user)
  else:
      # TODO: MAKE AUTHENTICATED USER CALL
  ```

  Using the Box Python SDK generic request method, we make a call directly to the
  `https://api.box.com/2.0/users` endpoint to search enterprise users, passing in
  the unique Okta user ID as the `external_app_user_id` value to search
  specifically for that user.

  If found (number of records is greater than 0) we can make an
  authenticated call to the Box APIs using that user record, which will be
  defined in the next section.

  If not found, we call the `createUser` function we defined in the last section
  to create a new Box user with that `external_app_user_id` association.
</Choice>

<Choice>
  Replace the `// TODO: VALIDATE USER` comment with the following:

  ```csharp theme={null}
  var userId = users.Entries[0].Id;
  var userToken = sdk.UserToken(userId);
  BoxClient userClient = sdk.UserClient(userToken, userId);

  // TODO: MAKE AUTHENTICATED USER CALL
  ```

  If a valid user is found, the Box ID is extracted and used to generate a Box
  SDK client that is scoped specifically for that user, rather than the
  application.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Make Authenticated Box User Calls

Once an associated Box user is found for the Okta user we're going to generate
an access token specifically
<Link href="/guides/authentication/jwt/user-access-tokens">scoped for that user</Link> to make Box
API calls, then make a call to get the current user to ensure that everything
is working and that we have a valid user access token.

<Choice>
  Replace `// TODO: MAKE AUTHENTICATED USER CALL` from the previous section with
  the following:

  ```js theme={null}
  this.userId = result.entries[0].id;
  this.userClient = sdk.getAppAuthClient('user', this.userId);

  this.userClient.users.get(this.userClient.CURRENT_USER_ID)
      .then(currentUser => {
          res.send(`Hello ${currentUser.name}`);
      });
  ```

  With a user found we capture the Box user ID, then generate a user client
  object scoped for that user. We finish by making a call to fetch the current
  user with the user client object, which should return the user profile
  information for the Okta associated Box app user.
</Choice>

<Choice>
  Replace `// TODO: MAKE AUTHENTICATED USER CALL` from the previous section with
  the following:

  ```java theme={null}
  // User found, authenticate as user
  // Fetch user ID
  JsonArray entries = (JsonArray) jsonObj.get("entries");
  JsonObject userRecord = (JsonObject) entries.get(0);
  JsonValue userId = userRecord.get("id");

  // Get user scoped access token and fetch current user with it
  BoxDeveloperEditionAPIConnection userApi = BoxDeveloperEditionAPIConnection.getAppUserConnection(userId.asString(), config);
  BoxUser currentUser = BoxUser.getCurrentUser(userApi);
  BoxUser.Info currentUserInfo = currentUser.getInfo();

  outputString = "Hello " + currentUserInfo.getName();
  ```

  With a user found we capture the Box user ID, then generate a user client
  object scoped for that user. We finish by making a call to fetch the current
  user with the user client object, which should return the user profile
  information for the Okta associated Box app user.
</Choice>

<Choice>
  Replace `# TODO: MAKE AUTHENTICATED USER CALL` from the previous section with
  the following:

  ```python theme={null}
  # Create user client based on discovered user
  user = user_info['entries'][0]
  user_to_impersonate = self.box_client.user(user_id=user['id'])
  user_client = self.box_client.as_user(user_to_impersonate)

  # Get current user
  current_user = user_client.user().get()
  return f'Hello {current_user.name}'
  ```

  With a user found we capture the Box user ID, then generate a user client
  object scoped for that user. We finish by making a call to fetch the current
  user with the user client object, which should return the user profile
  information for the Okta associated Box app user.
</Choice>

<Choice>
  Replace `// TODO: MAKE AUTHENTICATED USER CALL` from the previous section with
  the following:

  ```csharp theme={null}
  BoxUser currentUser = await userClient.UsersManager.GetCurrentUserInformationAsync();
  System.Diagnostics.Debug.WriteLine("Current user name: " + currentUser.Name);
  ```

  Using that user scoped client, the current user record is then extracted from
  Box, and a diagnostic message is written back stating the current user name.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Summary

* You've validated whether an Okta user exists as a Box user.
* You've created a new app user if they don't exist.
* You're making a Box API call for an existing Box user.

<Observe>
  <Next>I have set up Box user validation and creation</Next>
</Observe>


# Connect Okta identities to Box App Users in a web app
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/index



[Okta][okta] is a popular access management and identity platform used by
companies to provide a unified method for managing and authenticating into
multiple applications with a single set of credentials and a single secure
dashboard.

When connected to a custom Box application, the [Okta APIs][okta-dev] may be
used to provide a single login mechanism to identify users within the Box
application, allowing you to have a unified experience between your unified
identity system (Okta) and the Box APIs.

<Frame>
  <img alt="Okta Dashboard" />
</Frame>

## Overview

This quick start guide will walk you through how to programmatically use Okta to
log in to a Box application, provision an app user in Box that is linked to
the Okta user, then make Box API calls on behalf of that user.

This will take you through the following steps.

1. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/scaffold-application-code">Scaffold your application code</Link> so that we have a web application that we can log in to.
2. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta">Setup and configure your Okta application</Link> and create a first user that we can use to log into the web app with, and eventually create a Box account for.
3. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-box">Setup and configure your Box application</Link> so that we can connect your web application to Box.
4. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/logging-into-app">Create a log in flow for your application</Link>, allowing the Okta user to log in to your web application.
5. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/find-or-create-box-users">Find an existing Box user, and optionally create a Box user</Link> the first time that Okta user logs into your web application.
6. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/run-the-app">And finally, run the application</Link> and see the complete flow in action.

At the end of the tutorial we will output a single message to the browser. If
this is the first time an Okta user logs in to Box via the application, an
associated Box user will be created and the message
`New user created: {{USERNAME}}` will be output to the browser.

When attempting to log in with this user in subsequent attempts, a message
stating `Hello {{USERNAME}}` will now be output to the browser.

<Warning>
  To simplify this guide we will not create any user interface for the web
  application. Instead we will provide some output via the application console /
  terminal and directly as text output in the browser.
</Warning>

[okta]: https://www.okta.com/

[okta-dev]: https://developer.okta.com/


# Logging into the app with Okta
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/logging-into-app



<ProgressBar />

With the Okta, Box, and basic application set up, we can turn our attention to
the first step in the application code flow, the Okta login.

During the Okta login we will employ the OpenID Connect (OIDC) frameworks of
the language used to redirect the user to Okta to log in and pass Okta user
information back to the application. Those Okta user details will in turn be
used to validate and create Box users in the next step.

This section will walk you through:

* Setting up the application configuration skeleton.
* Defining the routes for the chosen framework to handle user traffic.
* Passing Okta user information to the next Box user validation step.

## Set up the Skeleton

<Choice>
  In your local application directory, load the `server.js` file created in
  step 1.

  Start by copying the following package definitions and configuration
  information into the file.

  ```js theme={null}
  const session = require('express-session');
  const { ExpressOIDC } = require('@okta/oidc-middleware');
  const bodyParser = require('body-parser');
  const boxSDK = require('box-node-sdk');
  const config = require('./config.js');
  const express = require('express')();
  const http = require('http');
  const path = require('path');
  const fs = require('fs');

  express.use(session({
      secret: 'this should be secure',
      resave: true,
      saveUninitialized: false
  }));

  const oidc = new ExpressOIDC({
      issuer: `https://${config.oktaOrgUrl}/oauth2/default`,
      client_id: config.oktaClientId,
      client_secret: config.oktaClientSecret,
      appBaseUrl: config.oktaBaseUrl,
      loginRedirectUri: `${config.oktaBaseUrl}${config.oktaRedirect}`,
      scope: 'openid profile'
  });

  express.use(oidc.router);
  express.use(bodyParser.json());
  express.use(bodyParser.urlencoded({
      extended: true
  }));
  ```

  This sets up the Express configuration and Okta OIDC connector
  information. Express is set to use the OIDC connector and the Okta
  information that we saved in step 2 of this quick start is used to configure
  the connector for our Okta integration.

  Now add the routing details.

  ```js theme={null}
  // Redirect to Okta login
  express.get('/', (req, res) => {
      // TODO: HANDLE ROUTE
  });
  ```

  This defines the entry route for our application. When a user attempts to
  visit our application root (`/`) the code within this route will be run.

  Lastly, add the Express server initialization to listen for traffic.

  ```js theme={null}
  // Create server
  const port = process.env.PORT || 3000;
  http.createServer(express).listen(port, () => {
      console.log(`Server started: Listening on port ${port}`);
  });
  ```
</Choice>

<Choice>
  In your local application directory, load the
  `/src/main/java/com/box/sample/Application.java` file created in step 1, or
  similar directory if an alternate application name was used.

  Copy the following basic application structure into the file.

  ```java theme={null}
  package com.box.okta.sample;

  import java.io.FileReader;
  import java.io.IOException;
  import java.io.Reader;
  import java.net.URL;

  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
  import org.springframework.security.core.annotation.AuthenticationPrincipal;
  import org.springframework.security.oauth2.core.oidc.user.OidcUser;
  import org.springframework.web.bind.annotation.RequestMapping;
  import org.springframework.web.bind.annotation.RestController;

  import com.box.sdk.BoxAPIRequest;
  import com.box.sdk.BoxConfig;
  import com.box.sdk.BoxDeveloperEditionAPIConnection;
  import com.box.sdk.BoxJSONResponse;
  import com.box.sdk.BoxUser;
  import com.box.sdk.CreateUserParams;
  import com.eclipsesource.json.JsonArray;
  import com.eclipsesource.json.JsonObject;
  import com.eclipsesource.json.JsonValue;

  @RestController
  @EnableAutoConfiguration
  public class Application {
      static BoxDeveloperEditionAPIConnection api;

      // TODO: SET ROUTE

      // TODO: INITIALIZE SERVER
  }
  ```

  This sets up the needed imports, the `Application` class, and a standard shared
  Box API connection attribute, to be defined in the next step.

  Replace `// TODO: SET ROUTE` with the following.

  ```java theme={null}
  @RequestMapping("/")
  String home(@AuthenticationPrincipal OidcUser user) throws IOException {
    // TODO: HANDLE ROUTE
  }
  ```

  The route mapping defines the entry route for our application. When a user
  attempts to visit our application root (`/`) in a logged out state, the OIDC
  connector will automatically push them through the Okta login, so we don't need
  to setup a redirect. When the user is in a logged in state, the code within
  this route will be run.

  Replace `// TODO: INITIALIZE SERVER` with the following to initialize the
  Spring Boot server to listen for traffic.

  ```java theme={null}
  public static void main(String[] args) {
      SpringApplication.run(Application.class, args);
  }
  ```
</Choice>

<Choice>
  In your local application directory, load the `server.py` file created in step 1.

  Copy the following basic application structure into the file.

  ```python theme={null}
  from flask import Flask, redirect, g, url_for
  from flask_oidc import OpenIDConnect
  from okta import UsersClient
  from boxsdk import Client
  from boxsdk import JWTAuth
  import requests
  import config
  import json

  app = Flask(__name__)
  app.config.update({
      'SECRET_KEY': config.okta_client_secret,
      'OIDC_CLIENT_SECRETS': './client_secrets.json',
      'OIDC_DEBUG': True,
      'OIDC_ID_TOKEN_COOKIE_SECURE': False,
      'OIDC_SCOPES': ["openid", "profile"],
      'OIDC_CALLBACK_ROUTE': config.okta_callback_route
  })

  oidc = OpenIDConnect(app)
  okta_client = UsersClient(config.okta_org_url, config.okta_auth_token)
  ```

  This sets up the Flask configuration, Okta client, and Okta OIDC
  connector information. Flask is set to use the OIDC connector and the Okta
  information that we saved in step 2 of this quick start is used to configure
  the connector for our Okta integration.

  Next, add a `before_request` definition to be run before route handling is
  engaged. We'll be using this to capture our Okta user information, if available.

  ```python theme={null}
  # Fetch Okta user record if logged in
  @app.before_request
  def before_request():
    # TODO: HANDLE BEFORE REQUEST
  ```

  Lastly, define the entry route for our application, as well as a `box_auth`
  route.

  ```python theme={null}
  # Main application route
  @app.route('/')
  def start():
    # TODO: HANDLE MAIN ROUTE

  # Box user verification
  @app.route("/box_auth")
  @oidc.require_login
  def box_auth():
    # TODO: HANDLE BOX AUTH ROUTE

  return 'Complete'
  ```

  When a user attempts to visit our application root (`/`) the code
  within this route will be run. When we validate an Okta user, the code within
  the `box_auth` route will be run.
</Choice>

<Choice>
  In your local application, load `Views` > `Shared` > `Layout.cshtml`. Once the
  ASP.NET application loads this will be the visual component that is rendered.
  At the top of the page, insert the following.

  ```csharp theme={null}
  @using System.Security.Claims;

  @if (User.Identity.IsAuthenticated)
  {
      <p class="navbar-text">Hello, @User.Identity.Name</p>
  }
  else
  {
      <a asp-controller="Account" asp-action="SignIn">Sign In</a>
  }
  ```

  If a user who is logged in to Okta visits, they will see the hello message. If
  the user is not logged in a sign in link will be provided to them.

  Within the line `<a asp-controller="Account" asp-action="SignIn">Sign In</a>`,
  `asp-controller="Account"` means that the to be created Account controller will
  handle the request, and `asp-action="SignIn"` states that the `SignIn` method
  in that controller will be enacted. Save and close that file.

  Within the `Controllers` directory create a new file, `AccountController.cs`.
  This will be the controller that is enacted when that sign in link is clicked.

  Copy the following basic application structure into the file.

  ```csharp theme={null}
  using System.IO;
  using System.Linq;
  using System.Threading.Tasks;
  using Microsoft.AspNetCore.Mvc;
  using Microsoft.AspNetCore.Authorization;
  using Okta.AspNetCore;
  using Box.V2;
  using Box.V2.Config;
  using Box.V2.JWTAuth;
  using Box.V2.Models;

  public class AccountController : Controller
  {
      public IActionResult SignIn()
      {
          if (!HttpContext.User.Identity.IsAuthenticated)
          {
              return Challenge(OktaDefaults.MvcAuthenticationScheme);
          }

          return RedirectToAction("Profile", "Account");
      }

      [Authorize]
      [Route("~/profile")]
      public IActionResult Profile()
      {
          // TODO: HANDLE ROUTE
      }
  }
  ```

  When the user clicks on the sign in link the `SignIn` method in this controller
  will be run. If the user is not already authenticated they will be sent to
  `Challenge`, which will redirect the user to Okta to log in. This functionality
  is handled by the routing framework and does not require any additional code to
  enact. If the user is authenticated, they will be redirected to the `Profile`
  routing method.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Setup Application Route

We now need to define the code that will run when our main route (`/`) is
engaged.

<Choice>
  Replace `// TODO: HANDLE ROUTE` in the main route with the following code.

  ```js theme={null}
  if (req.userContext && req.userContext.userinfo) {
      const tokenSet = req.userContext.tokens;
      const userInfo = req.userContext.userinfo;

      // If Okta ID is present, pass to Box user validation
      if (userInfo.sub) {
          box.validateUser(userInfo, res);
      } else {
          console.log('No Okta ID identified');
      }
  } else {
      res.redirect('/login');
  }
  ```

  What we are doing in the above is first checking to see if there is any Okta
  user information available from the OIDC connector. When a user logs in the
  connector will make the Okta user and configuration information available to
  our route within `req.userContext`.

  If user information is present, meaning the user is logged in to Okta, we pass
  the user information to `box.validateUser` along with the Express response
  object to see if there is an associated Box user available, which we'll define
  in the next step.

  If no user information is present, we redirect the user to `/login`. The OIDC
  connector will automatically handle this route and force the user through to
  the Okta login.
</Choice>

<Choice>
  Replace `// TODO: HANDLE MAIN ROUTE` in the main route with the following code.

  ```java theme={null}
  // Validate OIDC user against Box
  return validateUser(user);
  ```

  The Java OIDC connector handles most of the heavy lifting for us. When a logged
  out user accesses this route they will automatically be pushed to the Okta
  login. Once logged in, an OIDC user object will be made available to the route.
  We pass that user object to a `validateUser` function, which we'll define in
  the next step.
</Choice>

<Choice>
  Replace `// TODO: HANDLE BEFORE REQUEST` in the main route with the following code.

  ```python theme={null}
  if oidc.user_loggedin:
      g.user = okta_client.get_user(oidc.user_getfield('sub'))
  else:
      g.user = None
  ```

  This will check if an OIDC user is available, meaning that the user has already
  logged in to Okta. If available we set a user object using the Okta client
  object, and if not we set the user object to `None`.

  Next, replace `// TODO: HANDLE ROUTE` in the main route with the following code.

  ```python theme={null}
      return redirect(url_for(".box_auth"))
  ```

  When this code is engaged, if the user is not logged in to Okta they will be
  redirected to Okta to log in by the OIDC connector. After login, or if the user
  is already logged in, they will then be forwarded to the `box_auth` route code.

  Finally, replace `// TODO: HANDLE BOX AUTH ROUTE` in the `box_auth` route with
  the following code.

  ```python theme={null}
      box = Box()
      return box.validateUser(g)
  ```

  This creates a new instance of the Box class and calls the `validateUser`
  method, passing in the Okta user object. We'll define this class and methods in
  the next step.
</Choice>

<Choice>
  Replace `// TODO: HANDLE ROUTE` in the main route with the following code.

  ```csharp theme={null}
  var subClaim = HttpContext.User.Claims.First(c => c.Type == "sub");
  var sub = subClaim.Value;

  var nameClaim = HttpContext.User.Claims.First(c => c.Type == "name");
  var name = nameClaim.Value;

  Task userSearch = validateUser(name, sub);

  Task.WaitAll(userSearch);

  return Content(name);
  ```

  This block will capture the Okta user account sub (unique ID) and name, then
  sends that data to the to be created `validateUser` method to find a matching
  Box user, which will be created in the next step.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Summary

* You set up the skeleton routes and configuration for Okta.
* You set up the main route handler to pass to Box user verification.

<Observe>
  <Next>I have set up the Okta login</Next>
</Observe>


# Run the application
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/run-the-app



<ProgressBar />

With all the components of the sample in place, it's time to run our program to
see if everything is working correctly.

<Choice>
  From the terminal / command prompt in the local application directory, type
  `node server.js` and click enter. The server will start up and output
  `Server started: Listening on port 3000`.

  From your browser, go to `http://localhost:3000/`. Since this is the first time
  we'll be testing out the user sign in flow, you'll see the Okta login.

  <Frame>
    <img alt="Okta Login" />
  </Frame>

  Sign in with the credentials for the Okta user you created in the last section
  of <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta">step 2</Link>.

  <br />

  Once signed in, you will see a message stating
  `New user created: {{USERNAME}}` output to the browser.

  <br />

  When attempting to log in with this user in subsequent attempts, you
  will now see `Hello {{USERNAME}}` output to the browser.
</Choice>

<Choice>
  From Eclipse (or your preferred editor) click to run the application. You will
  see console output stating that the Spring boot application is now running on
  port 8080.

  From your browser, go to `http://localhost:8080/`. Since this is the first time
  we'll be testing out the user sign in flow, you'll see the Okta login.

  <Frame>
    <img alt="Okta Login" />
  </Frame>

  Sign in with the credentials for the Okta user you created in the last section
  of <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta">step 2</Link>.

  <br />

  Once signed in, you will see a message stating `New User Created: {{USERNAME}}`
  output to the browser.

  <br />

  When attempting to log in with this user in subsequent attempts, you
  will now see `Hello {{USERNAME}}` output to the browser.
</Choice>

<Choice>
  From the terminal / command prompt in the local application directory, type
  `env FLASK_APP=server.py flask run` and click enter. The server will start up
  and output `Running on http://127.0.0.1:5000/`.

  From your browser, go to `http://127.0.0.1:5000/`. Since this is the first time
  we'll be testing out the user sign in flow, you'll see the Okta login.

  <Frame>
    <img alt="Okta Login" />
  </Frame>

  Sign in with the credentials for the Okta user you created in the last section
  of <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta">step 2</Link>.

  <br />

  Once signed in, you will see a message stating
  `New user created: {{USERNAME}}` output to the browser.

  <br />

  When attempting to log in with this user in subsequent attempts, you
  will now see `Hello {{USERNAME}}` output to the browser.
</Choice>

<Choice>
  From Visual Studio Code (or your preferred editor) click `Run` ->
  `Start Debugging` from the menu. You will see debug console output as the
  application loads, then a browser window will be loaded with the application at
  `https://localhost:5001/`.

  Since this is the first time testing the application, the sign in link will be
  displayed. Once clicked, the Okta login will be automatically loaded.

  <Frame>
    <img alt="Okta Login" />
  </Frame>

  Sign in with the credentials for the Okta user you created in the last section
  of <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta">step 2</Link>.

  <br />

  Once signed in, you will see a message in the debug console stating
  `New user created: {{USERNAME}}` output to the browser.

  <br />

  When attempting to log in with this user in subsequent attempts, you
  will now see `Current user name: {{USERNAME}}` output to the browser.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Summary

You've reached the end of this Quick Start guide. By now you should have taken
the following steps.

1. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/scaffold-application-code">Created a web application scaffold</Link>.
2. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-okta">Setup and configured an Okta application</Link> and created a first user that could be used to log into the web app.
3. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/configure-box">Setup and configured a Box application</Link> so that the web app can connect to Box.
4. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/logging-into-app">Created a log in flow for the web application</Link>, allowing the Okta user to log in.
5. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/find-or-create-box-users">Added a check to find an existing Box user</Link>, and optionally create a Box user the first time that Okta user logs into the web application.
6. <Link href="/guides/sso-identities-and-app-users/connect-okta-to-app-users/run-the-app">And finally, ran the application</Link> and saw the complete flow in action.

## Next Steps

We recommend the following resources for anyone who wants to learn more about
more advanced capabilities that may be attached into the user creation and
access process.

* <Link href="/guides/users/provision">User provisioning</Link> best practices for advanced user folder architecture setup.
* <Link href="/guides/users/deprovision">User deprovisioning</Link> best practices cleaning up inactive users and transferring user content to another account.
* <Link href="/guides/uploads">Uploading content</Link> into Box, including running preflight checks and large file (chunked) uploading.


# Scaffold application code (Okta integration)
Source: https://developer.box.com/guides/sso-identities-and-app-users/connect-okta-to-app-users/scaffold-application-code



<ProgressBar />

Our first step in this guide is to create a local application to house our code
and configuration data as we start to create the Okta and Box applications that
will be needed.

Depending on your language / framework preference, create a blank application,
install the required dependencies, as well as all configuration and program
files.

Choose your preferred language / framework below to get started.

<Grid>
  <Choose>
    # Node

    Using the Express.js framework.
  </Choose>

  <Choose>
    # Java

    Using the Spring Boot framework.
  </Choose>
</Grid>

<Grid>
  <Choose>
    # Python

    Using the Flask framework.
  </Choose>

  <Choose>
    # .NET

    Using the ASP.NET Core framework.
  </Choose>
</Grid>

<Choice>
  * Create a local directory for your application.
  * Create a `package.json` file inside the local directory, open it in your preferred editor, copy / paste the following into it, and save / exit the file.

  ```json theme={null}
  {
    "name": "okta-box",
    "version": "1.0.0",
    "description": "Box / Okta sample integration",
    "main": "server.js",
    "scripts": {
      "test": "echo \"Error: no test specified\" && exit 1",
      "start": "node server.js"
    },
    "author": "Box",
    "license": "ISC",
    "dependencies": {
      "@okta/oidc-middleware": "^4.0.0",
      "@okta/okta-sdk-nodejs": "^3.2.0",
      "box-node-sdk": "^1.31.0",
      "express-session": "^1.17.0"
    }
  }
  ```

  * Run `npm init` from the terminal / console to install dependencies.
  * Create two files, `server.js` and `config.js` in the local directory.
  * Open `config.js` and save the following default configuration.

  ```js theme={null}
  const oktaClientId = exports.oktaClientId = '';
  const oktaClientSecret = exports.oktaClientSecret = '';
  const oktaOrgUrl = exports.oktaOrgUrl = '';
  const oktaBaseUrl = exports.oktaBaseUrl = 'http://localhost:3000';
  const oktaRedirect = exports.oktaRedirect = '/authorization-code/callback';
  ```
</Choice>

<Choice>
  * From Eclipse, create a new project. When prompted, select a Gradle project.
  * Enter a unique name for the project, we used `okta.sample` for this guide.
  * Open your `build.gradle` file and add the following dependencies. Once saved, refresh the Gradle project.

  ```java theme={null}
  dependencies {
      implementation 'org.springframework.boot:spring-boot-starter-security'
      implementation 'org.springframework.boot:spring-boot-starter-web'
      implementation 'com.okta.spring:okta-spring-boot-starter:1.4.0'
      testImplementation('org.springframework.boot:spring-boot-starter-test') {
        exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
      }
      testImplementation 'org.springframework.security:spring-security-test'
      compile 'com.box:box-java-sdk:2.44.1'
  }
  ```

  * Open your `/src/main/resources/application.properties` file and save the following defaults.

  ```java theme={null}
  okta.oauth2.redirect-uri=/authorization-code/callback
  okta.oauth2.issuer=
  okta.oauth2.clientId=
  okta.oauth2.clientSecret=

  security.oauth2.sso.loginPath=/authorization-code/callback
  ```
</Choice>

<Choice>
  * Create a local directory for your application.
  * Install needed dependencies using the following `pip` command from your terminal / command prompt: `pip install flask flask_oidc okta boxsdk config`
  * Create three files in the local directory, `client_secrets.json`, `config.py`, and `server.py`.
  * Open `config.py` and save the following into it. This will be some of Okta app configuration information needed. We'll fill in the remaining information in the next step.

  ```python theme={null}
  okta_client_secret = 'YOUR OKTA CLIENT SECRET'
  okta_org_url = 'YOUR OKTA ORG URL'
  okta_auth_token = 'YOUR OKTA APP TOKEN'
  okta_callback_route = '/oidc/callback'
  ```

  * Open `client_secrets.json` and save the following into it. This will be a standard object that the Flask OpenID Connect integration will use during configuration. We'll fill in the remaining information in the next step.

  ```json theme={null}
  {
    "web": {
      "client_id": "OKTA CLIENT ID",
      "client_secret": "OKTA CLIENT SECRET",
      "auth_uri": "OKTA AUTHORIZE URI",
      "token_uri": "OKTA TOKEN URI",
      "issuer": "OKTA APP DEFAULT",
      "userinfo_uri": "OKTA APP USER INFO URI",
      "redirect_uris": [
        "http://127.0.0.1:5000/oidc/callbac"
      ]
    }
  }
  ```
</Choice>

<Choice>
  * Create a local directory for your application.
  * Open a command prompt / terminal window and go to the local application directory. Using the [.NET Core CLI][dotnet-cli] type `dotnet new mvc` and hit enter. This will create the main scaffolding for an ASP.NET Core MVC (Model-View-Controller) web app. Alternately, create the application [directly from Visual Studio][vs-app-create].
  * From the command prompt / terminal window in the local application directory, add the Okta ASP.NET Core dependencies by typing `dotnet add package Okta.AspNetCore` and the Box dependencies by typing `dotnet add package Box.V2.Core`.
  * Load your new application into Visual Studio or your preferred editor.
  * Within the root of the project, open `Startup.cs`.
  * Add the following package declarations to the top of the file.

  ```csharp theme={null}
  using Microsoft.AspNetCore.Authentication.Cookies;
  using Okta.AspNetCore;
  ```

  * Replace the content of the `ConfigureServices` method with the following. We will fill in the specific Okta application values in the next step.

  ```csharp theme={null}
  services.AddControllersWithViews();
  services.AddAuthentication(options =>
  {
      options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
      options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
      options.DefaultChallengeScheme = OktaDefaults.MvcAuthenticationScheme;
  })
  .AddCookie()
  .AddOktaMvc(new OktaMvcOptions
  {
      // Replace these values with your Okta configuration
      OktaDomain = "",
      ClientId = "",
      ClientSecret = ""
  });
  ```

  Add the following line to the **top** of the `Configure` method.

  ```csharp theme={null}
  app.UseAuthentication();
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework to get started.
  </Danger>
</Choice>

## Summary

* You created a new local application, files, and basic configuration details.
* You installed all project dependencies.

<Observe>
  <Next>I have my local application set up</Next>
</Observe>

[dotnet-cli]: https://docs.microsoft.com/en-us/dotnet/core/tools/

[vs-app-create]: https://docs.microsoft.com/en-us/visualstudio/ide/quickstart-aspnet-core


# Create connection between SSO identity and app user
Source: https://developer.box.com/guides/sso-identities-and-app-users/create-app-user



When a user signs in to a custom Box application for the first time using their
SSO provider credentials a new Box user will need to be created and associated
with their SSO user record using some piece of unique information from that SSO
user record. Typically the data that is used to make the association between
those two accounts is either a unique ID or an email address.

To make that association, a Box account may be created in a few ways:

* Using the `external_app_user_id` field of a Box user to store the unique ID from the SSO provider.
* Using the `login` field of a Box user to store the unique email from the SSO provider (managed users only).

## Create association with `external_app_user_id`

Using the `external_app_user_id` field of a Box user record is a viable option
for both app users and managed users, and is the recommended method when
associating a user record from an SSO provider with a Box user account.

### App user

To create a new Box app user with an `external_app_user_id` association to an
SSO user record you will need two pieces of information from the SSO provider:

* UID (required): The unique identifier from the SSO user record.
* Name (optional): To maintain uniformity between the records, the SSO user name may be extracted to associate with the Box user record.

Once available, make a request to create a new app user, supplying the optional
`external_app_user_id` definition in the user parameters.

<CodeGroup>
  ```js Node theme={null}
  const ssoName = 'SSO User Name';
  const ssoUID = 'SSO User Unique ID';
  const spaceAmount = 1073741824;

  // Create app user
  client.enterprise.addAppUser(
      ssoName,
      {
        space_amount: spaceAmount,
        external_app_user_id: ssoUID
      }
  ).then(appUser => {
      console.log(`New user created: ${appUser.name}`);
  });
  ```

  ```java Java theme={null}
  String ssoName = "SSO User Name";
  String ssoUID = "SSO User Unique ID";

  // Create app user
  CreateUserParams params = new CreateUserParams();
  params.setExternalAppUserId(ssoUID);
  BoxUser.Info createdUserInfo = BoxUser.createAppUser(client, ssoName, params);

  outputString = "New user created: " + createdUserInfo.getName();
  ```

  ```python Python theme={null}
  sso_name = 'SSO User Name'
  sso_uid = 'SSO User Unique ID'
  space = 1073741824

  # Create app user
  user = box_client.create_user(sso_name, None, space_amount=space, external_app_user_id=sso_uid)
  print('New user created: {name}')
  ```
</CodeGroup>

### Managed user

To create a new Box managed user with an `external_app_user_id` association to
an SSO user record you will need two pieces of information from the SSO
provider:

* Email (required): The unique email from the SSO user record.
* Name (optional): To maintain uniformity between the records, the SSO user name may be extracted to associate with the Box user record.

Once available, make a request to create a new managed user, supplying the
SSO user record email address for the login.

<CodeGroup>
  ```js Node theme={null}
  const ssoName = 'SSO User Name';
  const ssoEmail = 'ssouser@email.com';
  const spaceAmount = 1073741824;

  // Create app user
  client.enterprise.addUser(
      ssoEmail,
      ssoName,
      {
          space_amount: spaceAmount
      }
  ).then(managedUser => {
      console.log(`New user created: ${managedUser.name}`);
  });
  ```

  ```java Java theme={null}
  String ssoName = "SSO User Name";
  String ssoEmail = "ssouser@email.com";

  // Create managed user
  BoxUser.Info createdUserInfo =
    BoxUser.createEnterpriseUser(client, ssoEmail, ssoName);

  outputString = "New user created: " + createdUserInfo.getName();
  ```

  ```python Python theme={null}
  sso_name = 'SSO User Name'
  sso_email = 'ssouser@email.com'
  space = 1073741824

  # Create managed user
  user = box_client.create_user(sso_name, sso_email, space_amount=space)
  print('New user created: {name}')
  ```
</CodeGroup>

## Create association by email

Creating a new <Link href="/guides/getting-started/users#managed-users">managed user</Link>
that is associated by the SSO user email address is the same process as
creating a standard managed user.

After the user logs in via your SSO provider, if the user doesn't already exist
as a Box user, extract the email address from the SSO user record and make a
request to create a new Box managed user.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/users" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "login": "ceo@example.com",
         "name": "Aaron Levie"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.users.createUser({
    name: userName,
    login: userLogin,
    isPlatformAccessOnly: true,
  } satisfies CreateUserRequestBody);
  ```

  ```python Python v10 theme={null}
  client.users.create_user(user_name, login=user_login, is_platform_access_only=True)
  ```

  ```csharp .NET v10 theme={null}
  await client.Users.CreateUserAsync(requestBody: new CreateUserRequestBody(name: userName) { Login = userLogin, IsPlatformAccessOnly = true });
  ```

  ```swift Swift v10 theme={null}
  try await client.users.createUser(requestBody: CreateUserRequestBody(name: userName, login: userLogin, isPlatformAccessOnly: true))
  ```

  ```java Java v10 theme={null}
  client.getUsers().createUser(new CreateUserRequestBody.Builder(userName).login(userLogin).isPlatformAccessOnly(true).build())
  ```

  ```java Java v5 theme={null}
  BoxUser.Info createdUserInfo = BoxUser.createEnterpriseUser(api, "user@example.com", "A User");
  ```

  ```py Python v4 theme={null}
  new_user = client.create_user('Temp User', 'user@example.com')
  ```

  ```csharp .NET v6 theme={null}
  var userParams = new BoxUserRequest()
  {
      Name = "Example User",
      Login = "user@example.com"
  };
  BoxUser newUser = await client.UsersManager.CreateEnterpriseUserAsync(userParams);
  ```

  ```js Node v4 theme={null}
  client.enterprise.addUser(
   'eddard@winterfell.example.com',
   'Ned Stark',
   {
    role: client.enterprise.userRoles.COADMIN,
    address: '555 Box Lane',
    status: client.enterprise.userStatuses.CANNOT_DELETE_OR_EDIT
   })
   .then(user => {
    /* user -> {
     type: 'user',
     id: '44444',
     name: 'Ned Stark',
     login: 'eddard@winterfell.example.com',
     created_at: '2012-11-15T16:34:28-08:00',
     modified_at: '2012-11-15T16:34:29-08:00',
     role: 'coadmin',
     language: 'en',
     timezone: 'America/Los_Angeles',
     space_amount: 5368709120,
     space_used: 0,
     max_upload_size: 2147483648,
     status: 'active',
     job_title: '',
     phone: '',
     address: '555 Box Lane',
     avatar_url: 'https://www.box.com/api/avatar/large/deprecated' }
          */
   });
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Find app user for SSO identity
Source: https://developer.box.com/guides/sso-identities-and-app-users/find-app-user



When a user logs into a platform application with their SSO provider, the
first step that should be taken is to see if that user already exists from a
previous login attempt where a Box user record was already created.

If a Box user is found you should
<Link href="/guides/authentication/jwt/user-access-tokens">create a user access token</Link>,
or make <Link href="/guides/authentication/jwt/as-user">as user calls</Link>, to access Box
APIs as that user.

If a Box user is not found you should create a new user with an association to
the SSO user record.

To search for existing users the <Link href="/reference/get-users">List Enterprise Users</Link>
endpoint may be used. Depending on whether you're using the
`external_app_user_id` or `login` method your query will look slightly
different.

Choose the search method that matches how you originally associated the SSO
identity to the Box user in
<Link href="/guides/sso-identities-and-app-users/create-app-user">Create connection between SSO identity and app user</Link>:

* Use `external_app_user_id` if you stored the SSO provider's unique ID on the Box user. This works for both app users and managed users.
* Use the `login` email if you created a managed user whose login is the SSO email address.

## Find user by external app user ID

To search for enterprise users by the stored `external_app_user_id` value you
will need one piece of information from the SSO provider:

* UID (required): The unique identifier from the SSO user record.

Once available, make a request to the list enterprise users endpoint, supplying
the `external_app_user_id` definition in the parameters.

<Warning>
  You can retrieve app users for a specific application only if
  such app users were created by this application.
  If you use one application to search for users
  created by a different one, no data will be returned.
</Warning>

<CodeGroup>
  ```js Node theme={null}
  const ssoUID = 'SSO User Unique ID';

  // Check enterprise users for matching external_app_user_id against SSO UID
  client.enterprise.getUsers({ "external_app_user_id": ssoUID })
  .then((users) => {
      if (users.total_count > 0) {
          // User found, fetch user ID
          const userId = users.entries[0].id;
      } else {
          // User not found - create new user record
      }
  });
  ```

  ```java Java theme={null}
  String ssoUID = "SSO User Unique ID";

  // Check enterprise users for matching external_app_user_id against SSO UID
  URL url = new URL("https://api.box.com/2.0/users?external_app_user_id=" + ssoUID);
  BoxAPIRequest request = new BoxAPIRequest(client, url, "GET");
  BoxJSONResponse jsonResponse = (BoxJSONResponse) request.send();
  JsonObject jsonObj = jsonResponse.getJsonObject();
  JsonValue totalCount = jsonObj.get("total_count");

  if (totalCount.asInt() > 0) {
      // User found, fetch
      // Fetch user ID
      JsonArray entries = (JsonArray) jsonObj.get("entries");
      JsonObject userRecord = (JsonObject) entries.get(0);
      JsonValue userId = userRecord.get("id");
  } else {
      // User not found - create new user record
  }
  ```

  ```python Python theme={null}
  sso_uid = 'SSO User Unique ID'

  # Validate is user exists
  url = f'https://api.box.com/2.0/users?external_app_user_id={sso_uid}'
  headers = {'Authorization': 'Bearer ' + access_token}
  response = requests.get(url, headers=headers)
  user_info = response.json()

  if (user_info['total_count'] == 0):
      # User not found - create new user record
  else:
      # User found, fetch user ID
      user = user_info['entries'][0]
      user_id = user['id']
  ```
</CodeGroup>

## Find user by email address

To search for enterprise users by their `login` email you
will need one piece of information from the SSO provider:

* Email (required): The unique email from the SSO user record.

Once available, make a request to the list enterprise users endpoint, supplying
the email address as the `filter_term`, which is made available to search by
email or name.

<CodeGroup>
  ```js Node theme={null}
  const ssoEmail = 'ssouser@email.com';

  client.enterprise.getUsers({filter_term: ssoEmail})
      .then(users => {
          if (users.total_count > 0) {
              // User found, fetch user ID
              const userId = users.entries[0].id;
          } else {
              // User not found - create new user record
          }
      });
  ```

  ```java Java theme={null}
  String ssoEmail = "ssouser@email.com";

  Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(client, ssoEmail);
  ```

  ```python Python theme={null}
  sso_email = 'ssouser@email.com'

  users = client.users(user_type='all', filter_term=ssoEmail)
  if (users['total_count'] == 0):
      # User not found - create new user record
  else:
      # User found, fetch user ID
      user = users['entries'][0]
      user_id = user['id']
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# SSO & App users
Source: https://developer.box.com/guides/sso-identities-and-app-users/index

How to use your own SSO service as the identity source for an app and link those identities to Box App Users.

Single Sign-On (SSO) services are often used as part of a company's **Identity
and Access Management (IAM)** solution. When deployed, these services grant
users the ability to securely authenticate multiple applications by logging in
once, with only one set of credentials (username and password).

Box is one of the applications that can be connected to the SSO service of a
company. Integrating these applications into your platform apps will allow you to
provision Box users on the fly for any of your end users, without those users
knowing they have a Box account.

This guide covers using your own SSO service as the identity source for your
application. To learn how a Box Enterprise's own SSO configuration affects
sign-ins to your app, see <Link href="/guides/authentication/sso">Enterprise SSO</Link>.

<Note>
  Popular SSO services include `Okta`, `Auth0`, `Microsoft Azure AD`,
  `OneLogin`, `G Suite`, and `Ping Identity`, but there are many others that may
  be deployed.
</Note>

## Connecting SSO to apps

When integrating SSO services into a Box application programmatically, we are
referring to the following flow.

1. A user accesses your web or mobile application in a logged out state.
2. The user is redirected to your SSO provider to log in, typically via `OAuth 2` and `OpenID Connect`.
3. After login, the user is redirected back to your application along with their SSO identity credentials.
4. Your application does a check to see if an associated Box account already exists for this user.
5. If an existing Box account already exists for this user, the application uses the SSO identity to make API calls on behalf of that user in Box.
6. If there is not already an associated Box account for this user, a new Box user account is created based on the SSO identity. The unique user ID from the SSO service is then linked to the new Box user, creating an association between the two accounts. This new Box user is then used to make API calls on behalf of that user in Box.

<Note>
  **Box web app and SSO**

  If you wish to connect your SSO service to the Box website instead of a Box
  application, Box provides a number of [integration options][sso-support] for
  supporting SSO integrations of the [Box web application](https://www.box.com)
  via SAML 2.0.
</Note>

[sso-support]: https://support.box.com/hc/en-us/articles/360043696514-Setting-Up-Single-Sign-On-SSO-for-your-Enterprise

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# App Diagnostics Report
Source: https://developer.box.com/guides/troubleshooting/app-diagnostics-report



The App Diagnostics Report provides a spreadsheet detailing each API call made
by a given application during a specified timeframe. The report gives you
access to the `API Request ID`, which can be given to Box Support for
troubleshooting purposes.

<Warning>
  This report will not include:

  * API calls made within the last 48 hours
  * Authorization and Token API calls

  We are working on including the above and thereby making the report suitable
  for real-time troubleshooting in the future.
</Warning>

## 1. Click on the **App Diagnostics** Tab

To run the App Diagnostics Report, click the **App Diagnostics** option located
along the top of your application's configuration section in
the [Developer Console][console].

<Frame>
  <img alt="New Menu Option" />
</Frame>

## 2. Click **Run App Diagnostics Report** to configure your report

Clicking **Run App Diagnostics Report** will display a popup to select report
filters and parameters.

<Frame>
  <img alt="App Diagnostic Menu" />
</Frame>

## 3. Select Report Parameters and Click **Run**

You can select a date in the last two weeks, starting 48 hours prior to today.
A report can be run for up to a total of 24 hours. Click **Run** to
generate a report.

<Frame>
  <img alt="Report Options" />
</Frame>

## 4. Access the Box Reports Folder

Navigate to [All Files][allfiles] and locate the Box Reports folder. If this is
your first time running a report, this folder is automatically generated. If
you are an Admin, this is the same folder you access
[Admin Console Reports][reports]. Open the folder.

<Frame>
  <img alt="Box Report Folder" />
</Frame>

## 5. Find and Open the latest Platform App Diagnostics Report Folder

You will see any reports you have run in the Box Reports folder.
Locate and open the most recent Platform App Diagnostics run folder.

<Frame>
  <img alt="Box Report Folder Contents" />
</Frame>

## 6. Check the Status

The report will take time to complete. You can see the status in the box at the
top of the folder.

<Frame>
  <img alt="Status Screen" />
</Frame>

## 7. Report Completed

Upon completion, the status will change, and the `.csv` file will appear in the
folder.

<Frame>
  <img alt="Diagnostics Report" />
</Frame>

## 8. Open the Report

You can open the file in your web browser or download it to view locally. If
you need help from [Box Support][support], you can send in the report with your
ticket by attaching a downloaded copy or via shared link.

<Frame>
  <img alt="Report Details" />
</Frame>

The report has nine columns.

| Column | Description |
| - | - |
| App Name | The name of the application |
| Client ID | The Client ID of the application |
| HTTP Status Code | The response code returned from Box |
| API Request Duration (ms) | The amount of time from API call to response |
| API Request ID | A unique identifier that can be used by Box Support |
| Resource | The primary resource accessed in the API call |
| Sub Resource | The secondary resource accessed in the API call |
| HTTP Method | The type of HTTP method used in the API call |
| API Request Timestamp | The timestamp of the API call |

[support]: https://support.box.com/hc/en-us/requests/new

[console]: https://app.box.com/developers/console

[allfiles]: https://app.box.com/folder/0

[reports]: https://docs.box.com/en/box-admin-tools/reporting-and-insights/running-reports


# Debugging your Box app
Source: https://developer.box.com/guides/troubleshooting/debugging-your-box-app

A step-by-step playbook for diagnosing failed API calls, handling retries and timeouts, and using the App Diagnostics tool to troubleshoot your Box application.

When your Box application returns an unexpected error, fails intermittently, or stops processing requests, you need a structured workflow for finding the root cause. This guide walks you through one: how to read a Box error response, when and how to retry, how to set sensible timeouts, and which Box-provided tools to use at each step.

<SignupCTA>
  A free Box developer account gives you access to the Developer Console where you can reproduce issues with your own application and run the App Diagnostics Report.
</SignupCTA>

## Take a systematic approach

Most Box API failures come from one of a small number of causes: an invalid token, a missing scope, an item the app cannot access, a malformed request, or a transient server-side issue. Before you change code, break the failing flow into smaller, independently testable parts:

1. **Authentication.** Can your app obtain an access token? Is the token the right type for your auth method (OAuth 2.0, JWT, or Client Credentials Grant)?
2. **Authorization.** Does the token have the scopes the endpoint requires? Does the [service account](/guides/getting-started/users#service-account) or user have access to the target item?
3. **Request construction.** Is the URL, HTTP method, header set, and body exactly what the API reference specifies?
4. **Server response.** What HTTP status code and Box error code came back? Was the request retried correctly if it was transient?
5. **Downstream side effects.** If you call other systems from a webhook or worker, did they succeed?

Test each step in isolation with a tool such as `curl` or Postman before you dig into application code.

## Inspect the API response

Box returns a structured error object for most `4xx` and `5xx` responses. Always log the full response body and the response headers — they are the single most useful piece of evidence you can collect.

```json theme={null}
{
  "type": "error",
  "status": 403,
  "code": "access_denied_insufficient_permissions",
  "help_url": "/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "Access denied - insufficient permission",
  "request_id": "abcdef123456"
}
```

Use the fields as follows:

| Field | What to do with it |
| - | - |
| `status` | The HTTP status code. Tells you the broad category (auth, permission, not found, rate limit, server error). |
| `code` | The Box-specific error code. Map this to a fix using the <Link href="/guides/api-calls/permissions-and-errors/common-errors">Errors reference</Link>. |
| `message` | A human-readable description. Often contains the specific field or value that failed validation. |
| `help_url` | A direct link to documentation for the error. |
| `request_id` | A unique identifier for the failed request. Include this in any support ticket. |

<Note>
  Most Box API responses also include a `box-request-id` response header. This is a different value from the `request_id` field in the error body. Capture both when you can.
</Note>

For the full catalog of Box error codes by HTTP status, see <Link href="/guides/api-calls/permissions-and-errors/common-errors">Errors</Link>.

## Handle retries and timeouts

Not every failure is permanent. The right response to a transient error is to retry; the right response to a permanent error is to stop and surface it to the caller. Retrying a permanent error wastes quota and can amplify outages.

### Which responses to retry

| Status code | Retry? | Notes |
| - | - | - |
| `408 Request Timeout` | Yes | The request did not reach the server in time. Retry with the same payload. |
| `429 Too Many Requests` | Yes | You have been rate limited. Honor the `retry-after` header. See <Link href="/guides/api-calls/permissions-and-errors/rate-limits">Rate limits</Link>. |
| `500 Internal Server Error` | Yes | Transient. Use exponential back-off. |
| `502 Bad Gateway` | Yes | Transient. Use exponential back-off. |
| `503 Service Unavailable` | Yes | Honor the `retry-after` header when present. Check the [Box status page](https://status.box.com/) if it persists. |
| `4xx` (other) | No | These indicate a problem with the request itself. Fix the request before resending. |

### Use exponential back-off with jitter

When you retry, increase the wait between attempts so you do not pile retries on top of a service that is already struggling. A simple pattern: wait `base * 2^attempt` seconds, capped at a maximum, plus a small random delay (jitter) to avoid thundering-herd retries from parallel workers.

```python theme={null}
import random, time

def backoff_seconds(attempt: int, base: float = 1.0, cap: float = 60.0) -> float:
    delay = min(cap, base * (2 ** attempt))
    return delay + random.uniform(0, delay * 0.1)
```

When the response includes a `retry-after` header, wait at least that many seconds before retrying instead of using your own back-off value.

```yaml theme={null}
retry-after: 100
```

### Set sensible request timeouts

Long-lived requests tie up workers and hide failures. Set an explicit timeout on every HTTP call your app makes to Box, and let the timeout fire a retry rather than waiting indefinitely. Choose values that match the endpoint: small JSON reads can use short timeouts, while uploads and AI extract calls need longer windows. If you use a [Box SDK](/guides/tooling/sdks), automatic retries and exponential back-off are already built in.

### Make retries safe

Retrying a `GET` is always safe. Retrying a `POST`, `PUT`, or `DELETE` can create duplicates if the original request actually succeeded but the response was lost. To make those retries safe:

* For chunked uploads, reuse the existing upload session and re-upload only the affected part. See <Link href="/guides/uploads/chunked">Chunked uploads</Link>.
* Treat a `409 item_name_in_use` on a retried create as "the original request already succeeded" rather than a real conflict, when that matches your flow. For example, if you retry `POST /files/content` and receive `item_name_in_use`, list the parent folder and look up the file you just tried to upload — in most cases the first attempt persisted before the response was lost.
* Before retrying a non-`GET` request, check whether the resource already exists. For example, before re-uploading a file, call `GET /folders/:id/items` on the destination folder and compare file names and sizes; before re-creating a collaboration, call `GET /folders/:id/collaborations`.

## Use the App Diagnostics tool

When you cannot reproduce a problem locally, or you need to see exactly what Box recorded for a request, run an <Link href="/guides/troubleshooting/app-diagnostics-report">App Diagnostics Report</Link> from the Developer Console.

The report exports a `.csv` of every API call your application made in a chosen 24-hour window. For each call it includes:

* The HTTP status code Box returned.
* The API request duration.
* The `API Request ID` — give this to Box Support and they can look up the exact request.
* The resource, sub-resource, HTTP method, and timestamp.

Use the App Diagnostics Report when you need to:

* Confirm whether a request ever reached Box.
* Find the request ID for a failed call that your own logs missed.
* Compare call volume against your expected pattern (for example, to see whether retries are running away).
* Provide Box Support with the precise call they need to investigate.

<Warning>
  The App Diagnostics Report does not include API calls made in the last 48 hours, or authorization and token API calls. For real-time investigations, rely on your application logs first.
</Warning>

For step-by-step setup instructions, see <Link href="/guides/troubleshooting/app-diagnostics-report">App Diagnostics Report</Link>.

## Capture the request ID for Box Support

If you need to escalate to [Box Support](https://support.box.com/hc/en-us/requests/new), include the full Box error response and at least one of:

* The `request_id` value from the error response body.
* The `box-request-id` response header from the failed call.
* The `API Request ID` column from an App Diagnostics Report.

With one of these IDs, Box Support can locate the exact request on the server side. Without one, investigating a single failure across millions of daily API calls is much slower.

## Debug common scenarios

The following checklist covers the failure modes most apps hit first.

### Authentication and token issues

| Symptom | First check |
| - | - |
| `401 invalid_token` | The token expired or was revoked. Refresh it, or request a new one. See <Link href="/guides/authentication/tokens/refresh">Refresh a token</Link>. |
| `400 invalid_grant` with "Current date time must be before the expiration date time" | The clock on the host running your app is out of sync with NTP. Re-sync time. |
| `400 invalid_client` | The `client_id` or `client_secret` in your token request does not match the values in the Developer Console. |
| `400 unauthorized_client` | A JWT or CCG application has not been authorized by the enterprise admin. See <Link href="/guides/authorization/platform-app-approval">Platform App Approval</Link>. |

For UI-side authorization errors (admin console messages), see <Link href="/guides/authorization/common-errors">Authorization common errors</Link>.

### Permission and access issues

| Symptom | First check |
| - | - |
| `403 access_denied_insufficient_permissions` | The user or [service account](/guides/getting-started/users#service-account) does not have access to the item, or your app is missing the required scope. Confirm the item is shared with the service account if you use CCG or JWT. |
| `403 insufficient_scope` | The application scopes in the Developer Console do not include the one this endpoint needs. See <Link href="/guides/api-calls/permissions-and-errors/scopes">Scopes</Link>. |
| `404 not_found` on an item you can see in the web app | Your token belongs to a different user (often the [service account](/guides/getting-started/users#service-account)) that has not been invited to the item. |

### Rate limit and capacity issues

| Symptom | First check |
| - | - |
| `429 rate_limit_exceeded` | Honor the `retry-after` header and back off. Review which limit you are hitting in <Link href="/guides/api-calls/permissions-and-errors/rate-limits">Rate limits</Link>. |
| Latency spikes plus 5xx | Check the [Box status page](https://status.box.com/) for known incidents. Add exponential back-off if you have not already. |

### Webhook issues

| Symptom | First check |
| - | - |
| Webhooks never arrive | Confirm the target URL is publicly reachable over HTTPS and returns `2xx` to a test `POST`. Check that the webhook is scoped to the correct trigger and item. |
| Webhooks arrive but processing fails | Log the full payload, then replay it against your handler. Verify the signature before processing in production. See <Link href="/guides/webhooks/v2/signatures-v2">Verify webhook signatures</Link>. |

## Check the Box status page

If multiple unrelated calls start failing with `5xx` errors, before you dig into your own code, check [status.box.com](https://status.box.com/) for a known incident. When Box has an active incident, the right action is usually to back off and let the existing retry logic ride it out.

## Next steps

* Review the full catalog of error codes in <Link href="/guides/api-calls/permissions-and-errors/common-errors">Errors</Link>.
* Tune your retry policy against the limits in <Link href="/guides/api-calls/permissions-and-errors/rate-limits">Rate limits</Link>.
* Run an <Link href="/guides/troubleshooting/app-diagnostics-report">App Diagnostics Report</Link> the next time you see an unexpected failure.

<RelatedLinks title="RELATED GUIDES" />


# Home
Source: https://developer.box.com/index

Build with the Box Platform. Explore guides, API reference, SDKs, and tutorials for content management, Box AI, e-signatures, and enterprise integrations.

<HideElements />

<div>
  # Welcome to Box

  <p>
    Learn how to use Box to manage documents at scale with enterprise security, real-time collaboration, e-signatures, workflow automation, and AI built in. Then extend those capabilities into your own applications using Box APIs, SDKs, embeddable UI components, and webhooks.
    <Link href="/guides/getting-started/why-box">Learn why developers choose Box</Link>.
  </p>

  <div>
    <a href={localizeLink("/guides/getting-started")}>
      Quick start
    </a>

    <a href={localizeLink("/reference")}>
      API reference
    </a>
  </div>

  ## I want to…

  <p>
    Start with the outcome that matches your goal.
  </p>

  <CardGroup>
    <Card title="Connect AI agents" href={localizeLink("/tutorials/connect-an-agent-to-box")} icon="sparkles">
      Give AI agents access to Box content through the Box CLI or the Box MCP server.
    </Card>

    <Card title="Automate invoice intake" href={localizeLink("/tutorials/invoice-intake")} icon="file-invoice">
      When a PDF lands in your inbox folder, Box AI Extract pulls vendor, dates, and totals into searchable metadata.
    </Card>

    <Card title="Display content interfaces to users" href={localizeLink("/tutorials/explorer-metadata-view")} icon="window-maximize">
      Let users browse, filter, and edit files by metadata inside your application.
    </Card>

    <Card title="Build an AI knowledge base" href={localizeLink("/tutorials/sales-rfp-answer-bank")} icon="magnifying-glass">
      Index curated content in a Box Hub and get answers with Box AI.
    </Card>

    <Card title="Create a company brain" href={localizeLink("/tutorials/company-brain")} icon="brain">
      Develop a secure, governed source for humans and agents to work from the same content, versions, and context.
    </Card>

    <Card title="Review documents in your own app" href={localizeLink("/tutorials/secure-in-app-document-review")} icon="eye">
      Embed a secure, expiring preview of files stored in Box, then let reviewers annotate in context.
    </Card>
  </CardGroup>

  <h2>Get started</h2>

  <CardGroup>
    <Card title="Explore user types" href={localizeLink("/guides/getting-started/users/")} icon="users" />

    <Card title="Understand application types" href={localizeLink("/guides/applications/platform-apps/index/")} icon="puzzle" />

    <Card title="Learn about authentication methods" href={localizeLink("/guides/authentication")} icon="fingerprint" />

    <Card title="Authorize an application" href={localizeLink("/guides/authorization/")} icon="shield-check" />

    <Card title="Upload files to Box" href={localizeLink("/guides/uploads/")} icon="cloud-arrow-up" />

    <Card title="Download files from Box" href={localizeLink("/guides/downloads/")} icon="download" />
  </CardGroup>

  ## New here? Start in 3 steps

  <Steps>
    <Step title={<a href="https://cloud.app.box.com/developers/console" className="no-underline hover:underline">Open the Developer Console</a>}>
      Create an application, configure scopes, and generate credentials.
    </Step>

    <Step title={<Link href="/guides/getting-started">Make your first API call</Link>}>
      Upload a file and authenticate with a developer token.
    </Step>

    <Step title={<Link href="/guides/tutorials">Pick a tutorial for your use case</Link>}>
      Build something real: invoice automation, RFP answer banks, and more.
    </Step>
  </Steps>

  ## Browse by topic

  <CardGroup>
    <Card title="Authentication & authorization" href={localizeLink("/guides/authentication")} icon="fingerprint">
      OAuth, JWT, app tokens, and scoped access for users and services.
    </Card>

    <Card title="Security" href={localizeLink("/guides/security")} icon="camera-cctv">
      Access tokens, scopes, permissions, and platform controls that protect your content.
    </Card>

    <Card title="Collaboration" href={localizeLink("/guides/collaborations/index")} icon="users">
      Invite collaborators, manage access, and share content across teams.
    </Card>

    <Card title="Box AI" href={localizeLink("/ai/box-ai-api")} icon="sparkles">
      Summarize, extract, generate, and query content with enterprise permissions intact.
    </Card>

    <Card title="Supported AI models" href={localizeLink("/guides/box-ai/ai-models/index")} icon="microchip">
      Core and customer-enabled models with access levels, capability tiers, and API names.
    </Card>

    <Card title="Intelligent workflow" href={localizeLink("/guides/intelligent-workflow")} icon="gears">
      Build governed, agentic content workflows without running your own orchestration stack.
    </Card>

    <Card title="Metadata" href={localizeLink("/guides/metadata/index")} icon="tags">
      Tag files with structured fields your apps can search and automate on.
    </Card>

    <Card title="Search" href={localizeLink("/guides/search/index")} icon="magnifying-glass">
      Find files and metadata across your enterprise content.
    </Card>

    <Card title="Webhooks & events" href={localizeLink("/guides/webhooks/index")} icon="bell">
      React to uploads, permission changes, and enterprise activity in real time.
    </Card>
  </CardGroup>

  ## Stay connected

  <CardGroup>
    <Card title="Changelog" href={localizeLink("/changelog/")} icon="clock-rotate-left" />

    <Card title="Developer blog" href="https://blog.box.com/developer" icon="newspaper" />

    <Card title="Developer playlist" href="https://www.youtube.com/playlist?list=PL0F3BD5B64D6A39F1" icon="youtube" />

    <Card title="Community" href="https://community.box.com/box-platform-5" icon="comments" />
  </CardGroup>
</div>


# Sample Code Catalog
Source: https://developer.box.com/sample-code

Explore sample code and demo applications for Box APIs, SDKs, and UI Elements

<SampleCodeCatalog />


# Add content to Box Archive
Source: https://developer.box.com/guides/archives/add-content



To add content to an archive, you need to create it first. If you
have not done this yet, use the <Link href="/reference/v2025.0/post-archives/">Create Archive</Link> endpoint.

## Add file or folder to archive

Use the <Link href="/reference/put-files-id">`PUT /files/:id`</Link> API endpoint to add a file to an archive, or the <Link href="/reference/put-folders-id">`PUT /folders/:id`</Link> endpoint to add a folder.
The `id` parameter is the ID of the file/folder you want to add to the archive.
To specify the destination, use the `parent.id` <Link href="/reference/put-folders-id/#param-parent-id">parameter</Link> in the request body.
This can be either an ID of an archive or the ID of a folder that is inside an archive.

[Update parent id of file]: /reference/put-files-id/#param-parent-id

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Box Archive
Source: https://developer.box.com/guides/archives/index



<Note>
  Box Archive is available only for Enterprise Advanced accounts.
</Note>

Box Archive allows you to create and manage archives. An archive is a folder dedicated to
storing content that is redundant, outdated, or trivial. Content in an archive is owned by the enterprise,
and it is not accessible to the previous owner and collaborators.

## Archives are folders

Archives are a special type of folders. Box Archive APIs allow you to create, list, update and delete archives.
However, there are other APIs that also work with archives or with content within archives.
For a full list of supported APIs, see the <Link href="/guides/archives/supported-apis">Supported APIs</Link> guide.

## Required scopes

Before using any of the Box Archive APIs, make sure you can access [Box Archive in Admin Console][Box Archive in Admin Console].
Your platform app must have the `GCM` and `Read and write all files and folders` <Link href="/guides/api-calls/permissions-and-errors/scopes/">scopes</Link> enabled.
If you plan to only view archives and not modify them, use the `Read all files and folders` instead of the `Read and write all files and folders` scope.
Additionally, to be able to assign <Link href="/reference/resources/storage-policy/">storage policy</Link> to an archive during its creation, your enterprise must have access to the Box Zones feature and your app must have the `Manage users` scope.

<Note>
  The `GCM` scope is not available in the Developer Console and needs to be enabled by contacting customer support.
</Note>

[Box Archive in Admin Console]: https://support.box.com/hc/en-us/p/Product_Page_2023?section-id=40168863437843

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Restore content from Box Archive
Source: https://developer.box.com/guides/archives/restore-content



This guide describes how to restore content that you archived by mistake.

## Restore file or folder from archive

Use the <Link href="/reference/put-files-id">`PUT /files/:id`</Link> API endpoint to restore a file from an archive, or the <Link href="/reference/put-folders-id">`PUT /folders/:id`</Link> endpoint to restore a folder from an archive.
The `id` parameter is the ID of the file/folder you want to restore from an archive.
To specify the destination, use the `parent.id` <Link href="/reference/put-folders-id/#param-parent-id">parameter</Link> in the request body.
This is the ID of a folder (can be owned by any user) where you want to restore the file/folder.

To restore a file/folder to user's root folder, use `0` as the `parent.id` value. Additionally, pass the ID of the user in the
`parent.user_id` <Link href="/reference/put-folders-id/#param-parent-user_id">parameter</Link> in the request body.

[Update parent id of file]: /reference/put-files-id/#param-parent-id

[Update parent user id of file]: /reference/put-files-id/#param-parent-user_id

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Supported APIs for Box Archive
Source: https://developer.box.com/guides/archives/supported-apis



The basic Box Archive APIs allow you to create, list, update and delete archives, but you can use other APIs to interact with an archive or its content.
See the table below for the full list of those APIs.

<Note>
  Those APIs require the <Link href="/guides/api-calls/permissions-and-errors/scopes/#global-content-manager-gcm">`GCM` scope</Link> to be enabled in your application.
  This scope is not available in the Developer Console and needs to be enabled by contacting customer support.

  Additionally, some of the below APIs need to be enabled by contacting customer support to properly work with Box Archive.
  When contacting customer support, specify the user ID you plan to use those APIs with.
</Note>

| API Endpoint | Description |
| - | - |
| <Link href="/reference/v2025.0/post-archives/">`POST /archives`</Link> | Create an archive. |
| <Link href="/reference/v2025.0/get-archives/">`GET /archives`</Link> | List all archives. |
| <Link href="/reference/v2025.0/put-archives-id/">`PUT /archives/:id`</Link> | Update an archive. |
| <Link href="/reference/v2025.0/delete-archives-id/">`DELETE /archives/:id`</Link> | Delete an archive. |
| <Link href="/reference/put-files-id">`PUT /files/:id`</Link> | Add a file to an archive, restore a file from an archive, or move a file within/between archives. Other updates to the file are not allowed. Requires contacting customer support to enable. |
| <Link href="/reference/put-folders-id">`PUT /folders/:id`</Link> | Add a folder to an archive, restore a folder from an archive, move a folder within/between archives, or rename and change the description of a folder in an archive. Other updates to the folder are not allowed. Requires contacting customer support to enable. |
| <Link href="/reference/post-files-content">`POST /files/content`</Link> | Upload a file to an archive or to a folder within an archive. Requires contacting customer support to enable. |
| <Link href="/reference/get-files-id-content">`GET /files/:id/content`</Link> | Download a file from an archive or from a folder within an archive. |
| <Link href="/reference/post-zip-downloads">`POST /zip_downloads`</Link> | Download a zip file of an archive or of a folder within an archive. |
| <Link href="/reference/post-folders">`POST /folders`</Link> | Create a folder within an archive. Requires contacting customer support to enable. |
| <Link href="/reference/get-files-id">`GET /files/:id`</Link> | Get details of a file within an archive. |
| <Link href="/reference/get-folders-id">`GET /folders/:id`</Link> | Get details of an archive or of a folder within an archive. |
| <Link href="/reference/get-folders-id-items">`GET /folders/:id/items`</Link> | List items within an archive or items in a folder within an archive. |
| <Link href="/reference/post-files-id-copy">`POST /files/:id/copy`</Link> | Copy a file to an archive. |
| <Link href="/reference/post-folders-id-copy">`POST /folders/:id/copy`</Link> | Copy a folder to an archive. |
| <Link href="/reference/delete-files-id">`DELETE /files/:id`</Link> | Permanently delete a file within an archive. |
| <Link href="/reference/delete-folders-id">`DELETE /folders/:id`</Link> | Permanently delete a folder within an archive. Requires contacting customer support to enable. |
| <Link href="/reference/post-files-id-metadata-id-id">`POST /files/:id/metadata/:scope/:template_key`</Link> | Create a metadata instance attached to a file within an archive. |
| <Link href="/reference/get-files-id-metadata-id-id">`GET /files/:id/metadata/:scope/:template_key`</Link> | View a metadata instance attached to a file within an archive. |
| <Link href="/reference/get-files-id-metadata">`GET /files/:id/metadata`</Link> | List all metadata instances attached to a file within an archive. |
| <Link href="/reference/put-files-id-metadata-id-id">`PUT /files/:id/metadata/:scope/:template_key`</Link> | Update a metadata instance attached to a file within an archive. |
| <Link href="/reference/delete-files-id-metadata-id-id">`DELETE /files/:id/metadata/:scope/:template_key`</Link> | Delete a metadata instance attached to a file within an archive. |
| <Link href="/reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo">`POST securityClassification`</Link> | Create a classification label for a file within an archive. |
| <Link href="/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo">`GET securityClassification`</Link> | View a classification label of a file within an archive. |
| <Link href="/reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo">`PUT securityClassification`</Link> | Update a classification label for a file within an archive. |
| <Link href="/reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo">`DELETE securityClassification`</Link> | Delete a classification label from a file within an archive. |

<RelatedLinks title="RELATED RESOURCES" />


# Get started with Box Notes API
Source: https://developer.box.com/guides/box-notes/get-started

Set up authentication and create your first Box Note from Markdown content.

This guide walks you through creating your first Box Note from
Markdown using the Box Notes API. By the end, you have a
`.boxnote` file in your Box account created from a single API call.

## Prerequisites

Before you begin, make sure you have:

* A Box account with file upload permissions.
* A <Link href="/guides/applications/platform-apps/create">platform application</Link> configured in the Box Developer Console.
* A valid access token for authentication (OAuth 2.0 or JWT).
* A target folder ID in Box where you want to create the note.

<Note>
  The Box Notes API requires API version `2026.0`. All requests must
  include the `box-version: 2026.0` header.
</Note>

## Step 1: Generate an access token

You need an access token to authenticate your API calls.

To generate a developer token for testing:

1. Go to **Developer Console** > **My Platform Apps**.
2. Select the **Options menu** button (**…**) next to your app.
3. Select **Generate Developer Token**. The token is automatically
   copied to your clipboard.

<Warning>
  Developer tokens expire after one hour. For production use, implement
  <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> or
  <Link href="/guides/authentication/jwt">JWT authentication</Link>.
</Warning>

## Step 2: Identify your target folder

You need the ID of the folder where you want to create the note. To find a
folder ID:

* Open the folder in the Box web app. The folder ID is the number at
  the end of the URL: `https://app.box.com/folder/123456789`.
* Alternatively, use the <Link href="/reference/get-folders-id">Get
  folder</Link> API endpoint.

<Tip>
  Use `0` as the folder ID to create the note in the root folder
  (All Files).
</Tip>

## Step 3: Create your first Box Note

Send a `POST` request to the `/2.0/notes/convert` endpoint with your
Markdown content. The API converts the Markdown to a Box Note and
uploads it to the specified folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST 'https://api.box.com/2.0/notes/convert' \
       -H 'box-version: 2026.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>' \
       -H 'Content-Type: application/json' \
       -d '{
         "content": "# Welcome\n\nThis is my first **Box Note** created using the API.",
         "content_format": "markdown",
         "parent": {
           "type": "folder",
           "id": "123456789"
         },
         "name": "My First Note"
       }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.box.com/2.0/notes/convert"
  headers = {
      "box-version": "2026.0",
      "Authorization": "Bearer <ACCESS_TOKEN>",
      "Content-Type": "application/json",
  }
  payload = {
      "content": "# Welcome\n\nThis is my first **Box Note** created using the API.",
      "content_format": "markdown",
      "parent": {"type": "folder", "id": "123456789"},
      "name": "My First Note",
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.status_code, response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.box.com/2.0/notes/convert", {
    method: "POST",
    headers: {
      "box-version": "2026.0",
      Authorization: "Bearer <ACCESS_TOKEN>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content:
        "# Welcome\n\nThis is my first **Box Note** created using the API.",
      content_format: "markdown",
      parent: { type: "folder", id: "123456789" },
      name: "My First Note",
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

A successful request returns `201 Created` with the new file's
information:

```json theme={null}
{
  "type": "file",
  "id": "1234567890"
}
```

## Step 4: Verify the note was created

Use the returned `id` to retrieve the full file metadata from the
Box Files API:

```sh theme={null}
curl -L 'https://api.box.com/2.0/files/1234567890' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

You can also open the Box web app and navigate to the target folder
to confirm the `.boxnote` file appears.

## Next steps

Now that you have created your first Box Note, explore these guides:

<RelatedLinks title="RELATED GUIDES" />


# Box Notes API
Source: https://developer.box.com/guides/box-notes/index

Programmatically create Box Notes from Markdown content using the Box Notes API.

The Box Notes API lets you programmatically convert Markdown content
into native Box Notes (`.boxnote` format) and upload them directly to
the Box filesystem in a single API call. The API handles Markdown
to ProseMirror conversion, preflight validation, and file upload
behind the scenes, so you don't need to construct `.boxnote` files
yourself.

<Note>
  The Box Notes API currently supports creating notes from Markdown
  content only. Reading, updating, listing, and deleting notes are
  managed through the existing
  <Link href="/reference/get-files-id">Box Files API</Link>.
  Additional input formats and operations may be added in the future.
</Note>

## How it works

When you send a request to `POST /2.0/notes/convert`, the API
performs the following steps:

<Steps>
  <Step title="Validate the request">
    The API validates the request body, checking for required
    fields, content size limits, and a valid `content_format`.
  </Step>

  <Step title="Run a preflight check">
    A preflight file-upload check verifies the caller's
    permissions, storage quota, and naming conflicts in the
    target folder.
  </Step>

  <Step title="Convert the content">
    The Markdown content is converted into a Box Notes ProseMirror
    document in `.boxnote` format.
  </Step>

  <Step title="Upload the file">
    The resulting `.boxnote` file is uploaded to the specified
    parent folder.
  </Step>

  <Step title="Return the result">
    The API returns `201 Created` with the new file's `type` and
    `id`.
  </Step>
</Steps>

## Box Notes API version

The Box Notes API is available starting in Box API version `2026.0`.
All API requests to Box Notes API endpoints must include the
`box-version` header set to `2026.0`.

For more details, see
<Link href="/guides/api-calls/api-versioning-strategy">Box API versioning</Link>.

## Supported operations

| Operation | Supported | Details |
| - | - | - |
| Create (convert) | Yes | `POST /2.0/notes/convert` |
| Read | No | Use `GET /2.0/files/{file_id}` after creation |
| Update | No | Not supported in this API |
| Delete | No | Use `DELETE /2.0/files/{file_id}` |
| List | No | Use the <Link href="/reference/get-folders-id-items">Box Folders API</Link> |

## Permissions

The Box Notes API uses existing Box file upload permissions. No new
OAuth scopes are required. If the authenticated user has permission
to upload files to the target folder, they can create notes using
this API.

## Limitations

| Constraint | Limit |
| - | - |
| Maximum content size | 1 MB |
| Supported input formats | Markdown only |
| Maximum conversion time | Up to 30 seconds per request |
| Response payload | Minimal - `type` and `id` only |

<Tip>
  To retrieve full file metadata after creating a note, call
  `GET /2.0/files/{file_id}` with the returned `id`.
</Tip>

## Next steps

<CardGroup>
  <Card title="Get started" icon="rocket" href={localizeLink("/guides/box-notes/get-started")}>
    Set up authentication and create your first Box Note from
    Markdown.
  </Card>

  <Card title="Convert Markdown to Box Note" icon="file-lines" href={localizeLink("/guides/box-notes/convert-markdown")}>
    Detailed guide covering request parameters, error handling,
    and code examples.
  </Card>

  <Card title="Use cases" icon="lightbulb" href={localizeLink("/guides/box-notes/use-cases")}>
    Common scenarios for AI-generated notes, automated reports,
    and third-party content import.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED APIS" />


# Allow a domain for collaboration
Source: https://developer.box.com/guides/collaborations/allowed-domains/create



An enterprise that normally restricts creating collaborations can
add domains, such as `example.com`, to a list for which collaborations may be
created within the enterprise.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/collaboration_whitelist_entries" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "domain": "example.com",
         "direction": "inboud"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.collaborationAllowlistEntries.createCollaborationWhitelistEntry({
    direction:
      'inbound' as CreateCollaborationWhitelistEntryRequestBodyDirectionField,
    domain: domain,
  } satisfies CreateCollaborationWhitelistEntryRequestBody);
  ```

  ```python Python v10 theme={null}
  client.collaboration_allowlist_entries.create_collaboration_whitelist_entry(
      domain, CreateCollaborationWhitelistEntryDirection.INBOUND
  )
  ```

  ```cs .NET v10 theme={null}
  await client.CollaborationAllowlistEntries.CreateCollaborationWhitelistEntryAsync(requestBody: new CreateCollaborationWhitelistEntryRequestBody(direction: CreateCollaborationWhitelistEntryRequestBodyDirectionField.Inbound, domain: domain));
  ```

  ```swift Swift v10 theme={null}
  try await client.collaborationAllowlistEntries.createCollaborationWhitelistEntry(requestBody: CreateCollaborationWhitelistEntryRequestBody(direction: CreateCollaborationWhitelistEntryRequestBodyDirectionField.inbound, domain: domain))
  ```

  ```java Java v10 theme={null}
  client.getCollaborationAllowlistEntries().createCollaborationWhitelistEntry(new CreateCollaborationWhitelistEntryRequestBody(domain, CreateCollaborationWhitelistEntryRequestBodyDirectionField.INBOUND))
  ```

  ```cs .NET v6 theme={null}
  BoxCollaborationWhitelistEntry entry = await client.CollaborationWhitelistManager.AddCollaborationWhitelistEntryAsync(
      "example.com",
      "both"
  );
  ```

  ```javascript Node v4 theme={null}
  client.collaborationAllowlist.addDomain('test.com', client.collaborationAllowlist.directions.INBOUND, callback);
  ```
</CodeGroup>

The
<Link href="/reference/post-collaboration-whitelist-entries">endpoint</Link>
will require the `domain` to allow the collaborations between, and a
`direction`, which may be set to:

* `inbound`: Whether external users may be collaborated in on content in your enterprise.
* `outbound`: Whether your enterprise managed users may be collaborated in on content owned within an external enterprise.
* `both`: Both of the above.

Supply both parameters to set up the new allowed domain.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/collaboration_whitelist_entries" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "domain": "example.com",
         "direction": "inboud"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.collaborationAllowlistEntries.createCollaborationWhitelistEntry({
    direction:
      'inbound' as CreateCollaborationWhitelistEntryRequestBodyDirectionField,
    domain: domain,
  } satisfies CreateCollaborationWhitelistEntryRequestBody);
  ```

  ```python Python v10 theme={null}
  client.collaboration_allowlist_entries.create_collaboration_whitelist_entry(
      domain, CreateCollaborationWhitelistEntryDirection.INBOUND
  )
  ```

  ```cs .NET v10 theme={null}
  await client.CollaborationAllowlistEntries.CreateCollaborationWhitelistEntryAsync(requestBody: new CreateCollaborationWhitelistEntryRequestBody(direction: CreateCollaborationWhitelistEntryRequestBodyDirectionField.Inbound, domain: domain));
  ```

  ```swift Swift v10 theme={null}
  try await client.collaborationAllowlistEntries.createCollaborationWhitelistEntry(requestBody: CreateCollaborationWhitelistEntryRequestBody(direction: CreateCollaborationWhitelistEntryRequestBodyDirectionField.inbound, domain: domain))
  ```

  ```java Java v10 theme={null}
  client.getCollaborationAllowlistEntries().createCollaborationWhitelistEntry(new CreateCollaborationWhitelistEntryRequestBody(domain, CreateCollaborationWhitelistEntryRequestBodyDirectionField.INBOUND))
  ```

  ```cs .NET v6 theme={null}
  BoxCollaborationWhitelistEntry entry = await client.CollaborationWhitelistManager.AddCollaborationWhitelistEntryAsync(
      "example.com",
      "both"
  );
  ```

  ```javascript Node v4 theme={null}
  client.collaborationAllowlist.addDomain('test.com', client.collaborationAllowlist.directions.INBOUND, callback);
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Remove a previously allowed domain for collaboration
Source: https://developer.box.com/guides/collaborations/allowed-domains/delete



Deleting a domain from the list of allowed collaboration domains will remove the
ability for collaborations to be created between your enterprise and users in
that domain.

To remove a domain from the allowed list, supply the ID of the list entry to
the delete request. This ID is returned when <Link href="/guides/collaborations/allowed-domains/create">allowing a new domain</Link>
or <Link href="/guides/collaborations/allowed-domains/list">listing the allowed domains in the enterprise</Link>.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/collaboration_whitelist_entries/213123" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.collaborationAllowlistEntries.deleteCollaborationWhitelistEntryById(
    entry.id!,
  );
  ```

  ```python Python v10 theme={null}
  client.collaboration_allowlist_entries.delete_collaboration_whitelist_entry_by_id(
      entry.id
  )
  ```

  ```cs .NET v10 theme={null}
  await client.CollaborationAllowlistEntries.DeleteCollaborationWhitelistEntryByIdAsync(collaborationWhitelistEntryId: NullableUtils.Unwrap(entry.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.collaborationAllowlistEntries.deleteCollaborationWhitelistEntryById(collaborationWhitelistEntryId: entry.id!)
  ```

  ```java Java v10 theme={null}
  client.getCollaborationAllowlistEntries().deleteCollaborationWhitelistEntryById(entry.getId())
  ```

  ```cs .NET v6 theme={null}
  string entryID = "11111";
  await client.CollaborationWhitelistManager.DeleteCollaborationWhitelistEntryAsync(entryID);
  ```

  ```javascript Node v4 theme={null}
  client.collaborationAllowlist.removeDomain('12345', callback);
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Allowed collaboration domains overview
Source: https://developer.box.com/guides/collaborations/allowed-domains/index



Within the content and sharing settings for an enterprise, an admin can specify
[collaboration restrictions][collab-restrictions] for the enterprise. These
settings include the ability to limit collaborations to only a series of
allowed domains.

The allowed domain APIs are available to allow applications with
appropriate permissions to add, fetch, and delete these allowed domains
programmatically for the enterprise.

[collab-restrictions]: https://support.box.com/hc/en-us/articles/4404822772755-Enterprise-Settings-Content-Sharing-Tab


# List allowed domains for collaboration
Source: https://developer.box.com/guides/collaborations/allowed-domains/list



Listing the domains that are allowed for collaboration will return all domains
that permit collaborations to be created with the current enterprise.

There are no required parameters for the request, but `limit` and `market`
parameters may optionally be set to limit and page through the full result set.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/collaboration_whitelist_entries" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.collaborationAllowlistEntries.getCollaborationWhitelistEntries();
  ```

  ```python Python v10 theme={null}
  client.collaboration_allowlist_entries.get_collaboration_whitelist_entries()
  ```

  ```cs .NET v10 theme={null}
  await client.CollaborationAllowlistEntries.GetCollaborationWhitelistEntriesAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.collaborationAllowlistEntries.getCollaborationWhitelistEntries()
  ```

  ```java Java v10 theme={null}
  client.getCollaborationAllowlistEntries().getCollaborationWhitelistEntries()
  ```

  ```cs .NET v6 theme={null}
  BoxCollectionMarkerBased<BoxCollaborationWhitelistEntry> whitelistedDomains = await client.CollaborationWhitelistManager
      .GetAllCollaborationWhitelistEntriesAsync();
  ```

  ```javascript Node v4 theme={null}
  client.collaborationAllowlist.getAllAllowlistedDomains(callback);
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Configure Box (Slack integration)
Source: https://developer.box.com/guides/collaborations/connect-slack-to-group-collabs/configure-box



<ProgressBar />

We will need to set up a Box application to manage Box groups and add
collaborators to files and folders in Box.

## Set up a Box app

<Grid>
  <Choose>
    # Create a new Box app

    Create and configure a new Box JWT application to use for this integration.
  </Choose>

  <Choose>
    # Use an existing approved app

    Use one of your existing admin-approved Box JWT applications from the Box
    developer console.
  </Choose>
</Grid>

<Choice>
  # Create a new Box app

  To create a new Box application that can be used to call the Box APIs, use
  the following steps.

  1. Go to the [Developer Console][devconsole]
  2. Select **Create New App**
  3. Select **Platform App** as the type of application to create, and click **Next**
  4. Select **OAuth 2.0 with JWT** as the authentication method, and click **Next**
  5. Give your Box app a unique name and click **Create App**
  6. Go to the app's configuration by clicking **View Your App**.
  7. Scroll down to **Application Access** and ensure that **Enterprise** is selected.
  8. Scroll to the **Application Scopes** section of the same screen and ensure that at least the following scopes are enabled: **Read and write all files and folders stored in Box**, **Manage users**, and **Manage groups**.
  9. Under **Advanced Features** ensure that **Perform Actions as Users** is enabled to perform actions on behalf of Box users.
  10. At the top of the page click the button to **Save Changes**

  <Warning>
    **App approval**

    Once the application is created it will still need to be approved by an
    enterprise admin before you will be able to make calls to the Box APIs.

    Follow <Link href="/guides/authorization/platform-app-approval">this guide</Link> to have the
    application approved in your enterprise.
  </Warning>
</Choice>

<Choice>
  # Use an Existing JWT Box application

  If you have an existing JWT based Box application in your
  [developer console][devconsole] that you would like to use, ensure that the
  following options are set in the **Configuration** section of your
  application.

  * Authentication Method: Should be set to OAuth 2.0 with JWT (Server Authentication).
  * Application Scopes: Set at least the following scopes.
    * Read and write all files and folders stored in Box
    * Manage users
    * Manage groups
  * Advanced Features: Both options should be enabled to perform actions as users and generate user access tokens.

    <Warning>
      **App approval**

      Once the application is updated it will need to be re-approved by an
      enterprise admin before you will be able to make calls to any of the Box
      APIs that need any of the new permissions.

      Follow <Link href="/guides/authorization/platform-app-approval">this guide</Link> to have the
      application approved in your enterprise.
    </Warning>
</Choice>

## Download app configuration

To begin working with the Box SDKs used in this tutorial, you will need the
application configuration file from the **Configuration** page of your
application. This will include all information needed to verify your
application to start making API requests with the Box SDKs.

Within the **Add and Manage Public Keys** section of the **Configuration**
page, click to **Generate a Public/Private Keypair**. This will send you
through 2FA verification before downloading the configuration file for your
application.

Store that file as `boxConfig.json` in a location accessible by your
application.

## Summary

* You created a new, or are using an existing, Box app which is approved by an enterprise admin.
* You downloaded your application configuration file and stored it in a location accessible by your application.

<Observe>
  <Next>I downloaded my application configuration file</Next>
</Observe>

[devconsole]: https://cloud.app.box.com/developers/console


# Configure Slack
Source: https://developer.box.com/guides/collaborations/connect-slack-to-group-collabs/configure-slack



<ProgressBar />

The first step in this guide is to create and configure a Slack application.
This Slack application will act as a bot that listens for user events in Slack
channels, and responds to **slash commands** by users in those channels -
allowing them to share Box files and folders with the group.

This section will take you through the following steps.

* Create a minimal Slack application within the Slack API dashboard
* Configure the Slack application to send notifications to our application whenever a user joins or leaves the channel - allowing our code to update the Box group.
* Configure a `/boxadd` **slash command** that will allow users to share a Box file or folder with all the users in the channel.

## Create a minimal Slack app

Go to the **[Slack apps page][slack-apps]** and click **Create an App**. Add
an **App Name**, select your **Development Slack Workspace** from the dropdown
list where the bot will be deployed to, then click **Create App**.

<Frame>
  <img alt="Create a Slack App" />
</Frame>

Once created, you will be redirected to the basic information section of the
application. You may adjust the icon and description of your app within the
**Display Information** section at the bottom to customize the application
in your workspace.

## Configure the Slack app's event listener

Setting up an event listener for our Slack app will allow us to monitor for
events within the channel. For this bot, we want to monitor three
[Slack events][slack-events] in order to perform actions within Box.

* [`bot_added`][slack-event-bot-added]: When the bot is first added to a channel, it will get a list of all users in the channel, then create a Box group for those users. We can then use this group later on to add that group to any content that is shared with the **slash command**.
* [`member_joined_channel`][slack-event-member-joined]: When a new user joins a Slack channel they will be added to the Box group.
* [`member_left_channel`][slack-event-member-left]: When a user leaves a Slack channel, or the user is removed, they will be removed from the Box group.

To set up a notification URL to which these Slack event payloads will
be sent, Slack requires a verification step. When you set an event listener URL
for your bot application code, Slack will immediately send a challenge to that
URL to verify that it's valid. This will be an HTTP POST with a payload that
looks something like the following:

```json theme={null}
{
  "token": "Jhj5dZrVaK7ZwHHjRyZWjbDl",
  "challenge": "3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P",
  "type": "url_verification"
}
```

To set up the URL for the event listener, that URL that is set needs
to respond with a verification payload containing the challenge value back to
Slack during this step. The payload will look similar to the following.

```js theme={null}
HTTP 200 OK Content-type: application/json {"challenge":"3eZbrw1aBm2rZgRNFdxV2595E9CY3gmdALWMmHkvFXO7tYXAYM8P"}
```

To do this we will deploy a small bit of code to respond to the challenge
event. Choose your preferred language / framework below to get started.

<Grid>
  <Choose>
    # Node (Express Framework)
  </Choose>

  <Choose>
    # Java (Spring Boot Framework)
  </Choose>
</Grid>

<Choice>
  Within the project directory, run `npm install express --save` to install the
  Express dependency, then deploy the following code to your public endpoint
  along with the appropriate Node modules.

  ```js theme={null}
  const express = require('express');
  const app = express();
  const port = process.env.PORT || 3000;

  app.use(express.urlencoded({ extended: true }));
  app.use(express.json());

  app.post('/event', (req, res) => {
      if (
          req.body &&
          req.body.challenge &&
          req.body.type === 'url_verification'
      ) {
          res.send({
              challenge: req.body.challenge
          });
      } else {
          res.status(400).send({
              error: "Unrecognized request"
          });
      }
  });

  app.listen(port, function(err) {
      console.log("Server listening on PORT", port);
  });
  ```
</Choice>

<Choice>
  <Tip>
    [`Spring Initializr`][spring-initializr] is a useful service for
    auto-generating a new Spring boot application with all dependencies defined.
    This may be used instead of creating a blank Java application.
  </Tip>

  * From Eclipse, create a new project. When prompted, select a Gradle project.
  * Enter a unique name for the project, we used `slack.box` for this guide.
  * Open your `build.gradle` file and add the following. Ensure that the group matches the group that you used for the application. Once saved, refresh the Gradle project.

  ```java theme={null}
  plugins {
      id 'org.springframework.boot' version '2.3.1.RELEASE'
      id 'io.spring.dependency-management' version '1.0.9.RELEASE'
      id 'java'
  }

  group = 'com.box'
  version = '0.0.1-SNAPSHOT'
  sourceCompatibility = '1.8'

  repositories {
      mavenCentral()
  }

  dependencies {
      implementation 'org.springframework.boot:spring-boot-starter-web'
      testImplementation('org.springframework.boot:spring-boot-starter-test') {
          exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
      }
      compile 'com.box:box-java-sdk:2.44.1'
  }

  test {
      useJUnitPlatform()
  }
  ```

  * Within your `src/main/java` path, create a new Java class file named `Application.java`.
  * Open the file, add the following code, and save.

  ```java theme={null}
  package com.box.slack.box;

  import org.jose4j.json.internal.json_simple.JSONObject;
  import org.jose4j.json.internal.json_simple.parser.JSONParser;
  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
  import org.springframework.web.bind.annotation.PostMapping;
  import org.springframework.web.bind.annotation.RequestBody;
  import org.springframework.web.bind.annotation.RestController;

  @RestController
  @EnableAutoConfiguration
  public class Application {
      @PostMapping("/event")
      public JSONObject challenge(@RequestBody String data) throws Exception {
          JSONObject returnJSON = new JSONObject();

          Object dataObj = new JSONParser().parse(data);
          JSONObject inputJSON = (JSONObject) dataObj;
          String challenge = (String) inputJSON.get("challenge");
          String type = (String) inputJSON.get("type");

          if (type.equals("url_verification")) {
              returnJSON.put("challenge", challenge);
          } else {
              System.err.println("Invalid input");
          }

          return returnJSON;
      }

      public static void main(String[] args) {
          SpringApplication.run(Application.class, args);
      }
  }
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework above to get started.
  </Danger>
</Choice>

Now that we have the code to respond to the Slack challenge when adding an
event URL, we can configure that within the Slack application.

From your Slack application **Basic Information** tab, under
**Add features and functionality**, click on the button titled
**Event Subscriptions** and do the following.

* Toggle **Enable Events** to **On**.
* Under **Request URL** add in the public URL that you deployed the above code to, and be aware that we are listening at `{YOUR_APP_DOMAIN}/event` (such as `https://myapp.com/event`). Once you add the URL and click outside the field, Slack will immediately send the challenge to the URL that you were hosting the code at above. If the code responds correctly, you will see a green verified note beside the **Request URL** header.

<Frame>
  <img alt="Enable Slack Event Subscriptions" />
</Frame>

* Expand the **Subscribe to bot events** section and click on the **Add Bot User Event** button.
* Add `member_joined_channel` and `member_left_channel` to the events the bot is subscribed to. These will send events when anyone new is added to the channel.
* Click the **Save Changes** button at the bottom of the page.

## Configure the Slack app slash command

To provide every user in a Slack channel access to a file or folder in Box, we
can use a Slack **"slash command"**. A slash command will allow any person in
the channel to share content they own in Box with the rest of the channel.

Through this command, a channel member will be able to type
`/boxadd [file / folder] [id]`, for example `boxadd file 1459732312`, into the
channel to share the file / folder with every user in the channel. To do this,
the file is automatically collaborated with the Box group of users that are in
that channel.

From the **Basic Information** tab of your application, under **Add features and
functionality**, click on the button titled **Slash Commands**.

In the page that comes up, click **Create New Command** and input the following:

* **Command**: This is the command that a channel user will use to share a Box file / folder ID with the channel. Use `/boxadd` for this quick start.
* **Request URL**: The URL that is listening for and responding to slash commands in our Slack bot. In this quick start we use the same event URL that was used for the app event listener section above.
* **Short Description**: A description of what the Slash command will do.
* **Usage Hint**: Additional parameters that may be passed to the command. In our case, that's the Box file / folder ID and type of content.

<Frame>
  <img alt="Create Slack Slash Command" />
</Frame>

Click **Save** to add the command to our Slack app.

## Add Additional Scopes

When slash commands or notifications are sent to our application from
Slack they will contain a Slack user ID, which relates to the person that took
or was affected by the action. To translate that ID to a Box user we need to
get the Slack user's email, which we can then use to associate that Slack user
to a corresponding Box user. This action requires two extra scopes in the Slack
application configuration.

From your Slack application configuration, click on **OAuth & Permissions** in
the left menu, then do the following.

* Scroll down to the **Scopes** section.
* Click on the **Add an OAuth Scope** button under **Bot Token Scopes**.
* Search for and add `users:read` and `users:read.email`.

## Deploy Bot to Slack Workspace

The last step is to install the application into your Slack workspace. From the
**Basic Information** page of the app, expand the
**Install your app to your workspace** section.

<Frame>
  <img alt="Enable Slack Event Subscriptions" />
</Frame>

Click the button to **Install App to Workspace**.

<Frame>
  <img alt="Enable Slack Event Subscriptions" />
</Frame>

Once the **Allow** button is clicked you should see a success message. Your bot
is now installed within the workplace.

## Summary

* You've created your Slack application.
* You've configured user event notifications, slash commands, and additional scoping.
* You've deployed your Slack bot to your workspace.

<Observe>
  <Next>I have my local application set up</Next>
</Observe>

[slack-apps]: https://api.slack.com/apps

[slack-events]: https://api.slack.com/events

[slack-event-bot-added]: https://api.slack.com/events/bot_added

[slack-event-member-joined]: https://api.slack.com/events/member_joined_channel

[slack-event-member-left]: https://api.slack.com/events/member_left_channel

[step3]: /guides/collaborations/connect-slack-to-group-collabs/scaffold-application-code

[spring-initializr]: https://start.spring.io/


# Connect Bot to Box
Source: https://developer.box.com/guides/collaborations/connect-slack-to-group-collabs/connect-box-functions



<ProgressBar />

We're now handling and processing events coming from Slack, then obtaining all
information needed to connect with Box users and groups. We now need to
connect that functionality to Box functions.

In this step we'll expand several functions from the last step to incorporate
new Box features.

* Instantiate a Box client.
* Add a Box user to a Box group.
* Remove a Box user from a Box group.
* Fetch a Box group ID from a group name.
* Add content that is shared to a group.

## Instantiate a Box Client

To make calls to the Box APIs, you'll first need to set up a Box client.

<Choice>
  Within `process.js`, replace the `// INSTANTIATE BOX CLIENT` comment at the top
  with the following.

  ```js theme={null}
  const boxConfig = require("./boxConfig.json");
  const sdk = box.getPreconfiguredInstance(boxConfig);
  const client = sdk.getAppAuthClient("enterprise");
  ```

  The `boxConfig` assignment line will use the `boxConfig.json` file you
  downloaded from your Box app at the end of <Link href="/guides/collaborations/connect-slack-to-group-collabs/configure-box">step 2</Link>. The sample above is
  assuming that you have it stored in the same folder as `process.js`. If that's
  not the case, change the path to point to where your `boxConfig.json` file is,
  and what it may be named.

  The last `client` assignment line is creating a Box client object which may be
  used to make API calls. At this point it is scoped to the
  <Link href="/guides/getting-started/users#service-account/">service account</Link> of the application, and not a specific user.
</Choice>

<Choice>
  Within `Application.java`, replace the `// INSTANTIATE BOX CLIENT` comment
  within the `processEvent` method with the following.

  ```java theme={null}
  this.fileReader = new FileReader("boxConfig.json");
  this.boxConfig = BoxConfig.readFrom(fileReader);
  this.boxAPI = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig);
  ```

  The `boxConfig` assignment line will use the `boxConfig.json` file you
  downloaded from your Box app at the end of <Link href="/guides/collaborations/connect-slack-to-group-collabs/configure-box">step 2</Link>. The sample above is
  assuming that you have it stored at the root of the Java project. If that's
  not the case, change the path in the `fileReader` assignment to point to where
  your `boxConfig.json` file is, and what it may be named.

  The last `boxAPI` assignment line is creating a Box client object which may be
  used to make API calls. At this point it is scoped to the
  <Link href="/guides/getting-started/users#service-account/">service account</Link> of the application, and not a specific user.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Add a Box user to a group

Let's add a function that adds a Box user to a group. When a bot is added to a
channel and needs to create a Box group with all users of the channel, or when
a single user joins the channel after that action, this function will perform
that task.

<Choice>
  Replace the `addGroupUser` function with the following.

  ```js theme={null}
  function addGroupUser(groupId, email) {
      client.enterprise.getUsers({ filter_term: email }).then((users) => {
          if (users.entries.length > 0) {
              const userId = users.entries[0].id;
              const groupRole = client.groups.userRoles.MEMBER;

              client.groups
                  .addUser(groupId, userId, { role: groupRole })
                  .then((membership) => {
                      if (membership.id) {
                          console.log(`Member added with membership ID: ${membership.id}`);
                      } else {
                          console.log(`Member not added`);
                      }
                  })
                  .catch(function (err) {
                      console.log(err.response.body);
                  });
          } else {
              console.log("No Box user found to add to group");
          }
      });
  }
  ```
</Choice>

<Choice>
  Replace the `addGroupUser` method with the following.

  ```java theme={null}
  public void addGroupUser(String groupId, String userEmail) {
      Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(this.boxAPI, userEmail);

      for (BoxUser.Info user : users) {
          if (user.getLogin().toUpperCase().equals(userEmail.toUpperCase())) {
              try {
                  BoxGroup group = new BoxGroup(boxAPI, groupId);
                  BoxUser boxUser = new BoxUser(this.boxAPI, user.getID());
                  BoxGroupMembership.Info groupMembershipInfo = group.addMembership(boxUser);
              } catch (Exception ex) {
                  System.err.println("User already present");
              }
          }
      }
  }
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

Since we're matching a Slack user to a Box user via their email address, we
first find a matching Box user using the Slack profile email. If found, a call
is made to add that user to the channel group. The group was created when the
bot was first added.

<Tip>
  The Box <Link href="/reference/get-users-id">Get User</Link> endpoint only permits user lookup
  by user ID. To lookup a user by email address, use the
  <Link href="/reference/get-users">List Enterprise Users</Link> endpoint and set the
  `filter_term` option to the email address you're searching for.
</Tip>

## Remove a Box user from a group

When a user leaves or is removed from a Slack channel, we also want to remove
them from the Box group so that they can no longer access the shared group
content.

<Choice>
  Replace the `removeGroupUser` function with the following.

  ```js theme={null}
  function removeGroupUser(groupId, email) {
      client.groups.getMemberships(groupId).then(memberships => {
          for (let i = 0; i < memberships.entries.length; i++) {
              if (memberships.entries[i].user.login === email) {
                  client.groups
                  .removeMembership(memberships.entries[i].id)
                  .then(() => {
                      console.log('Group user removed')
                  });
                  break;
              }
          }
      });
  }
  ```
</Choice>

<Choice>
  Replace the `removeGroupUser` method with the following.

  ```java theme={null}
  public void removeGroupUser(String groupId, String userEmail) {
    BoxGroup boxGroup = new BoxGroup(this.boxAPI, groupId);
    Iterable<BoxGroupMembership.Info> memberships = boxGroup.getAllMemberships();
    for (BoxGroupMembership.Info membershipInfo : memberships) {
      if (membershipInfo.getUser().getLogin().toUpperCase().equals(userEmail.toUpperCase())) {
        BoxGroupMembership membership = new BoxGroupMembership(this.boxAPI, membershipInfo.getID());
        membership.delete();
      }
    }
  }
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

This code will take the group ID, which will be the Slack channel ID, and get
all members of the group. If a matching member is found for the person that
left the Slack channel, based on email address, that person is removed from the
group using their membership ID.

<Tip>
  **Improving performance with a data store**

  While looking up group memberships to obtain a membership ID negates the need
  to store membership IDs in a local data store (like a database), this code
  can be made more efficient by having a data store that saves the Box
  membership ID with the user record.

  By using a local data store, the membership ID can be retrieved from the data
  store rather than having to call the Box API repeatedly to search for the
  membership ID.
</Tip>

## Fetch a Box group ID for a group name

The next Box function we need has two main purposes.

* Return the Box group ID of an existing group.
* If a group doesn't exist, create the Box group and return the ID.

<Choice>
  Replace the `getGroupId` function with the following.

  ```js theme={null}
  function getGroupId(groupName, callback) {
      client.groups.getAll().then((groups) => {
          const group = groups.entries.filter((g) => g.name === groupName)[0];

          if (!group) {
              client.groups
                .create(groupName, {
                    description: "Slack channel collaboration group",
                    invitability_level: "all_managed_users",
                })
                .then((group) => {
                    callback(group.id);
                });
          } else {
              callback(group.id);
          }
      });
  }
  ```
</Choice>

<Choice>
  Replace the `getGroupId` method with the following.

  ```java theme={null}
  public String getGroupId(String groupName) {
      String groupId = new String();

      Iterable<BoxGroup.Info> groups = BoxGroup.getAllGroups(this.boxAPI);
      for (BoxGroup.Info groupInfo : groups) {
          if (groupInfo.getName().toUpperCase().equals(groupName)) {
              groupId = groupInfo.getID();
          }
      }

      if (groupId.isEmpty()) {
          BoxGroup.Info groupInfo = BoxGroup.createGroup(boxAPI, groupName);
          groupId = groupInfo.getID();
      }

      return groupId;
  }
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

The code fetches all the groups in the enterprise, and then tries to match the
Slack channel ID to the group name. If any of the groups matches, the group ID
is returned.

If there are no matches, a new Box group is created and the ID of the group is
returned for use. The group will be named after the Slack channel ID since that
is a constant that is returned with both slash commands and user events, making
it easier to lookup without additional functions.

## Add shared content to a group

Finally, the main purpose of our whole application is to allow users to share
files and folders from their own Box accounts with everyone else in the group.

Building upon all previous functionality, the following function performs that
task.

<Choice>
  Replace the `processContent` function with the following.

  ```js theme={null}
  function processContent(user, channel, itemType, itemId) {
      getGroupId(channel, function (groupId) {
          const email = user.profile.email;

          client.enterprise.getUsers({ filter_term: email }).then((users) => {
              if (users.entries.length > 0) {
                  client.asUser(users.entries[0].id);
                  const collabRole = client.collaborationRoles.VIEWER;
                  const collabOptions = { type: itemType };

                  client.collaborations
                      .createWithGroupID(groupId, itemId, collabRole, collabOptions)
                      .then((collaboration) => {
                          console.log(
                              `Content added with collaboration ID ${collaboration.id}`
                          );
                      })
                      .catch(function (err) {
                          console.log(
                            util.inspect(err.response.body, {
                                showHidden: false,
                                depth: null,
                            })
                          );
                      });
              }
          });
      });
  }
  ```
</Choice>

<Choice>
  Replace the `processContent` method with the following.

  ```java theme={null}
  public void processContent(JSONObject userResponse, String channel, String fType, String fId) {
      String groupId = getGroupId(channel);

      JSONObject userObj = (JSONObject) userResponse.get("user");
      JSONObject userProfile = (JSONObject) userObj.get("profile");
      String userEmail = (String) userProfile.get("email");

      Iterable<BoxUser.Info> users = BoxUser.getAllEnterpriseUsers(this.boxAPI, userEmail);

      for (BoxUser.Info user : users) {
          if (user.getLogin().toUpperCase().equals(userEmail.toUpperCase())) {
              String uid = user.getID();
              boxAPI.asUser(uid);

              BoxCollaborator collabGroup = new BoxGroup(boxAPI, groupId);

              try {
                  if (fType.equals("file")) {
                      BoxFile file = new BoxFile(boxAPI, fId);
                      file.collaborate(collabGroup, BoxCollaboration.Role.VIEWER, false, false);
                  } else if (fType.equals("folder")) {
                      BoxFolder folder = new BoxFolder(boxAPI, fId);
                      folder.collaborate(collabGroup, BoxCollaboration.Role.VIEWER);
                  }
              } catch (Exception ex) {
                  System.err.println("Collaboration failed");
              }

              boxAPI.asSelf();
          }
      }
  }
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

The code starts by capturing the Box group ID for the Slack channel, which
is where content will be shared to.

Since we want to share files and folders from the Box account of the person who
sent the slash command, we next capture their Box user profile based on their
email address.

Lastly, we make a call to collaborate content with the group via the group ID.

## Summary

* You've instantiated a Box client.
* You've created Box group user add and remove functions.
* You've created a function to share content with the group.

<Observe>
  <Next>I've set up my Box functions</Next>
</Observe>


# Handle Slack Events
Source: https://developer.box.com/guides/collaborations/connect-slack-to-group-collabs/handle-slack-events



<ProgressBar />

With the application scaffold in place, the next step is to build the handling
and processing functionality for user events, as well as the handling of slash
commands coming from Slack. Each one of these will eventually be passed to a
Box API endpoint to perform group and content collaboration tasks.

In this step we'll expand the empty functions we wrote in the last step. These
functions will perform the following tasks.

* Listen for new events and slash commands from Slack.
* Process those events and commands to route to the appropriate function.
* Process all Slack users in a channel to be added to a Box group when the bot is first added to a channel.
* Fetch profile information for a Slack user to get their email.

## Listen for Slack events

When the Slack application was configured, it was instructed to send events to
our application code for three events.

* When a user joins a channel.
* When a user leaves a channel.
* When a user enters a `/boxadd` Slash command.

Our application needs to have a public route that listens for those messages
from Slack. The payloads of these messages will look something like this.

<CodeGroup>
  ```json "/boxadd"-command theme={null}
  {
    "token": "cF1PwB1eIMcRHZWwFHJR1tgs",
    "team_id": "T932DQSV12P",
    "team_domain": "slacktest",
    "channel_id": "C078N43MFHU",
    "channel_name": "bottest",
    "user_id": "U016JCDPN56",
    "user_name": "testuser",
    "command": "/boxadd",
    "text": "file 123456",
    "response_url": "https://hooks.slack.com/commands/T541DQSV12P/3977594927231/ankvsRb42WKnKPRp002FeyTx",
    "trigger_id": "1189442196855.1183332180295.cca20c3ca1ea193dab432ad8e9e95431"
  }
  ```

  ```json "member_joined_channel"-event theme={null}
  {
    "token": "cF1PwB1eIMcRHZWwFHJR1tgs",
    "team_id": "T932DQSV12P",
    "api_app_id": "A321V573PQT",
    "event": {
      "type": "member_joined_channel",
      "user": "U0431JM4RLZ",
      "channel": "C078N43MFHU",
      "channel_type": "C",
      "team": "T932DQSV12P",
      "inviter": "U016JCDPN56",
      "event_ts": "1592858788.000700"
    },
    "type": "event_callback",
    "event_id": "Ev032NRJYASJ",
    "event_time": 1592858788,
    "authed_users": [ "U0431JM4RLZ" ]
  }
  ```

  ```json "member_left_channel"-event theme={null}
  {
    "token": "cF1PwB1eIMcRHZWwFHJR1tgs",
    "team_id": "T932DQSV12P",
    "api_app_id": "A321V573PQT",
    "event": {
      "type": "member_left_channel",
      "user": "U0431JM4RLZ",
      "channel": "C078N43MFHU",
      "channel_type": "C",
      "team": "T932DQSV12P",
      "event_ts": "1593033236.000600"
    },
    "type": "event_callback",
    "event_id": "Ev032NRJYASJ",
    "event_time": 1593033236,
    "authed_users": [ "U0431JM4RLZ" ]
  }
  ```
</CodeGroup>

<Choice>
  To start processing these events, load `process.js` in your preferred editor
  and replace the `app.post("/event" ...` listener with the following.

  ```js theme={null}
  app.post("/event", (req, res) => {
      if (req.body.token !== slackConfig.verificationToken) {
          res.send("Slack Verification Failed");
      }

      handler.process(res, req.body);
  });
  ```

  When an event comes through, the listener verifies that the message came from
  Slack, using the verification token from our Slack application. If it's a valid
  request, the event payload is sent to our event process function.
</Choice>

<Choice>
  Load `Application.java` in your preferred editor, then replace the
  `@PostMapping("/event")` block with the following.

  ```java theme={null}
  @PostMapping("/event")
  @ResponseBody
  public void handleEvent(@RequestBody String data, @RequestHeader("Content-Type") String contentType, HttpServletResponse response) throws Exception {
      int code = HttpServletResponse.SC_OK;
      java.io.PrintWriter wr = response.getWriter();
      response.setStatus(code);

      if (contentType.startsWith(MediaType.APPLICATION_JSON_VALUE)) {
          wr.write("Adding content to group");
      } else {
          wr.print(response);
      }

      wr.flush();
      wr.close();

      if (! contentType.startsWith(MediaType.APPLICATION_JSON_VALUE)) {
          JSONObject returnJSON = new JSONObject();
          String[] inputParts = data.split("&");

          for (String part: inputParts) {
              String[] keyval = part.split("=");

              try {
                  keyval[1] = java.net.URLDecoder.decode(keyval[1], StandardCharsets.UTF_8.name());
              } catch (UnsupportedEncodingException e) {
                  System.err.println(e);
              }

              returnJSON.put(keyval[0], keyval[1]);
          }

          data = returnJSON.toString();
      }

      processEvent(data);
  }
  ```

  When an event comes through, the handler will send an immediate 200 response
  back before code processing. Slash commands will be sent as URL encoded
  strings, while member join / leave events will be sent as JSON. If a slash
  command is encountered we respond with a processing message, otherwise we send
  the `HttpServletResponse` response.

  <Note>
    In this example we send an `HTTP 200` response before the event is fully
    processed. This is done because Slack requires a response to an event within
    3 seconds from dispatch. When the code execution takes longer than 3 seconds
    then a duplicate event will be dispatched by Slack.
  </Note>

  To make event processing easier, we want to standardize all event objects as
  JSON. If a content type isn't JSON it'll be the URL encoded string. If that's
  encountered the string is converted into a JSON object before being sent to
  `processEvent`.

  Replace `processEvent` with the following.

  ```java theme={null}
  @Async
  public void processEvent(String data) throws Exception {
      Object dataObj = new JSONParser().parse(data);
      JSONObject inputJSON = (JSONObject) dataObj;
      String token = (String) inputJSON.get("token");

      if (token.equals(slackConfig.verificationToken)) {
          // INSTANTIATE BOX CLIENT

          process(inputJSON);
      } else {
          System.err.println("Invalid event source");
      }
  }
  ```

  This method will convert the JSON event string to a JSON object, then verify
  that the event came from Slack by comparing the verification token. If valid,
  the event is routed to `process`.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Process Slack events

Next, we will want to determine what event was received and pass this on to the
right part of our application.

<Choice>
  Replace the `process` function with the following.

  ```js theme={null}
  function process(res, data) {
      if (data.type && data.type === "event_callback") {
          const eventType = data.event.type;
          const channel = data.event.channel;
          const userId = data.event.user;

          getSlackUser(userId, function (user) {
              processUser(user, eventType, channel);
          });

          res.send();
      } else if (data.command && data.command === "/boxadd") {
          const [itemType, itemId] = data.text.split(" ");
          if (["file", "folder"].includes(itemType) && !isNaN(itemId)) {
              const userId = data.user_id;

              getSlackUser(userId, function (user) {
                  processContent(user, data.channel_id, itemType, itemId);
              });
              res.send("Adding content");
          } else {
              res.send("Invalid input. Example usage: /boxadd file 123456");
          }
      } else {
          res.send("Invalid action");
      }
  }
  ```

  The purpose of this function is to figure out if the payload from Slack is a
  user event or a Slash command, fetch any needed information, then route to the
  appropriate function to process the results.

  If the payload is a user event, denoted by `data.type` being set to
  `event_callback`, we extract a few pieces of information.

  * `eventType`: The type of event to determine if a user is leaving (`member_left_channel`) or joining (`member_joined_channel`) the channel.
  * `channel`: The channel ID, which will be used as the Box group name.
  * `userId`: The ID of the user, to look up their profile email which will bind to a user profile in Box that uses the same email.

  The process function then fetches the profile of the user by calling
  `getSlackUser`, and once obtained that user profile is sent to the
  `processUser` function to add or remove them from the Box group.

  If the payload is a slash command, denoted by `data.command` being set to
  `/boxadd`, the content of the command that represents the Box ID and whether
  it's a file or folder, such as `file 1234`, is extracted and split to get the
  individual values. Those values are validated for proper content.

  Once validated, the profile of the Slack user is obtained to get the email,
  then the user profile is sent to `processContent` to collaborate the Box
  content with the Box group so that everyone has access.

  <Note>
    The reason for fetching the Slack user's email in this step is because the
    file or folder is owned by the user, not by the application's service
    account. When we share content (by creating a collaboration) the action will
    need to be performed by a user who has sharing permissions on that file or
    folder. For this reason, we need to match the Slack user's email address
    against a Box user's email address so that we can create the collaboration on
    their behalf.
  </Note>
</Choice>

<Choice>
  Replace the `process` method with the following.

  ```java theme={null}
  public void process(JSONObject inputJSON) throws Exception {
      if (inputJSON.containsKey("event")) {
          JSONObject event = (JSONObject) inputJSON.get("event");
          String eventType = (String) event.get("type");
          String eventUserId = (String) event.get("user");
          String eventChannel = (String) event.get("channel");

          processUser(getSlackUser(eventUserId), eventType, eventChannel);
      } else if (inputJSON.containsKey("command")) {
          String eventCommand = (String) inputJSON.get("command");
          if (eventCommand.equals("/boxadd")) {
              String eventChannelId = (String) inputJSON.get("channel_id");
              String eventUserId = (String) inputJSON.get("user_id");
              String cInput = (String) inputJSON.get("text");
              String[] cInputParts = cInput.split(" ");

              if (cInputParts[0].matches("file|folder")) {
                  processContent(getSlackUser(eventUserId), eventChannelId, cInputParts[0], cInputParts[1]);
              }
          }
      } else {
          System.err.println("Invalid event action");
      }
  }
  ```

  The purpose of this method is to figure out if the payload from Slack is a
  user event or a Slash command, fetch any needed information, then route to the
  appropriate method to process the results.

  If the payload is a user event, denoted by the event node being present in the
  JSON payload, we extract a few pieces of information.

  * `eventType`: The type of event to determine if a user is leaving (`member_left_channel`) or joining (`member_joined_channel`) the channel.
  * `eventUserId`: The ID of the user, to look up their profile email which will bind to a user profile in Box that uses the same email.
  * `eventChannel`: The channel ID, which will be used as the Box group name.

  We then route to `processUser`, passing in the return value
  from the `getSlackUser` method (a user object), the type of event, and the
  channel.

  If the payload is a slash command, denoted by the `command` node being present
  in the JSON payload, we extract a few pieces of information.

  * `eventChannelId`: The Slack channel ID, to be used as the Box group name.
  * `eventUserId`: The ID of the user who issued the command.
  * `cInputParts`: The type and ID of the command input, from a string such as `file 1234`.

  We then route to `processContent`, passing in the return value
  from the `getSlackUser` method (a user object), the channel ID, the content
  type (file or folder), and the content ID for the file or folder stored in Box.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Process Slack user

Next, we need to define how user events should be processed. There are three
events that we need to account for:

* The bot was added to the channel.
* A regular user joined the channel.
* A regular user left the channel.

<Choice>
  Replace the `processUser` function with the following.

  ```js theme={null}
  function processUser(user, event, channel) {
      getGroupId(channel, function (groupId) {
          // if bot was added, add all channel users
          if (user.is_bot) {
              processSlackChannel(channel, groupId);
          } else if (
              user.profile &&
              user.profile.email &&
              event === "member_joined_channel"
          ) {
              addGroupUser(groupId, user.profile.email);
          } else if (
              user.profile &&
              user.profile.email &&
              event === "member_left_channel"
          ) {
              removeGroupUser(groupId, user.profile.email);
          }
      });
  }
  ```
</Choice>

<Choice>
  Replace the `processUser` method with the following.

  ```java theme={null}
  public void processUser(JSONObject userResponse, String event, String channel) throws Exception {
      String groupId = getGroupId(channel);

      JSONObject userObj = (JSONObject) userResponse.get("user");

      Boolean isBot = (Boolean) userObj.get("is_bot");
      JSONObject userProfile = (JSONObject) userObj.get("profile");
      String userEmail = (String) userProfile.get("email");

      if (isBot) {
          processSlackChannel(channel, groupId);
      } else if (event.equals("member_joined_channel")) {
          addGroupUser(groupId, userEmail);
      } else if (event.equals("member_left_channel")) {
          removeGroupUser(groupId, userEmail);
      }
  }
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

The code starts by fetching the Box group ID for the channel, which will be
defined in the next step. Once obtained, it processes users as follows.

* If the user is a bot, it needs to initialize the Box group and add all current users of the channel as Box users in the group. This is to account for the bot being added to existing channels, and this is ignored if the bot is being re-added to a channel that they were already present in previously.
* If the user joined the channel it needs to add them to the group.
* If the user left the channel it needs to remove them from the group.

## Process Slack channel users

When a bot is first added to a channel, it needs to list all users
currently in the channel and create a Box group with those people in order to
create a baseline for the channel.

<Choice>
  Replace the `processSlackChannel` function with the following.

  ```js theme={null}
  function processSlackChannel(channel, groupId) {
      const limit = 100;
      const channelUsersPath = `https://slack.com/api/conversations.members?token=${slackConfig.botToken}&channel=${channel}&limit=${limit}`;

      axios.get(channelUsersPath).then((response) => {
          response.data.members.forEach((uid) => {
              getSlackUser(uid, function (user) {
                  if (user.profile.email && !user.is_bot) {
                      addGroupUser(groupId, user.profile.email);
                  }
              });
          });
      });
  }
  ```
</Choice>

<Choice>
  Replace the `processSlackChannel` method with the following.

  ```java theme={null}
  public void processSlackChannel(String channel, String groupId) throws Exception {
      String limit = "100";
      String channelUsersPath = String.format("%s/conversations.members?token=%s&channel=%s&limit=%s", slackConfig.slackApiUrl, slackConfig.botToken, channel, limit);

      JSONObject channelUserList = sendGETRequest(channelUsersPath);
      JSONArray channelUserIds = (JSONArray) channelUserList.get("members");

      @SuppressWarnings("rawtypes")
      Iterator i = channelUserIds.iterator();
      while(i.hasNext()) {
          String uid = (String)i.next();

          JSONObject userResponse = (JSONObject) getSlackUser(uid.toString());
          JSONObject userObj = (JSONObject) userResponse.get("user");
          JSONObject userProfile = (JSONObject) userObj.get("profile");
          Boolean isBot = (Boolean) userObj.get("is_bot");

          String userEmail = new String();
          if (!isBot) {
              userEmail = (String) userProfile.get("email");
          }

          if (!userEmail.isEmpty() && !isBot) {
              addGroupUser(groupId, userEmail);
          }
      }
  }
  ```
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

This code runs a number of actions in sequence.

* First, it calls the Slack APIs to fetch all members of the channel. The
  `limit` can be adjusted to collect more users in the channel.
* For every user that is found, it calls `getSlackUser` to get their profile, allowing it to map their email address to a Box user's email address.
* Each user is then sent to `addGroupUser` to add them into the group.

## Fetch Slack user profile

The last Slack related function is a utility mechanism used by the other
functions. It calls the Slack API to fetch the user profile
given the user ID provided by either Slack event / command or when fetching
a list of channel users. Since we're matching Slack users to Box users via
their email address, that is the field that we care about from the user profile
lookup.

<Note>
  Email addresses in Box are unique and cannot be used for multiple accounts,
  meaning that they can be used effectively for user account lookup.
</Note>

<Choice>
  Replace the `getSlackUser` function with the following.

  ```js theme={null}
  function getSlackUser(userId, callback) {
      const userPath = `https://slack.com/api/users.info?token=${slackConfig.botToken}&user=${userId}`;

      axios.get(userPath).then((response) => {
          if (response.data.user && response.data.user.profile) {
              callback(response.data.user);
          } else {
              console.log("No user data found");
          }
      });
  }
  ```

  This function makes a call to the Slack user profile endpoint, then sends the
  user profile information (if valid) to the specified callback.
</Choice>

<Choice>
  Replace the `getSlackUser` method with the following.

  ```java theme={null}
  public JSONObject getSlackUser(String userId) throws Exception {
      String usersPath = String.format("%s/users.info?token=%s&user=%s", slackConfig.slackApiUrl, slackConfig.botToken, userId);
      return sendGETRequest(usersPath);
  }
  ```

  This method sends a request to Slack to capture the user profile, then returns
  the response from that request, which should be a user profile JSON object.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Summary

* You've verified incoming events and forwarded them to be processed.
* You've processed events and routed to the appropriate function.
* You've implemented functions for processing all users in a channel and for fetching the Slack profile of a single user.

<Observe>
  <Next>I've set up my Slack functions</Next>
</Observe>


# Connect Slack to Box Group Collaborations
Source: https://developer.box.com/guides/collaborations/connect-slack-to-group-collabs/index



Slack is a popular communication and productivity tool, allowing for real-time
coordination when working with individuals or groups in and outside of the
company.

When connected to a custom Box application, the Slack channel structure, along
with the [slash command][slack-slash-commands] and [event API][slack-event-api]
systems, can be used to provide a logical grouping and collaboration system for
Box files and folders.

## Overview

This quick start guide will walk you through all the steps needed to group Box
users based on the channels they are in within a Slack workspace, and then
permit individuals within those Slack channels to share Box files and folders
with that group using a Slack slash command.

At the end of this tutorial you will have a Slack bot that will be deployed to a
channel in your workspace. This bot will create a Box group containing all the
people present in the channel, and then listen for a `/boxadd` command in the
channel. It will then parse that command and automatically collaborate the Box
file or folder with the entire group of users in the channel.

<Frame>
  <img alt="/boxadd command in Slack" />
</Frame>

This guide will take you through the following steps.

1. <Link href="/guides/collaborations/connect-slack-to-group-collabs/configure-slack">Setup and configure your Slack app</Link> to handle the event notification and Slash command structures.
2. <Link href="/guides/collaborations/connect-slack-to-group-collabs/configure-box">Setup and configure your Box application</Link> to connect the web application to Box.
3. <Link href="/guides/collaborations/connect-slack-to-group-collabs/scaffold-application-code">Listen for Slack events and commands</Link> when users join and leave channels, or share a Box file or folder with the group.
4. <Link href="/guides/collaborations/connect-slack-to-group-collabs/handle-slack-events">Structure Box groups and file / folder collaborations</Link> based on the Slack events or slash commands.
5. <Link href="/guides/collaborations/connect-slack-to-group-collabs/connect-box-functions">And finally, deploy the application to your workspace</Link> and invite the Slack app bot to your channels to begin listening for events.

## Requirements

This quick start guide has two requirements that are worth noting before we proceed.

1. **User emails need to match between Box and Slack**: We are connecting a Slack user account to a Box user account by comparing the Slack user email address. Therefore, a matching Box user account using the same email address must be present in your Box enterprise.
2. **You must have a publicly accessible server**: Slack will need to send event and command notification data to a public URL for your application. This guide assumes that you have a public location where your application code will be hosted, such as `https://mysite.com/`. If you don't have access to any public hosting then application platforms like [Heroku][heroku], serverless options like [AWS lambda][aws-lambda], or exposing localhost with services like [ngrok][ngrok] are all options that you might want to consider.

<Next>
  I am ready to get started
</Next>

[slack-slash-commands]: https://api.slack.com/interactivity/slash-commands

[slack-event-api]: https://api.slack.com/events-api

[step6]: /guides/collaborations/connect-slack-to-group-collabs/test-bot

[heroku]: https://heroku.com/

[aws-lambda]: https://aws.amazon.com/lambda/

[ngrok]: https://ngrok.com/


# Scaffold application code (Slack integration)
Source: https://developer.box.com/guides/collaborations/connect-slack-to-group-collabs/scaffold-application-code



<ProgressBar />

With our Slack and Box applications configured, we're ready to write the code
for our application which will listen for incoming slash commands and events
from Slack.

This application will be split up into three parts:

* Set up the initial application skeleton and configuration information.
* Set up the handlers for Slack events and slash commands.
* Connect those handlers to the required functions in Box.

## Add dependencies and scaffold code

Let's start by scaffolding the files and minimal code needed to
run the application.

<Choice>
  * Either create a new local directory for your application or load the existing code created for the Slack event URL challenge from <Link href="/guides/collaborations/connect-slack-to-group-collabs/configure-slack">step 1</Link>.
  * Create a new `package.json` file, or update the existing one, inside the local directory, open it in your preferred editor, copy / paste the following into it, and save / exit the file.

  ```json theme={null}
  {
    "name": "box-slack",
    "version": "1.0.0",
    "description": "Box Slack integration",
    "main": "process.js",
    "scripts": {
      "test": "echo \"Error: no test specified\" && exit 1",
      "start": "node process.js"
    },
    "author": "Box",
    "license": "ISC",
    "dependencies": {
      "axios": "^0.19.2",
      "body-parser": "^1.19.0",
      "box-node-sdk": "^1.33.0",
      "express": "^4.17.1"
    }
  }
  ```

  * Run `npm install` from the terminal / console to install the dependencies.
  * Create two files, `process.js` and `slackConfig.json` in the local directory.
  * Open `slackConfig.json` and save the following default configuration.

  ```json theme={null}
  {
    "verificationToken": "TOKEN",
    "botToken": "TOKEN"
  }
  ```

  * There are two values above that will need to be replaced with details from your Slack application. Replace the `TOKEN` strings with the appropriate values.
    * `verificationToken`: Load up your Slack application configuration page. Within the **Basic Information** page, scroll down to the **App Credentials** section. The **Verification Token** string will be available there.
    * `botToken`: Within your Slack application, go to the **OAuth & Permissions** page. The **Bot User OAuth Access Token** string is available at the top and was auto-populated once the bot was added to your Slack workspace.
  * Open up the blank `process.js` file, copy and paste the following code, and save the file.

  ```js theme={null}
  const box = require("box-node-sdk");

  const slackConfig = require("./slackConfig.json");
  const boxConfig = require("./boxConfig.json");

  const express = require("express");
  const app = express();
  const axios = require("axios");
  const util = require("util");

  app.use(express.urlencoded({ extended: true }));
  app.use(express.json());

  // INSTANTIATE BOX CLIENT

  app.post('/event', (req, res) => {
      //HANDLE INCOMING EVENTS
  });

  const handler = (() => {
      function process(res, data) {
          // PROCESS EVENTS
      }

      function processUser(user, event, channel) {
          // PROCESS USER ADD / REMOVE REQUEST
      }

      function addGroupUser(groupId, email) {
          // ADD USER TO BOX GROUP
      }

      function removeGroupUser(groupId, email) {
          // REMOVE USER FROM BOX GROUP
      }

      function processContent(user, channel, type, fid) {
          // COLLABORATE CONTENT WITH GROUP
      }

      function processSlackChannel(channel, gid) {
          // ADD ALL SLACK CHANNEL USERS TO GROUP
      }

      function getSlackUser(userId, _callback) {
          // GET SLACK USER PROFILE
      }

      function getGroupId(groupName, _callback) {
          // GET AND CREATE BOX GROUP
      }

      return {
          process
      };
  })();

  const port = process.env.PORT || 3000;
  app.listen(port, function(err) {
    console.log("Server listening on PORT", port);
  });
  ```

  This code contains all of the main functions that will be needed to handle and
  process the communication between Slack and Box. From top to bottom, the
  functions are:

  * `/event` handler: Captures all incoming Slack traffic, verifies the content, and routes them to the `process` function.
  * `process`: Parses the Slack event and routes the event to either Box group processing (user channel events) or to add Box content to the group (slash commands).
  * `processUser`: Handles user events, either adding or removing a user from a Box group by routing to the appropriate functions.
  * `addGroupUser`: Adds a user to a Box group.
  * `removeGroupUser`: Removes a user from a Box group.
  * `processContent`: Collaborates Box content with the Box group.
  * `processSlackChannel`: Adds all Slack channel users to a Box group.
  * `getSlackUser`: Utility function to fetch a Slack user's profile from their Slack user ID.
  * `getGroupId`: Utility function to fetch a Box group ID from a Box group name.
</Choice>

<Choice>
  A configuration file needs to be created to house our Slack credentials and
  URLs.

  * Within your `src/main/java` path, where your `Application.java` file is located, create a new Java class file named `slackConfig.java`.
  * Open the file and save the following into it.

  ```java theme={null}
  package com.box.slack.box;

  public class slackConfig {
      public static String verificationToken = "TOKEN";
      public static String botToken = "TOKEN";
      public static String slackApiUrl = "https://slack.com/api";
  }
  ```

  * There are two values above that will need to be replaced with details from your Slack application. Replace the `TOKEN` strings with the appropriate values.
    * `verificationToken`: Load up your Slack application configuration page. Within the **Basic Information** page, scroll down to the **App Credentials** section. The **Verification Token** string will be available there.
    * `botToken`: Within your Slack application, go to the **OAuth & Permissions** page. The **Bot User OAuth Access Token** string is available at the top and was auto-populated once the bot was added to your Slack workspace.
  * Open up the `Application.java` file that was created for the previous Slack event challenge setup and replace the content of the file with the following.

  ```java theme={null}
  package com.box.slack.box;

  import java.io.BufferedReader;
  import java.io.FileReader;
  import java.io.InputStreamReader;
  import java.io.Reader;
  import java.io.UnsupportedEncodingException;
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.nio.charset.StandardCharsets;
  import java.util.Iterator;

  import javax.servlet.http.HttpServletResponse;

  import org.jose4j.json.internal.json_simple.JSONArray;
  import org.jose4j.json.internal.json_simple.JSONObject;
  import org.jose4j.json.internal.json_simple.parser.JSONParser;
  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
  import org.springframework.http.MediaType;
  import org.springframework.scheduling.annotation.Async;
  import org.springframework.web.bind.annotation.PostMapping;
  import org.springframework.web.bind.annotation.RequestBody;
  import org.springframework.web.bind.annotation.RequestHeader;
  import org.springframework.web.bind.annotation.ResponseBody;
  import org.springframework.web.bind.annotation.RestController;

  import com.box.sdk.BoxAPIConnection;
  import com.box.sdk.BoxCollaborator;
  import com.box.sdk.BoxCollaboration;
  import com.box.sdk.BoxConfig;
  import com.box.sdk.BoxDeveloperEditionAPIConnection;
  import com.box.sdk.BoxFile;
  import com.box.sdk.BoxFolder;
  import com.box.sdk.BoxGroup;
  import com.box.sdk.BoxGroupMembership;
  import com.box.sdk.BoxUser;

  @RestController
  @EnableAutoConfiguration
  public class Application extends slackConfig {
      private Reader fileReader;
      private BoxConfig boxConfig;
      private BoxAPIConnection boxAPI;

      @PostMapping("/event")
      @ResponseBody
      public void handleEvent(@RequestBody String data, @RequestHeader("Content-Type") String contentType, HttpServletResponse response) throws Exception {
          // HANDLE EVENTS
      }

      @Async
      public void processEvent(String data) throws Exception {
          // VERIFY EVENTS
      }

      public void process(JSONObject inputJSON) throws Exception {
          // PROCESS EVENTS
      }

      public void processUser(JSONObject userResponse, String event, String channel) throws Exception {
          // PROCESS USER ADD / REMOVE REQUEST
      }

      public void addGroupUser(String groupId, String userEmail) {
          // ADD USER TO BOX GROUP
      }

      public void removeGroupUser(String groupId, String userEmail) {
          // REMOVE USER FROM BOX GROUP
      }

      public void processContent(JSONObject userResponse, String channel, String fType, String fId) {
          // COLLABORATE CONTENT WITH GROUP
      }

      public void processSlackChannel(String channel, String groupId) throws Exception {
          // ADD ALL SLACK CHANNEL USERS TO GROUP
      }

      public JSONObject getSlackUser(String userId) throws Exception {
          // GET SLACK USER PROFILE
      }

      public String getGroupId(String groupName) {
          // GET AND CREATE BOX GROUP
      }

      public JSONObject sendGETRequest(String reqURL) throws Exception {
          StringBuffer response = new StringBuffer();

          URL obj = new URL(reqURL);
          HttpURLConnection httpURLConnection = (HttpURLConnection) obj.openConnection();
          httpURLConnection.setRequestMethod("GET");

          int responseCode = httpURLConnection.getResponseCode();
          if (responseCode == HttpURLConnection.HTTP_OK) {
              BufferedReader in = new BufferedReader(new InputStreamReader(httpURLConnection.getInputStream()));
              String inputLine;

              while ((inputLine = in .readLine()) != null) {
                  response.append(inputLine);
              } in .close();
          } else {
              System.err.println("GET request failed");
          }

          Object dataObj = new JSONParser().parse(response.toString());
          JSONObject outputJSON = (JSONObject) dataObj;

          return outputJSON;
      }

      public static void main(String[] args) {
          SpringApplication.run(Application.class, args);
      }
  }
  ```

  This code contains all of the main functions that will be needed to handle and
  process the communication between Slack and Box. From top to bottom, the
  functions are:

  * `handleEvent`: Captures all incoming Slack traffic and responds with an HTTP 200 response to notify Slack that the event was received. Since slash commands will transmit their payload as `application/x-www-form-urlencoded` rather than `application/json`, we convert those payloads to JSON objects to standardize the input.
  * `processEvent`: Verifies that the event is from Slack, instantiates a Box client, and routes for processing.
  * `process`: Parses the Slack event and routes to either Box group processing (user channel events) or to add Box content to the group (slash commands).
  * `processUser`: Handles user event requirements to either add or remove a user to a Box group by routing to the appropriate functions.
  * `addGroupUser`: Adds a user to a Box group.
  * `removeGroupUser`: Removes a user from a Box group.
  * `processContent`: Collaborates Box content with the Box group.
  * `processSlackChannel`: Adds all Slack channel users to a Box group.
  * `getSlackUser`: Utility function to fetch a Slack user profile from a Slack user ID.
  * `getGroupId`: Utility function to fetch a Box group ID from a Box group name.
  * `sendGETRequest`: Utility function to send an HTTP GET request.
</Choice>

<Choice>
  <Danger>
    **Incomplete previous step**
    Please select a preferred language / framework in step 1 to get started.
  </Danger>
</Choice>

## Summary

* You created a minimal application scaffold, and provided the basic configuration details.
* You installed all the project dependencies.

<Observe>
  <Next>I have my local application set up</Next>
</Observe>


# Test the bot
Source: https://developer.box.com/guides/collaborations/connect-slack-to-group-collabs/test-bot



<ProgressBar />

In this last section we'll test the full range of functionality of the Slack
bot.

* **Group creation**: When a bot is added to a channel, a new Box group should be created with all of the current channel participants. Only those people in the channel with matching Box accounts (based on email address matching) should be added.
* **User event functions**: When a user enters or leaves a channel, they should be added or removed from the channel group.
* **Content add functions**: When a user enters a valid `/boxadd` slash command, that content should be shared with the group through a new collaboration.

<Note>
  If you haven't done so already, ensure that all the code we've written so far
  is deployed as an application that is publicly accessible.
</Note>

## Testing group creation

When a bot is first added to a channel, there are a number of expectations.

* A new group is created with a name that matches the Slack channel ID.
* All people currently in the channel are added to the group, as long as their Slack email address matches an enterprise account with the same email.

When the Slack bot was configured in <Link href="/guides/collaborations/connect-slack-to-group-collabs/configure-slack">step 1</Link>, we installed it within
the Slack workspace. To test group creation we need to add it to a channel.

From any Slack channel, invite the Slack bot, either through the Slack UI or
using a `/invite @bot_app_name` command.

Once added, verify that the group is created in Box and members have been
added. From a Box enterprise admin account, go to the
**[Users and Groups][box-users-groups]** section of the admin console. If
successful, you will see a group with a random alpha-numeric string as the
group name. This is the Slack channel ID, which is mirrored in the group name.

<Frame>
  <img alt="View Box Groups" />
</Frame>

Under the **Members** column, you should also see a number indicating the
number of Box users with matching email addresses that were found in the
enterprise and added to the group during group creation.

If you see your group and members, this step is a success.

<Note>
  If you see no members added to the group, and no errors being returned from
  the bot application, the most likely cause is email mismatch. Ensure that the
  email addresses used by the accounts in Slack match the emails used by users
  in your Box enterprise.
</Note>

## Testing user event functions

Keep the **[Users and Groups][box-users-groups]** section of the Box admin
console open and take note of the number in the **Members** column beside your
Slack group.

From the Slack channel with the bot invited, add or remove someone other than
the bot from the channel.

Refresh the users and groups section of the Box admin console and you should
see the members number drop or increase depending on if you added or removed a
user.

If the number of members changes, this step is a success.

## Testing content add functions

To test the functionality of sharing content with the group, you will need
access to two users in the channel, one person to share the content from their
Box account, and another person in the group to view their list of files to
verify that the content was shared.

From the Slack channel with the bot invited, type in the slash command to share
files or folders with the group, in the format of
`/boxadd [file/folder] [ID of file/folder]`, such as
`/boxadd folder 324554221`.

<Note>
  The file or folder ID specified needs to be content within the Box account of
  the person sharing it.
</Note>

To find the ID of a file or folder in a Box account, load up the file or folder
within [the Box site][box], then look at the URL. The ID will be the
last string in the URL, often right after a section which includes either
`/file/` or `/folder/`.

<Frame>
  <img alt="Get File or Folder ID" />
</Frame>

Once the command is typed in, go to [the Box site][box] account
of another person within the Slack channel and Box group. The content that was
shared should now be available to that account.

If the shared content is available to others in the group, this step is a
success.

## Next Steps

With our minimal bot deployed we can now think about ways to improve the
experience on top of what we've created so far. Next steps in this
journey may include any number of different expansion areas.

* Add new slash commands for <Link href="/guides/shared-links/create-or-update">creating shared links</Link> for the files and folders shared with the group, allowing you to share the content with others who are not in the group and people outside your enterprise.
* <Link href="/reference/post-retention-policies">Creating retention policies</Link> and <Link href="/reference/post-retention-policy-assignments">assigning them</Link> to any content shared with the group, allowing you to control the lifespan and governance of shared content.
* Adding new slash commands for allowing people in the channel to <Link href="/reference/post-comments">comment on the files</Link> that are shared with the group.

[box-users-groups]: https://app.box.com/master/groups

[box]: https://box.com


# Sharing with Groups
Source: https://developer.box.com/guides/collaborations/groups



To share a file or folder with a group of users, create a collaboration using
the group ID, the ID of the file or folder, and the role or permissions level
the group should have when accessing the file or folder.

<Info>
  The collaboration roles are `editor`, `viewer`, `previewer`, `uploader`,
  `previewer uploader`, `viewer uploader`, `co-owner`, or `owner`. For a full
  description of each role, please refer to our [support documentation].
</Info>

## Nested objects

When creating a collaboration there are two nested objects within the request
body: `accessible_by` and `item`.

The `accessible_by` object specifies who the item should be shared with and
includes a group `id` and the `type`. The `type` field should always be set to
`group`.

The `item` object specifies what is being shared. It includes a `type` field
which should be set as `file` or `folder`, and an `id` for that file or folder.

[support documentation]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels


# Collaborations
Source: https://developer.box.com/guides/collaborations/index

Grant users and groups role-based access to files and folders, manage pending invitations, and apply collaboration domain restrictions.

Collaborations define access permissions for users and groups on files and folders, similar to access control lists. A collaboration object grants a user or group access to a file or folder with permissions defined by a specific role.

Use the guides in this section when you need to invite collaborators, share with groups, handle pending invitations, or manage enterprise collaboration domain restrictions through the API.

## How collaborations work

When you create a collaboration, you specify three things:

1. **Item** — The file or folder being shared (`type` of `file` or `folder`, plus its `id`).
2. **Accessible by** — Who receives access: a `user` (by ID or email login) or a `group` (by ID).
3. **Role** — The permission level granted to that user or group.

Box applies the same permission model through the API as in the Box web app. You cannot bypass content permissions or the [waterfall folder structure][waterfall] by using the API. Access tokens only succeed against content the authenticated user owns or is a collaborator on — see the <Link href="/guides/security">security overview</Link>.

Collaborations are distinct from <Link href="/guides/shared-links/index">shared links</Link>. Shared links provide URL-based access to an item. Collaborations grant role-based access to a specific user or group and appear in the item's collaborator list.

## Roles

The collaboration roles are `editor`, `viewer`, `previewer`, `uploader`, `previewer uploader`, `viewer uploader`, `co-owner`, and `owner`.

For a full description of each role, see the [collaborator permission levels][support documentation] support article.

## Collaboration status

A collaboration invitation can be in one of these states:

| Status | Meaning |
| - | - |
| `pending` | The invitee has not accepted yet |
| `accepted` | The collaborator has access |
| `rejected` | The invitee declined the invitation |

You can list pending invitations for the current user with <Link href="/guides/collaborations/pending">`GET /collaborations?status=pending`</Link>.

## Users and groups

* **Users** — Share with a managed or external user by user ID or email. See <Link href="/guides/collaborations/share-content">Share content with a user</Link>.
* **Groups** — Share once with a Box group so every group member inherits the same role. See <Link href="/guides/collaborations/groups">Sharing with groups</Link>.

You can also build integrations that create Box groups from external systems and collaborate those groups on folders — for example, the <Link href="/guides/collaborations/connect-slack-to-group-collabs/index">Slack group collaborations</Link> tutorial.

## Enterprise domain restrictions

Admins can limit who can be invited as collaborators by allowing only specific email domains. Applications with the right permissions can add, list, and delete those allowed domains programmatically. See <Link href="/guides/collaborations/allowed-domains/index">Allowed collaboration domains</Link>.

## Quick example

Invite a user as an editor on a folder:

```bash theme={null}
curl -X POST https://api.box.com/2.0/collaborations \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "item": { "type": "folder", "id": "FOLDER_ID" },
    "accessible_by": { "type": "user", "login": "user@example.com" },
    "role": "editor"
  }'
```

## Guides in this section

<CardGroup>
  <Card title="Share content with a user" icon="user-plus" href={localizeLink("/guides/collaborations/share-content")}>
    Create a collaboration on a file or folder for a user by ID or email.
  </Card>

  <Card title="Sharing with groups" icon="users" href={localizeLink("/guides/collaborations/groups")}>
    Grant the same role to every member of a Box group in one collaboration.
  </Card>

  <Card title="Pending collaborations" icon="clock" href={localizeLink("/guides/collaborations/pending")}>
    List invitations the current user has not accepted yet.
  </Card>

  <Card title="Allowed collaboration domains" icon="globe" href={localizeLink("/guides/collaborations/allowed-domains/index")}>
    Manage enterprise allow-lists that restrict which email domains can collaborate.
  </Card>

  <Card title="Connect Slack to group collaborations" icon="slack" href={localizeLink("/guides/collaborations/connect-slack-to-group-collabs/index")}>
    Sync Slack channels to Box groups and share files with the channel in one command.
  </Card>
</CardGroup>

[support documentation]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels

[waterfall]: https://support.box.com/hc/en-us/articles/360043697254-Understanding-Folder-Permissions


# Get Pending Collaborations
Source: https://developer.box.com/guides/collaborations/pending



To get the pending collaborations for a user, call the `GET /collaborations` API
with a `status` of `pending`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/collaborations?status=pending" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.listCollaborations.getCollaborations({
    status: 'pending' as GetCollaborationsQueryParamsStatusField,
  } satisfies GetCollaborationsQueryParams);
  ```

  ```python Python v10 theme={null}
  client.list_collaborations.get_collaborations(GetCollaborationsStatus.PENDING)
  ```

  ```cs .NET v10 theme={null}
  await client.ListCollaborations.GetCollaborationsAsync(queryParams: new GetCollaborationsQueryParams(status: GetCollaborationsQueryParamsStatusField.Pending));
  ```

  ```swift Swift v10 theme={null}
  try await client.listCollaborations.getCollaborations(queryParams: GetCollaborationsQueryParams(status: GetCollaborationsQueryParamsStatusField.pending))
  ```

  ```java Java v10 theme={null}
  client.getListCollaborations().getCollaborations(new GetCollaborationsQueryParams(GetCollaborationsQueryParamsStatusField.PENDING))
  ```

  ```java Java v5 theme={null}
  Collection<BoxCollaboration.Info> pendingCollaborations =
      BoxCollaboration.getPendingCollaborations(api);
  ```

  ```python Python v4 theme={null}
  pending_collaborations = client.get_pending_collaborations()
  for pending_collaboration in pending_collaborations:
      print(f'Collaboration {pending_collaboration.id} is pending')
  ```

  ```cs .NET v6 theme={null}
  BoxCollection<BoxCollaboration> pendingCollabs = await CollaborationsManager
      .GetPendingCollaborationAsync();
  ```

  ```javascript Node v4 theme={null}
  client.collaborations.getPending()
  	.then(collaborations => {
  		/* collaborations -> {
  			total_count: 1,
  			entries: [
  				{
  					type: 'collaboration',
  					id: '11111',
  					created_by: {
  						type: 'user',
  						id: '22222',
  						name: 'Example User',
  						login: 'user@example.com'
  					},
  					created_at: '2011-11-29T12:56:35-08:00',
  					modified_at: '2012-09-11T15:12:32-07:00',
  					expires_at: null,
  					status: 'pending',
  					accessible_by: {
  						type: 'user',
  						id: '33333',
  						name: 'Collaborator User',
  						login: 'collaborator@example.com'
  					},
  					role: 'editor',
  					acknowledged_at: '2011-11-29T12:59:40-08:00',
  					item: null
  				}
  			]
  		}
  		*/
  	});
  ```
</CodeGroup>

<Warning>
  This only returns the current list of pending collaborations for a user. This
  API does not allow for returning all collaborations for a user.
</Warning>


# Share Content with User
Source: https://developer.box.com/guides/collaborations/share-content



To share content with a user, create a collaboration using
the user ID or email
address, the ID of the content, and the role or
permissions level the user
should have when accessing the content.
The collaboration roles
are `editor`, `viewer`, `previewer`, `uploader`,
`previewer uploader`,
`viewer uploader`, `co-owner`,
or `owner`. For a full description of each role,
please refer to our [support documentation].

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/collaborations" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "item": {
           "type": "file",
           "id": "11446498"
         },
         "accessible_by": {
           "type": "user",
           "login": "user@example.com"
         },
         "role": "editor"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.userCollaborations.createCollaboration({
    item: {
      type: 'folder' as CreateCollaborationRequestBodyItemTypeField,
      id: folder.id,
    } satisfies CreateCollaborationRequestBodyItemField,
    accessibleBy: {
      type: 'user' as CreateCollaborationRequestBodyAccessibleByTypeField,
      id: user.id,
    } satisfies CreateCollaborationRequestBodyAccessibleByField,
    role: 'editor' as CreateCollaborationRequestBodyRoleField,
  } satisfies CreateCollaborationRequestBody);
  ```

  ```python Python v10 theme={null}
  client.user_collaborations.create_collaboration(
      CreateCollaborationItem(type=CreateCollaborationItemTypeField.FOLDER, id=folder.id),
      CreateCollaborationAccessibleBy(
          type=CreateCollaborationAccessibleByTypeField.USER, id=user.id
      ),
      CreateCollaborationRole.EDITOR,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.UserCollaborations.CreateCollaborationAsync(requestBody: new CreateCollaborationRequestBody(item: new CreateCollaborationRequestBodyItemField() { Type = CreateCollaborationRequestBodyItemTypeField.Folder, Id = folder.Id }, accessibleBy: new CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.User) { Id = user.Id }, role: CreateCollaborationRequestBodyRoleField.Editor));
  ```

  ```swift Swift v10 theme={null}
  try await client.userCollaborations.createCollaboration(requestBody: CreateCollaborationRequestBody(item: CreateCollaborationRequestBodyItemField(type: CreateCollaborationRequestBodyItemTypeField.folder, id: folder.id), accessibleBy: CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.user, id: user.id), role: CreateCollaborationRequestBodyRoleField.editor))
  ```

  ```java Java v10 theme={null}
  client.getUserCollaborations().createCollaboration(new CreateCollaborationRequestBody(new CreateCollaborationRequestBodyItemField.Builder().type(CreateCollaborationRequestBodyItemTypeField.FOLDER).id(folder.getId()).build(), new CreateCollaborationRequestBodyAccessibleByField.Builder(CreateCollaborationRequestBodyAccessibleByTypeField.USER).id(user.getId()).build(), CreateCollaborationRequestBodyRoleField.EDITOR))
  ```

  ```java Java v5 theme={null}
  BoxCollaborator user = new BoxUser(api, "user-id")
  BoxFolder folder = new BoxFolder(api, "folder-id");
  folder.collaborate(user, BoxCollaboration.Role.EDITOR);
  ```

  ```python Python v4 theme={null}
  from boxsdk.object.collaboration import CollaborationRole

  user = client.user(user_id='11111')
  collaboration = client.folder(folder_id='22222').collaborate(user, CollaborationRole.VIEWER)

  collaborator = collaboration.accessible_by
  item = collaboration.item
  has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
  print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')
  ```

  ```cs .NET v6 theme={null}
  // collaborate folder 11111 with user 22222
  BoxCollaborationRequest requestParams = new BoxCollaborationRequest()
  {
      Item = new BoxRequestEntity()
      {
          Type = BoxType.folder,
          Id = "11111"
      },
      Role = "editor",
      AccessibleBy = new BoxCollaborationUserRequest()
      {
          Type = BoxType.user,
          Id = "22222"
      }
  };
  BoxCollaboration collab = await client.CollaborationsManager.AddCollaborationAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  // Invite user 123456 to collaborate on folder 987654
  client.collaborations.createWithUserID('123456', '987654', client.collaborationRoles.EDITOR)
  	.then(collaboration => {
  		/* collaboration -> {
  			type: 'collaboration',
  			id: '11111',
  			created_by: 
  			{ type: 'user',
  				id: '22222',
  				name: 'Inviting User',
  				login: 'inviter@example.com' },
  			created_at: '2016-11-16T21:33:31-08:00',
  			modified_at: '2016-11-16T21:33:31-08:00',
  			expires_at: null,
  			status: 'accepted',
  			accessible_by: 
  			{ type: 'user',
  				id: '123456',
  				name: 'Collaborator User',
  				login: 'collaborator@example.com' },
  			role: 'editor',
  			acknowledged_at: '2016-11-16T21:33:31-08:00',
  			item: 
  			{ type: 'folder',
  				id: '987654',
  				sequence_id: '0',
  				etag: '0',
  				name: 'Collaborated Folder' } }
  		*/
  	});
  ```
</CodeGroup>

## Nested objects

When creating a collaboration there are two nested objects within the request
body: `accessible_by` and `item`.

The `accessible_by` object specifies who the item should be shared with and
includes a user `id` and the `type`. The `type` field should always be set to
`user`.

The `item` object specifies what is being shared. It includes a `type` field
which should be set as `file` and an `id` for that file.

[support documentation]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels


# Add Item to Collection
Source: https://developer.box.com/guides/collections/add



To add an item to a collection, call the `PUT` endpoint for that specific type of
item and pass along a list of collection IDs.

<Warning>
  The only collection that is available via the API is the "Favorites"
  collection. The ID of this collection is [different for every
  user](/guides/collections/list).
</Warning>

## Add file to collection

To add a file to a collection, call the `PUT /files/:id` API and pass along a
list of collection IDs.

## Add folder to collection

To add a folder to a collection, call the `PUT /folders/:id` API and pass along
a list of collection IDs.

## Add web link to collection

To add a web link to a collection, call the `PUT /web_links/:id` API and pass
along a list of collection IDs.

<RelatedLinks title="RELATED APIS" />


# Collections overview
Source: https://developer.box.com/guides/collections/index



Collections in Box are a way to group files, folders, and web links without
putting them all into a folder together.

<Warning>
  The only collection that is available via the API is the "Favorites"
  collection. The ID of this collection is [different for every
  user](/guides/collections/list).
</Warning>


# List User's Collections
Source: https://developer.box.com/guides/collections/list



To list all collections for a user, call the [`GET
/collections`](/reference/get-collections) API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/collections" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.collections.getCollections();
  ```

  ```python Python v10 theme={null}
  client.collections.get_collections()
  ```

  ```cs .NET v10 theme={null}
  await client.Collections.GetCollectionsAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.collections.getCollections()
  ```

  ```java Java v5 theme={null}
  Iterable<BoxCollection.Info> collections = BoxCollection.getAllCollections(api);
  for (BoxCollection.Info collectionInfo : collections) {
  	// Do something with the collection.
  }
  ```

  ```python Python v4 theme={null}
  collections = client.collections()
  for collection in collections:
      print(f'Collection "{collection.name}" has ID {collection.id}')
  ```

  ```cs .NET v6 theme={null}
  BoxCollection<BoxCollectionItem> collections = await client.CollectionsManager.GetCollectionsAsync();
  ```

  ```javascript Node v4 theme={null}
  client.collections.getAll()
  	.then(collections => {
  		/* collections -> { total_count: 1,
  			entries: 
  			[ { type: 'collection',
  				id: '11111',
  				name: 'Favorites',
  				collection_type: 'favorites' } ],
  			limit: 100,
  			offset: 0 }
  		*/
  	});
  ```
</CodeGroup>

<Warning>
  The only collection that is available via the API is the "Favorites"
  collection. The ID of this collection is different for every
  user.
</Warning>

## Favorites Collection

The only collection that items can currently be added and removed to via the
API is the "Favorites" collection.

The ID of the favorites collection is different for every user. To find the
user's collection ID for their favorites, list all the user's collections and
then find the collection with a `collection_type` of `favorites`.

```json theme={null}
{
  "entries": [
    {
      "collection_type": "favorites",
      "id": "12345678",
      "name": "Favorites",
      "type": "collection"
    }
  ],
  "limit": 100,
  "offset": 0,
  "total_count": 1
}
```

<RelatedLinks title="RELATED APIS" />


# List Items in Collections
Source: https://developer.box.com/guides/collections/list-items



To list all files, folders and web links in a folder call the [`GET
/collections/:id/items`](/reference/get-collections-id-items) API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/collections/926489/items" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.collections.getCollectionItems(favouriteCollection.id!);
  ```

  ```python Python v10 theme={null}
  client.collections.get_collection_items(favourite_collection.id)
  ```

  ```cs .NET v10 theme={null}
  await client.Collections.GetCollectionItemsAsync(collectionId: NullableUtils.Unwrap(favouriteCollection.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.collections.getCollectionItems(collectionId: favouriteCollection.id!)
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, "id");
  for (BoxItem.Info itemInfo : folder) {
      if (itemInfo instanceof BoxFile.Info) {
          BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
          // Do something with the file.
      } else if (itemInfo instanceof BoxFolder.Info) {
          BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo;
          // Do something with the folder.
      }
  }
  ```

  ```python Python v4 theme={null}
  items = client.collection(collection_id='12345').get_items()
  for item in items:
      print(f'{item.type.capitalize()} "{item.name}" is in the collection')
  ```

  ```cs .NET v6 theme={null}
  BoxCollection<BoxItem> items = await client.CollectionsManager.GetCollectionItemsAsync(id: "11111");
  ```

  ```javascript Node v4 theme={null}
  client.collections.getItems('81934', {fields: 'name', limit: 2})
  	.then(items => {
  		/* items -> { total_count: 24,
  			entries: 
  			[ { type: 'folder',
  				id: '192429928',
  				sequence_id: '1',
  				etag: '1',
  				name: 'Stephen Curry Three Pointers' },
  				{ type: 'file',
  				id: '818853862',
  				sequence_id: '0',
  				etag: '0',
  				name: 'Warriors.jpg' } ],
  			offset: 0,
  			limit: 2 }
  		*/
  	});
  ```
</CodeGroup>

<Warning>
  The only collection that is available via the API is the "Favorites"
  collection. The ID of this collection is [different for every
  user](/guides/collections/list).
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Remove Item from Collection
Source: https://developer.box.com/guides/collections/remove



To remove an item from a collection, call the `PUT` endpoint for that specific
type of item and pass along a list of collection IDs that does not include the
ID of the collection that needs to be removed.

<Warning>
  The only collection that is available via the API is the "Favorites"
  collection and therefore to remove an item from this collection can be
  achieved by passing the API an empty array of collections.
</Warning>

## Remove file from collection

To remove a file from a collection, call the `PUT /files/:id` API and pass an empty
array of collection IDs.

## Remove folder from collection

To remove a folder from a collection, call the `PUT /folders/:id` API and pass an
empty array of collection IDs.

## Remove web link from collection

To remove a web link from a collection, call the `PUT /web_links/:id` API and
pass an empty array of collection IDs.

<RelatedLinks title="RELATED APIS" />


# Create Comment
Source: https://developer.box.com/guides/comments/create-comment



To create a comment, call the <Link href="/reference/post-comments">`POST /comments`</Link> API with the
message of the comment, as well as the ID of the file to leave the comment on.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/comments" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "message": "Review completed!",
         "item": {
           "type": "file",
           "id": 426436
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.comments.createComment({
    message: message,
    item: {
      id: fileId,
      type: 'file' as CreateCommentRequestBodyItemTypeField,
    } satisfies CreateCommentRequestBodyItemField,
  } satisfies CreateCommentRequestBody);
  ```

  ```python Python v10 theme={null}
  client.comments.create_comment(
      message, CreateCommentItem(id=file_id, type=CreateCommentItemTypeField.FILE)
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Comments.CreateCommentAsync(requestBody: new CreateCommentRequestBody(message: message, item: new CreateCommentRequestBodyItemField(id: fileId, type: CreateCommentRequestBodyItemTypeField.File)));
  ```

  ```swift Swift v10 theme={null}
  try await client.comments.createComment(requestBody: CreateCommentRequestBody(message: message, item: CreateCommentRequestBodyItemField(id: fileId, type: CreateCommentRequestBodyItemTypeField.file)))
  ```

  ```java Java v10 theme={null}
  client.getComments().createComment(new CreateCommentRequestBody(message, new CreateCommentRequestBodyItemField(fileId, CreateCommentRequestBodyItemTypeField.FILE)))
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  file.addComment("This file is pretty cool.");
  ```

  ```python Python v4 theme={null}
  comment = client.file(file_id='11111').add_comment('When should I have this done by?')
  ```

  ```cs .NET v6 theme={null}
  var requestParams = new BoxCommentRequest()
  {
      Item = new BoxRequestEntity()
      {
          Type = BoxType.File,
          Id = "12345"
      },
      Message = "Great work!"
  };
  BoxComment comment = await client.CommentsManager.AddCommentAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  client.comments.create('33333', 'Is this the latest version?')
      .then(comment => {
          /* comment -> {
              type: 'comment',
              id: '11111',
              is_reply_comment: false,
              message: 'Is this the latest version?',
              created_by: 
              { type: 'user',
                  id: '22222',
                  name: 'Example User',
                  login: 'user@example.com' },
              created_at: '2012-12-12T11:25:01-08:00',
              item: { id: '33333', type: 'file' },
              modified_at: '2012-12-12T11:25:01-08:00' }
          */
      });
  ```
</CodeGroup>

A comment's message can also mention users using the `@` sign. To do so, add
the string `@[userid:name]` anywhere within the message. The `user_id` is the
target user's ID, where the `name` can be any custom phrase. In the Box UI this
name will link to the user's profile.

Then, pass this string as the `tagged_message` instead of the `message`.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create Reply
Source: https://developer.box.com/guides/comments/create-reply



To create a reply to a previous comment, call the <Link href="/reference/post-comments">`POST
/comments`</Link> API with the message of the new comment, as well as
the ID of the previous comment to leave the reply on.

A reply's message can also mention users using the `@` sign. To do so, add
the string `@[userid:name]` anywhere within the message. The `user_id` is the
target user's ID, where the `name` can be any custom phrase. In the Box UI this
name will link to the user's profile.

Then, pass this string as the `tagged_message` instead of the `message`.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Comments overview
Source: https://developer.box.com/guides/comments/index



Comments are messages generated by Box users on files, allowing users to
collaborate together on a file, discussing any feedback they might have on the
content.

Each comment is tied to a specific file and user, and comments can be created as
independent comments or as replies to previous comments.


# Download File
Source: https://developer.box.com/guides/downloads/file



To download a file, pass the <Link href="/reference/get-files-id-content">`GET /files/:id/content`</Link> the ID of the file
to get the content for.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X GET "https://api.box.com/2.0/files/12345/content" \
       -H "authorization: Bearer <ACCESS_TOKEN>" 
  ```

  ```typescript Node/TypeScript v10 theme={null}
  const fs = require('fs');

  const fileContent = await client.downloads.downloadFile('123456789');
  const fileWriteStream = fs.createWriteStream('file.pdf');
  fileContent.pipe(fileWriteStream);
  ```

  ```python Python v10 theme={null}
  client.downloads.download_file(uploaded_file.id)
  ```

  ```cs .NET v10 theme={null}
  await client.Downloads.DownloadFileAsync(fileId: uploadedFile.Id);
  ```

  ```swift Swift v10 theme={null}
  let downloadsDirectoryURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
  let destinationURL = downloadsDirectoryURL.appendingPathComponent("file.txt")

  let url = try await client.downloads.downloadFile(fileId: file.id, downloadDestinationURL: destinationURL)

  if let fileContent = try? String(contentsOf: url, encoding: .utf8) {
      print("The content of the file: \(fileContent)")
  }
  ```

  ```java Java v10 theme={null}
  client.getDownloads().downloadFile(uploadedFile.getId())
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  BoxFile.Info info = file.getInfo();

  FileOutputStream stream = new FileOutputStream(info.getName());
  file.download(stream);
  stream.close();
  ```

  ```python Python v4 theme={null}
  file_id = '11111'
  file_content = client.file(file_id).content()
  ```

  ```cs .NET v6 theme={null}
  Stream fileContents = await client.FilesManager.DownloadStreamAsync(id: "11111");
  ```

  ```javascript Node v4 theme={null}
  var fs = require('fs');
  client.files.getReadStream('12345', null, function(error, stream) {

  	if (error) {
  		// handle error
  	}

  	// write the file to disk
  	var output = fs.createWriteStream('/path/to/file');
  	stream.pipe(output);
  });
  ```
</CodeGroup>

## Download URL

When not using the SDKs, this API call will return an `HTTP 302 Found` status
code, with a `location` header containing a link to the download URL, which
looks something like this.

```sh theme={null}
https://dl.boxcloud.com/d/1/[long-random-string]/download
```

By using the `-L` flag in cURL we are able to automatically follow this
redirect.

<Info>
  In our SDKs this will result in the binary data to be downloaded. In the API
  this will result in a download URL being returned via the `location` header.

  It is possible to <Link href="/guides/downloads/get-url">get the download URL</Link> via the SDKs as well.
</Info>

## Download URL expiry

Although this download URL can be passed to a user's browser to allow them to
download the file, the URL does expire and should be requested again for any
further downloads.

## File not ready

If the file is not ready to be downloaded yet a `retry-after` header will be
returned indicating the time in seconds after which the file will be available
for the client to download.

This response can occur when the file was uploaded immediately before the
download request.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Download File Version
Source: https://developer.box.com/guides/downloads/file-version



To download a specific file version, pass the <Link href="/reference/get-files-id-content">`GET /files/:id/content`</Link>
the ID of the file to get the content for, as well as its version ID.

## Download URL

When not using the SDKs, this API call will return an `HTTP 302 Found` status
code, with a `location` header containing a link to the download URL, which
looks something like this.

```sh theme={null}
https://dl.boxcloud.com/d/1/[long-random-string]/download
```

By using the `-L` flag in cURL we are able to automatically follow this
redirect.

<Info>
  In our SDKs this will result in the binary data to be downloaded. In the API
  this will result in a download URL being returned via the `location` header.

  It is possible to <Link href="/guides/downloads/get-url">get the download URL</Link> via the SDKs as well.
</Info>

## Download URL expiry

Although this download URL can be passed to a user's browser to allow them to
download the file, the URL does expire and should be requested again for any
further downloads.

## File not ready

If the file is not ready to be downloaded yet a `retry-after` header will be
returned indicating the time in seconds after which the file will be available
for the client to download.

This response can occur when the file was uploaded immediately before the
download request.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Download All Files in Folder using SDKs
Source: https://developer.box.com/guides/downloads/folder



Sometimes an application might want to download all files for a folder. To do so
with the SDKs and the CLI requires traversing the folder tree, finding every
file and downloading it accordingly.

<Note>
  To download a ZIP archive, follow <Link href="/guides/downloads/zip-archive">this</Link> guide.
</Note>

<CodeGroup>
  ```csharp .NET theme={null}
  using System;
  using System.Collections.Generic;
  using System.IO;
  using System.Linq;
  using System.Threading.Tasks;
  using Box.V2.Config;
  using Box.V2.JWTAuth;

  namespace BoxDownloadAllFiles {
      class Program {
          static void Main (string[] args) {
              ExecuteMainAsync ().Wait ();
          }

          private static async Task ExecuteMainAsync () {
              using (FileStream fs = new FileStream ($"./config.json", FileMode.Open)) {
                  var session = new BoxJWTAuth (BoxConfig.CreateFromJsonFile (fs));
                  var client = session.AdminClient (session.AdminToken ());
                  var folderId = "987654321";
                  var folder = await client.FoldersManager.GetInformationAsync (folderId);
                  var folderName = folder.Name;
                  var localFolderPath = Path.Combine (Directory.GetCurrentDirectory (), folderName);
                  ResetLocalFolder (localFolderPath);

                  var items = await client.FoldersManager.GetFolderItemsAsync (folderId, 1000, autoPaginate : true);
                  var fileDownloadTasks = new List<Task> ();
                  var files = items.Entries.Where (i => i.Type == "file");
                  foreach (var file in files) {
                      fileDownloadTasks.Add (client.FilesManager.DownloadStreamAsync (file.Id).ContinueWith ((t) => {
                          var localFile = File.Create (Path.Combine (localFolderPath, file.Name));
                          return t.Result.CopyToAsync (localFile);
                      }));
                  }
                  await Task.WhenAll (fileDownloadTasks);
              }
          }

          private static void ResetLocalFolder (string localFolderPath) {
              if (!Directory.Exists (localFolderPath)) {
                  Directory.CreateDirectory (localFolderPath);
              } else {
                  foreach (var file in Directory.EnumerateFiles (localFolderPath)) {
                      File.Delete (Path.Combine (localFolderPath, file));
                  }
                  Directory.Delete (localFolderPath);
                  Directory.CreateDirectory (localFolderPath);
              }
          }
      }
  }
  ```

  ```java Java theme={null}
  package com.box;

  import com.box.sdk.BoxConfig;
  import com.box.sdk.BoxDeveloperEditionAPIConnection;
  import com.box.sdk.BoxFile;
  import com.box.sdk.BoxFolder;
  import com.box.sdk.BoxItem;
  import java.io.BufferedReader;
  import java.io.FileOutputStream;
  import java.io.IOException;
  import java.nio.charset.Charset;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.nio.file.Paths;

  public class Playground {

      public static void main(String[] args) throws Exception {
          Path configPath = Paths.get("config.json");
          Path currentDir = Paths.get("").toAbsolutePath();
          try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) {
              BoxConfig boxConfig = BoxConfig.readFrom(reader);
              BoxDeveloperEditionAPIConnection client = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig);
              String folderId = "987654321";
              BoxFolder folder = new BoxFolder(client, folderId);
              String folderName = folder.getInfo().getName();
              Path localFolderPath = currentDir.resolve(Paths.get(folderName));
              if (!Files.exists(localFolderPath)) {
                  localFolderPath = Files.createDirectory(localFolderPath);
              } else {
                  localFolderPath = resetLocalFolder(localFolderPath);
              }

              for (BoxItem.Info itemInfo: folder) {
                  if (itemInfo instanceof BoxFile.Info) {
                      BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
                      BoxFile file = new BoxFile(client, fileInfo.getID());
                      String localFilePath = localFolderPath.resolve(Paths.get(fileInfo.getName())).toAbsolutePath().toString();
                      FileOutputStream stream = new FileOutputStream(localFilePath);
                      file.download(stream);
                      stream.close();
                  }
              }

          }
      }

      static Path resetLocalFolder(Path localFolderPath) throws IOException {
          Files.list(localFolderPath).forEach(file -> {
              System.out.println(file.getFileName());
              try {
                  Files.delete(file.toAbsolutePath());
              } catch (IOException e) {}
          });
          Files.delete(localFolderPath);
          localFolderPath = Files.createDirectory(localFolderPath);
          return localFolderPath;
      }
  }
  ```

  ```js Node theme={null}
  "use strict";
  const box = require("box-node-sdk");
  const fs = require("fs");
  const util = require("util");
  const path = require("path");
  let configFile = fs.readFileSync("config.json");
  configFile = JSON.parse(configFile);

  let session = box.getPreconfiguredInstance(configFile);
  let client = session.getAppAuthClient("enterprise");
  client._useIterators = true;

  let folderId = "987654321";
  let folderName;
  let localFolderPath;
  client.folders
      .get(folderId, null)
      .then(folderInfo => {
          folderName = folderInfo.name;

          return client.folders.getItems(folderId, { limit: 1000 });
      })
      .then(folderItemsIterator => {
          return autoPage(folderItemsIterator);
      })
      .then(folderItems => {
            console.log(folderName);
            console.log(folderItems.length);
            let files = folderItems.filter(item => {
                return item.type === "file";
            });
            console.log(files);
            localFolderPath = createLocalFolder(folderName);
            let downloadPromises = [];
            files.forEach(file => {
                downloadPromises.push(
                    client.files.getReadStream(file.id, null).then(stream => {
                        let output = fs.createWriteStream(
                          path.join(localFolderPath, file.name)
                        );
                        stream.pipe(output);
                    })
                );
            });
            return Promise.all(downloadPromises);
      })
      .then(() => {
          console.log("Downloaded all files...");
          console.log(fs.readdirSync(localFolderPath));
      });

  function createLocalFolder(folderName) {
      let localFolderName = path.join(__dirname, folderName);
      try {
          fs.mkdirSync(localFolderName);
      } catch (e) {
          if (e.code === "EEXIST") {
              resetLocalFolder(localFolderName);
              fs.mkdirSync(localFolderName);
          } else {
              throw e;
          }
      }
      return localFolderName;
  }

  function resetLocalFolder(localFolderName) {
      if (fs.existsSync(localFolderName)) {
          fs.readdirSync(localFolderName).forEach(localFileName => {
              console.log(localFileName);
              fs.unlinkSync(path.join(localFolderName, localFileName));
          });
          fs.rmdirSync(localFolderName);
      }
  }

  function autoPage(iterator) {
      let collection = [];
      let moveToNextItem = () => {
          return iterator.next().then(item => {
              if (item.value) {
                  collection.push(item.value);
              }
              if (item.done !== true) {
                  return moveToNextItem();
              } else {
                  return collection;
              }
          });
      };
      return moveToNextItem();
  }
  ```
</CodeGroup>

<Warning>
  It is important to remember that an application needs to have the
  permissions to access and download the files and folders in question. When the
  authenticated user does not have access to any of the files or folders, an
  `HTTP 404 Not Found` error will occur.

  Learn more about <Link href="/guides/getting-started/users">User Types</Link> in our guides on
  authentication.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get Download URL
Source: https://developer.box.com/guides/downloads/get-url



The official Box SDKs return the binary data when downloading a file. To get the
download URL for the data instead, use the following SDK methods.

<Warning>
  **Redirects**

  If you are not using one of our SDKs it's important to make sure your HTTP
  client does not automatically follow HTTP redirects. When redirects are
  automatically followed, your code will detect the `location` header returned
  by the API and follow it to get the binary data.
</Warning>

## Download URL expiry

Although this download URL can be passed to a user's browser to allow them to
download the file, the URL does expire and should be requested again for any
further downloads. In most cases the download URL is valid for 15 minutes, after
which a new URL needs to be requested. This expiration time may be subject to
change without any prior notification.

[api]: /reference/get-files-id-content

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Download in Browser
Source: https://developer.box.com/guides/downloads/in-browser



Sometimes an application wants to embed a file into a page as an HTML element. An
example would be when working with an audio player.

```html theme={null}
<audio controls>
  <source src="..." type="audio/mp3">
</audio>
```

In this case, using the regular <Link href="/guides/downloads/get-url">download URL</Link> does not work because the
`dl.boxcloud.com` domain does not support <Link href="/guides/security/cors">Cross Origin Resource Sharing</Link>.

Instead an application can use the following format.

```sh theme={null}
https://api.box.com/2.0/files/[FILE_ID]/content?access_token=[ACCESS_TOKEN]
```

<Warning>
  **CORS**

  For this to work the application needs to have the domain of the web site
  hosting this file added to the list of allowed domains in the <Link href="/guides/security/cors">CORS
  settings</Link>.
</Warning>

<Warning>
  **Downscope Token**

  Using this method would expose the Access Token to the end user, allowing them
  to potentially use this token to do more than intended. For this reason we
  recommend <Link href="/guides/authentication/tokens/downscope">downscoping</Link> this token accordingly.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Downloads
Source: https://developer.box.com/guides/downloads/index

Download files from Box to your application server or directly to a browser, and understand access requirements.

The Box API allows for downloading files to the application's server, or directly
by the end user in a browser.

## Quick example

Download a file by its ID:

```bash theme={null}
curl -L https://api.box.com/2.0/files/FILE_ID/content \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -o downloaded-file.pdf
```

## When not to download

Downloading a file is not always the desired solution, especially if the file is
only being downloaded for the user to preview, comment, or annotate. In those
cases we recommend using one of the ways to embed the Box experience straight
into your application.

<Card href={localizeLink("/guides/embed/")} title="Learn more about embedding Box" />

## Access Errors

It is important to realize that the application needs to have access to the
file that is to be downloaded. When the application is authenticated through
JWT, the user is authenticated as a Service Account. This service
account does not have access to files besides their own.

If this user does not have access to the file the application will receive a
`404 Not Found` error.

<Card href={localizeLink("/guides/getting-started/users/")} title="Learn more about different User Types" />


# Download Shared Link
Source: https://developer.box.com/guides/downloads/shared-link



<RelatedLinks title="REQUIRED GUIDES" />

To download the file for a <Link href="/guides/shared-links">Shared Link</Link>, first <Link href="/guides/shared-links/find-for-item">determine the
file</Link> for the link.

<Note>
  You cannot use the shared link to download folders. <Link href="/guides/downloads/zip-archive">Create and download
  the ZIP archive</Link> instead.
</Note>

Once the file ID has been determined, the file can be downloaded by passing the
`BoxAPI` header to the API.

<Warning>
  To get the Shared Link for an item the user must have at least viewer-level
  access to the item.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Download ZIP Archive
Source: https://developer.box.com/guides/downloads/zip-archive



To download all files in a folder or an entire folder structure, you have to create and download a ZIP archive.

## Create a ZIP Archive

First, you need to create a ZIP archive containing the files or the folder structure. You can include up to 10,000 file and folder IDs unless you reach the account’s upload limit.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/zip_downloads" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
         "download_file_name": "January Financials",
         "items": [
           {
             "type": "file",
             "id": "12345"
           },
           {
             "type": "file",
             "id": "34325"
           },
           {
             "type": "folder",
             "id": "45678"
           }
         ]
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.zipDownloads.createZipDownload({
    items: [
      {
        id: file1.id,
        type: 'file' as ZipDownloadRequestItemsTypeField,
      } satisfies ZipDownloadRequestItemsField,
      {
        id: file2.id,
        type: 'file' as ZipDownloadRequestItemsTypeField,
      } satisfies ZipDownloadRequestItemsField,
      {
        id: folder1.id,
        type: 'folder' as ZipDownloadRequestItemsTypeField,
      } satisfies ZipDownloadRequestItemsField,
    ],
    downloadFileName: 'zip',
  } satisfies ZipDownloadRequest);
  ```

  ```python Python v10 theme={null}
  client.zip_downloads.create_zip_download(
      [
          CreateZipDownloadItems(id=file_1.id, type=DownloadZipItemsTypeField.FILE),
          CreateZipDownloadItems(id=file_2.id, type=DownloadZipItemsTypeField.FILE),
          CreateZipDownloadItems(id=folder_1.id, type=DownloadZipItemsTypeField.FOLDER),
      ],
      download_file_name="zip",
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.ZipDownloads.CreateZipDownloadAsync(requestBody: new ZipDownloadRequest(items: Array.AsReadOnly(new [] {new ZipDownloadRequestItemsField(id: file1.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: file2.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: folder1.Id, type: ZipDownloadRequestItemsTypeField.Folder)})) { DownloadFileName = "zip" });
  ```

  ```swift Swift v10 theme={null}
  try await client.zipDownloads.createZipDownload(requestBody: ZipDownloadRequest(items: [ZipDownloadRequestItemsField(id: file1.id, type: ZipDownloadRequestItemsTypeField.file), ZipDownloadRequestItemsField(id: file2.id, type: ZipDownloadRequestItemsTypeField.file), ZipDownloadRequestItemsField(id: folder1.id, type: ZipDownloadRequestItemsTypeField.folder)], downloadFileName: "zip"))
  ```

  ```java Java v10 theme={null}
  client.getZipDownloads().createZipDownload(new ZipDownloadRequest.Builder(Arrays.asList(new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FILE, file1.getId()), new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FILE, file2.getId()), new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FOLDER, folder1.getId()))).downloadFileName("zip").build())
  ```

  ```java Java v5 theme={null}
  ArrayList<BoxZipItem> items = new ArrayList<BoxZipItem>();
  BoxZipItem file = new BoxZipItem("file", "12345");
  BoxZipItem folder = new BoxZipItem("folder", "156472");
  items.add(file);
  items.add(folder);
  BoxZip zip = new BoxZip(api);
  BoxZipInfo zipInfo = zip.create("Awesome Zip File", items);
  ```

  ```js Node v4 theme={null}
  var name = 'test',
  items = [
   {
    type: 'file',
    id: '466239504569'
   },
   {
    type: 'folder',
    id: '466239504580'
   }
  ];
  client.files.createZip(name, items)
   .then(zip => {
    /* zip -> {
      "download_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/content",
      "status_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/status",
      "expires_at": "2018-04-25T11:00:18-07:00",
      "name_conflicts": [
       [
        {
         "id": "100",
         "type": "file",
         "original_name": "salary.pdf",
         "download_name": "aqc823.pdf"
        },
        {
         "id": "200",
         "type": "file",
         "original_name": "salary.pdf",
         "download_name": "aci23s.pdf"
        }
       ],
       [
        {
         "id": "1000",
         "type": "folder",
         "original_name": "employees",
         "download_name": "3d366a_employees"
        },
        {
         "id": "2000",
         "type": "folder",
         "original_name": "employees",
         "download_name": "3aa6a7_employees"
        }
       ]
      ]
     }
    */
   });
  ```
</CodeGroup>

The response will look similar to the following:

```json theme={null}
{
  "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew/content",
  "status_url": "https://api.box.com/2.0/zip_downloads/25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew/status",
  "expires_at": "2023-02-28T10:23:54Z",
  "name_conflicts": []
}
```

## Extract the ZIP download ID

To download the ZIP archive, you need the ZIP download ID.
You can find it in the response you got when you created the archive.

Go to `status_url` and copy the ID located between `zip_downloads` and `content`:

```json theme={null}
25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew
```

<Note>
  Download URL is valid only for the time specified in `expires_at` parameter.
</Note>

## Download files

Place the download ID in the file location URL as in the sample below
to point to the right files.

<CodeGroup>
  ```sh cURL theme={null}
  curl -L GET "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -o sample_curl.zip
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.zipDownloads.getZipDownloadContent(zipDownload.downloadUrl!);
  ```

  ```python Python v10 theme={null}
  client.zip_downloads.get_zip_download_content(zip_download.download_url)
  ```

  ```csharp .NET v10 theme={null}
  await client.ZipDownloads.GetZipDownloadContentAsync(downloadUrl: NullableUtils.Unwrap(zipDownload.DownloadUrl));
  ```

  ```swift Swift v10 theme={null}
  try await client.zipDownloads.getZipDownloadContent(downloadUrl: zipDownload.downloadUrl!, downloadDestinationUrl: URL(path: destinationPathString))
  ```

  ```java Java v10 theme={null}
  client.getZipDownloads().getZipDownloadContent(zipDownload.getDownloadUrl())
  ```

  ```java Java v5 theme={null}
  ArrayList<BoxZipItem> items = new ArrayList<BoxZipItem>();
  BoxZipItem file = new BoxZipItem("file", "12345");
  BoxZipItem folder = new BoxZipItem("folder", "156472");
  items.add(file);
  items.add(folder);
  BoxZip zip = new BoxZip(api);
  FileOutputStream stream = new FileOutputStream();
  BoxZipDownloadStatus zipDownloadStatus = zip.download("Another Awesome Zip File", items, stream);
  stream.close();
  if (zipDownloadStatus.getState() == BoxZipDownloadStatus.State.SUCCEEDED) {
      System.out.println("Zip downloaded successfully");
  }
  ```

  ```py Python v4 theme={null}
  name = 'test'
  file = mock_client.file('466239504569')
  folder = mock_client.folder('466239504580')
  items = [file, folder]
  output_file = open('test.zip', 'wb')
  status = client.download_zip(name, items, output_file)
  print(f'The status of the zip download is {status["state"]}')
  ```

  ```csharp .NET v6 theme={null}
  BoxZipRequest request = new BoxZipRequest();
  request.Name = "test";
  request.Items = new List<BoxZipItemRequest>();

  var file = new BoxZipRequestItem()
  {
      Id = "466239504569",
      Type = BoxZipItemType.file
  };
  var folder = new BoxZipRequestItem()
  {
      Id = "466239504580",
      Type = BoxZipItemType.folder
  };
  request.Items.Add(file);
  request.Items.Add(folder);
  Stream fs = new FileStream(@"c:\temp\MyTest.zip");

  BoxZipDownloadStatus status = await _filesManager.DownloadZip(request, fs);
  ```

  ```js Node v4 theme={null}
  var name = 'test',
  items = [
   {
    type: 'file',
    id: '466239504569'
   },
   {
    type: 'folder',
    id: '466239504580'
   }
  ],
  stream = new Readable();
  client.files.downloadZip(name, items, stream)
   .then(status => {
    /* status -> {
      "total_file_count": 20,
      "downloaded_file_count": 10,
      "skipped_file_count": 10,
      "skipped_folder_count": 10,
      "state": "succeeded"
     }
    */
   });
  ```
</CodeGroup>

For downloads that take longer, you can monitor the
download status using the
<Link href="/reference/get-zip-downloads-id-status">status endpoint</Link>.
This allows you to inspect the progress of the
download as well as the number of items that might have been skipped.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.zipDownloads.getZipDownloadStatus(zipDownload.statusUrl!);
  ```

  ```python Python v10 theme={null}
  client.zip_downloads.get_zip_download_status(zip_download.status_url)
  ```

  ```csharp .NET v10 theme={null}
  await client.ZipDownloads.GetZipDownloadStatusAsync(statusUrl: NullableUtils.Unwrap(zipDownload.StatusUrl));
  ```

  ```swift Swift v10 theme={null}
  try await client.zipDownloads.getZipDownloadStatus(statusUrl: zipDownload.statusUrl!)
  ```

  ```java Java v10 theme={null}
  client.getZipDownloads().getZipDownloadStatus(zipDownload.getStatusUrl())
  ```
</CodeGroup>

<Note>
  If you want to use SDKs to download the contents
  of the folder, follow <Link href="/guides/downloads/folder">this</Link> guide.
</Note>

<RelatedLinks title="RELATED APIS" />


# Copy a File Request
Source: https://developer.box.com/guides/file-requests/copy



<RelatedLinks title="REQUIRED GUIDES" />

To create a copy of an existing <Link href="/guides/file-requests/template">template</Link> file
request, all you need is its unique ID, and the ID of the folder to apply the
new file request to.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/file_requests/42037322/copy" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
         "title": "Please upload required documents",
         "description": "Please upload required documents",
         "status": "active",
         "is_email_required": true,
         "is_description_required": false,
         "folder": {
           "id": "2233212",
           "type": "folder"
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileRequests.createFileRequestCopy(fileRequestId, {
    folder: {
      id: fileRequest.folder.id,
      type: 'folder' as FileRequestCopyRequestFolderTypeField,
    } satisfies FileRequestCopyRequestFolderField,
  } satisfies FileRequestCopyRequest);
  ```

  ```python Python v10 theme={null}
  client.file_requests.create_file_request_copy(
      file_request_id,
      CreateFileRequestCopyFolder(
          id=file_request.folder.id, type=CreateFileRequestCopyFolderTypeField.FOLDER
      ),
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FileRequests.CreateFileRequestCopyAsync(fileRequestId: fileRequestId, requestBody: new FileRequestCopyRequest(folder: new FileRequestCopyRequestFolderField(id: fileRequest.Folder.Id) { Type = FileRequestCopyRequestFolderTypeField.Folder }));
  ```

  ```swift Swift v10 theme={null}
  try await client.fileRequests.createFileRequestCopy(fileRequestId: fileRequestId, requestBody: FileRequestCopyRequest(folder: FileRequestCopyRequestFolderField(id: fileRequest.folder.id, type: FileRequestCopyRequestFolderTypeField.folder)))
  ```

  ```java Java v10 theme={null}
  client.getFileRequests().createFileRequestCopy(fileRequestId, new FileRequestCopyRequest(new FileRequestCopyRequestFolderField.Builder(fileRequest.getFolder().getId()).type(FileRequestCopyRequestFolderTypeField.FOLDER).build()))
  ```

  ```java Java v5 theme={null}
  BoxFileRequest fileRequest = new BoxFileRequest(api, "id");
  BoxFileRequest.Info fileRequestInfo = fileRequest.new Info();
  fileRequestInfo.setDescription("Following documents are requested for your process");
  fileRequestInfo.setIsDescriptionRequired(true);
  fileRequestInfo.setStatus(BoxFileRequest.Status.ACTIVE);
  fileRequestInfo = fileRequest.copyInfo(fileRequestInfo, "folderId");
  ```

  ```py Python v4 theme={null}
  file_request = client.file_request(file_request_id='123456')
  folder = client.folder(folder_id='123456789')
  new_file_request = file_request.copy(folder=folder, title="Copied file request")
  ```

  ```csharp .NET v6 theme={null}
  var destinationFolder = new BoxRequestEntity
  {
      Id = "123456",
      Type = BoxType.folder
  };

  var copyRequest = new BoxFileRequestCopyRequest
  {
      Description = "New file request description",
      Folder = destinationFolder
  };

  BoxFileRequestObject fileRequest = await client.FileRequestsManager.CopyFileRequestAsync("12345", copyRequest);
  ```

  ```js Node v4 theme={null}
  client.fileRequests.copy(fileRequestId, {
    folder: {
      id: '157979815648',
      type: 'folder'
    }
  }).then((r: FileRequest) => {
    // do something with the copied file request 
    console.log(r)
  });
  ```
</CodeGroup>

<Note>
  The ID of a folder and file request can be determined by visiting the Box web
  app and inspecting the URL.

  The folder ID is the number at the end of the URL when visiting a folder, for
  example `app.box.com/folder/123` is the URL for the folder with ID `123`.

  For a file request, please <Link href="/guides/file-requests/template">check our guide</Link>
  on setting up a file request template to learn how to determine a file request
  ID.
</Note>

## Updating a file request on copy

It is possible to make some basic changes to a file request when copying from
a template. The file request's title, description, status and a few more other
settings can be updated when the file request is copied from the template.

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/file_requests/2342235/copy" \
    -H "Authorization: Bearer <ACCESS_TOKEN>" \
    -d '{
      "title": "Please upload required documents",
      "description": "Please upload required documents",
      "status": "active",
      "is_email_required": true,
      "is_description_required": false,
      "folder": {
        "id": "342323423"
      }
    }'
```

<Note>
  For more details on the different fields that can be updated when creating
  a template, please see the reference documentation for the
  <Link href="/reference/post-file-requests-id-copy">`POST /file-requests/:id/copy`</Link> API.
</Note>

<RelatedLinks title="RELATED APIS" />


# Delete a File Request
Source: https://developer.box.com/guides/file-requests/delete



<RelatedLinks title="REQUIRED GUIDES" />

To delete a file request, all you need is its unique ID.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/file_requests/42037322" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileRequests.deleteFileRequestById(updatedFileRequest.id);
  ```

  ```python Python v10 theme={null}
  client.file_requests.delete_file_request_by_id(updated_file_request.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.FileRequests.DeleteFileRequestByIdAsync(fileRequestId: updatedFileRequest.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.fileRequests.deleteFileRequestById(fileRequestId: updatedFileRequest.id)
  ```

  ```java Java v10 theme={null}
  client.getFileRequests().deleteFileRequestById(updatedFileRequest.getId())
  ```

  ```java Java v5 theme={null}
  BoxFileRequest fileRequest = new BoxFileRequest(api, "id");
  fileRequest.delete();
  ```

  ```py Python v4 theme={null}
  file_request = client.file_request(file_request_id='123456')
  file_request.delete()
  ```

  ```csharp .NET v6 theme={null}
  bool isSuccess = await client.FileRequestsManager.DeleteFileRequestAsync("12345");
  ```

  ```js Node v4 theme={null}
  client.fileRequests.delete('2484517969').then(() => console.log('Removed file request'));
  ```
</CodeGroup>

<Note>
  The ID of a file request can be determined by visiting the Box web
  app and inspecting the URL. Please
  <Link href="/guides/file-requests/template">check our guide</Link> on setting up a file
  request template to learn how to determine a file request ID.
</Note>

<RelatedLinks title="RELATED APIS" />


# Get information for a File Request
Source: https://developer.box.com/guides/file-requests/get



To get details about an existing <Link href="/guides/file-requests/template">file request</Link>,
all you need is its unique ID.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/file_requests/42037322" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileRequests.getFileRequestById(fileRequestId);
  ```

  ```python Python v10 theme={null}
  client.file_requests.get_file_request_by_id(file_request_id)
  ```

  ```csharp .NET v10 theme={null}
  await client.FileRequests.GetFileRequestByIdAsync(fileRequestId: fileRequestId);
  ```

  ```swift Swift v10 theme={null}
  try await client.fileRequests.getFileRequestById(fileRequestId: fileRequestId)
  ```

  ```java Java v10 theme={null}
  client.getFileRequests().getFileRequestById(fileRequestId)
  ```

  ```java Java v5 theme={null}
  BoxFileRequest fileRequest = new BoxFileRequest(api, "id");
  BoxFileRequest.Info fileRequestInfo = fileRequest.getInfo();
  ```

  ```py Python v4 theme={null}
  file_request = client.file_request(file_request_id='123456').get()
  print(f'File request {file_request.id} on folder {file_request.folder.name}')
  ```

  ```csharp .NET v6 theme={null}
  BoxFileRequestObject fileRequest = await client.FileRequestsManager.GetFileRequestByIdAsync("12345");
  ```

  ```js Node v4 theme={null}
  client.fileRequests.getById(fileRequestId)
  ```
</CodeGroup>

<Note>
  The ID of a file request can be determined by visiting the Box web
  app and inspecting the URL. Please
  <Link href="/guides/file-requests/template">check our guide</Link> on setting up a file
  request template to learn how to determine a file request ID.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# File Requests
Source: https://developer.box.com/guides/file-requests/index



Box File Request gives you a fast and secure way to request files and
associated metadata from anyone.  Using a drag-and-drop graphic
interface, you can create a web form that enables you to:

* Securely request files from anyone, no matter whether they have a Box account, without adding collaborators on a folder.
* Solicit additional information with metadata form fields, which you can set as required/optional.
* Enable extra security and tracking with link settings.
* Kick off automated workflows using Box Relay.

The **File Request API** gives you the power to create new file requests
based on an existing file request, update file request settings, activate
and deactivate, and delete file requests programmatically.

## Use Cases

The File Request API is especially useful in situations where folders are
automatically created when a new case, project, or customer is created in an
external system. For each of these folders a file request can be automatically
generated, allowing customers and other users to upload documents to the
project.

For example.

* **Case management** - In this situation each customer support case has its own associated folder and a new file request can be sent out to a customer, requesting them to submit case related documents to the folder.
* **Project management** - In this situation each project has its own associated folder for each project defined in an external system. The API can be used to automatically create a **"Client Documents"** folder within this folder, and a link can be sent to the client to allow them to upload documents on demand.
* **Employee "drop" folder** - In this situation every new loan advisor in a bank has a personal folder in Box. To help them work with their clients a "drop" subfolder is automatically generated for them with an associated file request, allowing their clients to automatically upload documents to their advisor's personal folder.

## Limitations

Currently, the API only allows the creation of new file requests by copying
an existing file request associated to another folder. Please check our guide
to create a template folder with a template file request.

<RelatedLinks title="RELATED APIS" />


# Create a template File Request
Source: https://developer.box.com/guides/file-requests/template



Currently, the API only allows the creation of new file requests by copying an
existing file request associated to another folder. Please check our below
guide on creating a template folder with a template file request.

## 1. Template folder

First off, create a template folder that you can associate the template file
request to. This can be any folder really, but we recommend using a
folder that is only used for this purpose.

A folder can be created through the Box web or mobile interface, or through the
<Link href="/reference/post-folders">`POST /folders`</Link> API.

<Note>
  When using server-side JWT authentication, we recommend creating a folder that
  is owned by the application's
  <Link href="/guides/getting-started/users#service-account">Service Account</Link>. This way,
  the folder can't be accidentally deleted by a regular Box user.
</Note>

## 2. Template file request

To create a file request, navigate to the template folder in the web app and
click the 3 dots at the top of the page. Then, select **File Request** from
the menu.

<Frame>
  <img alt="Create a file request" />
</Frame>

In the next configuration panel, click the **Edit** button to visit the file
request configuration page.

<Frame>
  <img alt="Edit a file request" />
</Frame>

On the configuration page, you can configure the title and description,
before saving the page.

This page will also have the ID of the file request in the URL. Make a note of
the URL as the number at the end is the file request's ID, which you will need
when working with the API.

```sh theme={null}
https://*.app.box.com/filerequest/2338423584
```

<Warning>
  If your template folder belongs to a JWT user, you will need to
  <Link href="/reference/post-collaborations">invite</Link> a managed Box user to the folder before
  it can be seen in the web app. Invite yourself to the folder to allow yourself
  to add a file request to the folder via the app.
</Warning>

## 3. Using a template

A template file request can be used to create new copies using the
<Link href="/reference/post-file-requests-id-copy">`POST /file-requests/:id/copy`</Link>
API. With the ID of a new folder in hand, you can copy the existing
request, including its title, description and form-configuration
to a new folder <Link href="/guides/file-requests/copy">with one API call</Link>.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Update a File Request
Source: https://developer.box.com/guides/file-requests/update



To update some of the basic details for an existing
file request, all you need is its unique ID.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/file_requests/42037322" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
         "title": "Please upload required documents",
         "description": "Please upload required documents",
         "status": "active",
         "is_email_required": true,
         "is_description_required": false
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileRequests.updateFileRequestById(copiedFileRequest.id, {
    title: 'updated title',
    description: 'updated description',
  } satisfies FileRequestUpdateRequest);
  ```

  ```python Python v10 theme={null}
  client.file_requests.update_file_request_by_id(
      copied_file_request.id, title="updated title", description="updated description"
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FileRequests.UpdateFileRequestByIdAsync(fileRequestId: copiedFileRequest.Id, requestBody: new FileRequestUpdateRequest() { Title = "updated title", Description = "updated description" });
  ```

  ```swift Swift v10 theme={null}
  try await client.fileRequests.updateFileRequestById(fileRequestId: copiedFileRequest.id, requestBody: FileRequestUpdateRequest(title: "updated title", description: "updated description"))
  ```

  ```java Java v10 theme={null}
  client.getFileRequests().updateFileRequestById(copiedFileRequest.getId(), new FileRequestUpdateRequest.Builder().title("updated title").description("updated description").build())
  ```

  ```java Java v5 theme={null}
  BoxFileRequest fileRequest = new BoxFileRequest(api, "id");
  BoxFileRequest.Info fileRequestInfo = fileRequest.new Info();
  fileRequestInfo.setDescription("Following documents are requested for your process");
  fileRequestInfo.setIsDescriptionRequired(true);
  fileRequestInfo.setStatus(BoxFileRequest.Status.ACTIVE);
  fileRequestInfo = fileRequest.updateInfo(fileRequestInfo);
  ```

  ```py Python v4 theme={null}
  from boxsdk.object.file_request import StatusState
  update_data = {
      "description": 'Updated description', 
      "is_email_required": True,
      "status": StatusState.ACTIVE
  }
  file_request.update_info(data=update_data)
  ```

  ```csharp .NET v6 theme={null}
  var updateRequest = new BoxFileRequestUpdateRequest
  {
      Description = "New file request description",
      Status = BoxFileRequestStatus.inactive
  };

  BoxFileRequestObject fileRequest = await client.FileRequestsManager.UpdateFileRequestAsync("12345", updateRequest);
  ```

  ```js Node v4 theme={null}
  client.fileRequests.update(fileRequestId, {
    title: 'Updated title'
  }).then((r: FileRequest) => {
    // do something with the updated file request 
    console.log(r)
  });
  ```
</CodeGroup>

For more details on the different fields that can be updated when creating
a template, please see the reference documentation for the
<Link href="/reference/put-file-requests-id">`POST /file-requests/:id/update`</Link> API.

<Note>
  The ID of a file request can be determined by visiting the Box web
  app and inspecting the URL. Please
  <Link href="/guides/file-requests/template">check our guide</Link> on setting up a file
  request template to learn how to determine a file request ID.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Build Folder Tree
Source: https://developer.box.com/guides/folders/bulk/build-folder-tree



The following examples provide an example on how to create a JSON representation
of a folder tree. A folder tree is the name of a folder, and every subfolder
within that folder.

The sample below allows for specifying the starting **root** folder and the
maximum depth the code should traverse. It also allows for configuring what user
is authenticated by allowing the passing in of an initialized SDK client.

<CodeGroup>
  ```csharp .NET theme={null}
  using System;
  using System.Collections.Generic;
  using System.Diagnostics;
  using System.Dynamic;
  using System.IO;
  using System.Linq;
  using System.Net;
  using System.Net.Sockets;
  using System.Runtime.InteropServices;
  using System.Text;
  using System.Threading.Tasks;
  using Box.V2;
  using Box.V2.Auth;
  using Box.V2.Config;
  using Box.V2.Converter;
  using Box.V2.Exceptions;
  using Box.V2.JWTAuth;
  using Box.V2.Models;
  using Newtonsoft.Json;

  namespace BoxPlayground
  {
      public class Program4
      {
          static void Main(string[] args)
          {
              ExecuteMainAsync().Wait();
          }

          public class BoxFolderTreeBuilder
          {
              public BoxClient BoxClient { get; set; }
              public string RootFolderId { get; set; }
              public int MaxDepth { get; set; }

              public BoxFolderTreeBuilder(BoxClient boxClient, string rootFolderId = "0", int maxDepth = -1)
              {
                  this.BoxClient = boxClient;
                  this.RootFolderId = rootFolderId;
                  this.MaxDepth = maxDepth;
              }

              public async Task<BoxFolderTree> BuildFolderTreeWithFlatLists()
              {
                  var tree = new BoxFolderTree
                  {
                      RootId = this.RootFolderId,
                      Files = new List<BoxFolderTreeItem>(),
                      Folders = new List<BoxFolderTreeFolder>()
                  };
                  var rootFolderItems = await this.BoxClient.FoldersManager.GetFolderItemsAsync(this.RootFolderId, limit: 1000, autoPaginate: true);
                  var rootFolderChildren = new List<BoxFolderTreeFolder>();
                  foreach (var item in rootFolderItems.Entries)
                  {
                      var folderTreeItem = new BoxFolderTreeItem(item);
                      folderTreeItem.Path = $"{this.RootFolderId}";
                      if (item.Type == "file")
                      {
                          tree.Files.Add(folderTreeItem);
                      }
                      else if (item.Type == "folder")
                      {
                          var childFolder = new BoxFolderTreeFolder(folderTreeItem);
                          tree.Folders.Add(new BoxFolderTreeFolder(folderTreeItem));
                          rootFolderChildren.Add(childFolder);
                      }
                  }
                  tree = await Dive(tree, rootFolderChildren, 1);
                  return tree;
              }

              private async Task<BoxFolderTree> Dive(BoxFolderTree tree,
                  List<BoxFolderTreeFolder> children, int currentDepth)
              {
                  if (InTooDeep(currentDepth))
                  {
                      return tree;
                  }
                  else
                  {
                      currentDepth++;
                      var additionalChildren = new List<BoxFolderTreeFolder>();
                      foreach (var child in children)
                      {
                          var folderItems = await this.BoxClient.FoldersManager.GetFolderItemsAsync(child.Item.Id, limit: 1000, autoPaginate: true);
                          var foundFolder = tree.Folders.FindIndex((f) =>
                          {
                              return f.Item.Id == child.Item.Id;
                          });
                          foreach (var item in folderItems.Entries)
                          {
                              if (foundFolder >= 0)
                              {
                                  tree.Folders[foundFolder].Children.Add(item);
                              }
                              var folderTreeItem = new BoxFolderTreeItem(item);
                              folderTreeItem.Path = $"{child.Path}/{child.Item.Id}";
                              if (item.Type == "file")
                              {
                                  tree.Files.Add(folderTreeItem);
                              }
                              else if (item.Type == "folder")
                              {
                                  var childFolder = new BoxFolderTreeFolder(folderTreeItem);
                                  tree.Folders.Add(new BoxFolderTreeFolder(folderTreeItem));
                                  additionalChildren.Add(childFolder);
                              }
                          }
                      }
                      if (additionalChildren.Count == 0)
                      {
                          return tree;
                      }
                      else
                      {
                          return await Dive(tree, additionalChildren, currentDepth);
                      }
                  }
              }

              private bool InTooDeep(int depthCount)
              {
                  if (this.MaxDepth < 0)
                  {
                      return false;
                  }
                  else
                  {
                      return (depthCount >= this.MaxDepth);
                  }
              }
              public class BoxFolderTreeItem
              {
                  [JsonProperty(PropertyName = "item")]
                  public BoxItem Item { get; set; }

                  [JsonProperty(PropertyName = "path")]
                  public string Path { get; set; }
                  public BoxFolderTreeItem(BoxItem item)
                  {
                      Item = item;
                  }
              }
              public class BoxFolderTreeFolder : BoxFolderTreeItem
              {
                  public BoxFolderTreeFolder(BoxFolderTreeItem item) : base(item.Item)
                  {
                      this.Path = item.Path;
                  }

                  [JsonProperty(PropertyName = "children")]
                  public List<BoxItem> Children { get; set; } = new List<BoxItem>();
              }
              public class BoxFolderTree
              {
                  [JsonProperty(PropertyName = "rootId")]
                  public string RootId { get; set; }
                  [JsonProperty(PropertyName = "files")]
                  public List<BoxFolderTreeItem> Files { get; set; }

                  [JsonProperty(PropertyName = "folders")]
                  public List<BoxFolderTreeFolder> Folders { get; set; }

                  public string writeJSON()
                  {
                      var converter = new Box.V2.Converter.BoxJsonConverter();
                      return converter.Serialize<BoxFolderTreeBuilder.BoxFolderTree>(this);
                  }
              }
          }
          private static async Task ExecuteMainAsync()
          {
              using (FileStream fs = new FileStream($"./config.json", FileMode.Open))
              {
                  var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs));
                  var serviceAccountClient = session.AdminClient(session.AdminToken());
                  var folderTreeBuilder = new BoxFolderTreeBuilder(serviceAccountClient, rootFolderId: "37477903736");
                  var tree = await folderTreeBuilder.BuildFolderTreeWithFlatLists();
                  System.Console.WriteLine(tree.writeJSON());
              }
          }
      }
  }
  ```

  ```java Java theme={null}
  package com.box;

  import java.io.BufferedReader;
  import java.nio.charset.Charset;
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.nio.file.Paths;
  import java.util.ArrayList;
  import com.box.sdk.BoxConfig;
  import com.box.sdk.BoxDeveloperEditionAPIConnection;
  import com.box.sdk.BoxFile;
  import com.box.sdk.BoxFolder;
  import com.box.sdk.BoxItem;
  import com.eclipsesource.json.JsonArray;
  import com.eclipsesource.json.JsonObject;

  public class BoxFolderTreeBuilder {
      private BoxDeveloperEditionAPIConnection _boxClient;
      private String _rootFolderId;
      private int _maxDepth;

      private static final String DEFAULT_ROOT_FOLDER_ID = "0";
      private static final int DEFAULT_MAX_DEPTH = -1;

      public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient) {
          this(boxClient, DEFAULT_ROOT_FOLDER_ID, DEFAULT_MAX_DEPTH);
      }

      public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient, String rootFolderId) {
          this(boxClient, rootFolderId, DEFAULT_MAX_DEPTH);
      }

      public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient, int maxDepth) {
          this(boxClient, DEFAULT_ROOT_FOLDER_ID, maxDepth);
      }

      public BoxFolderTreeBuilder(BoxDeveloperEditionAPIConnection boxClient, String rootFolderId, int maxDepth) {
          this._boxClient = boxClient;
          this._rootFolderId = rootFolderId;
          this._maxDepth = maxDepth;
      }

      public BoxFolderTree buildFolderTreeWithFlatLists() {
          BoxFolderTree tree = new BoxFolderTree();
          tree.setRootId(this._rootFolderId);
          ArrayList<BoxFolderTreeFolder> rootFolderChildren = new ArrayList<>();
          BoxFolder folder = new BoxFolder(this._boxClient, this._rootFolderId);
          String path = this._rootFolderId;
          for (BoxItem.Info itemInfo : folder) {
              if (itemInfo instanceof BoxFile.Info) {
                  BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
                  BoxFolderTreeFile treeFile = new BoxFolderTreeFile(fileInfo, path);
                  tree.files.add(treeFile);
              } else if (itemInfo instanceof BoxFolder.Info) {
                  BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo;
                  BoxFolderTreeFolder treeFolder = new BoxFolderTreeFolder(folderInfo, path);
                  tree.folders.add(treeFolder);
                  rootFolderChildren.add(treeFolder);
              }
          }
          tree = Dive(tree, rootFolderChildren, 1);
          return tree;
      }

      private BoxFolderTree Dive(BoxFolderTree tree, ArrayList<BoxFolderTreeFolder> children, int currentDepth) {
          if (inTooDeep(currentDepth)) {
              return tree;
          } else {
              currentDepth++;
              ArrayList<BoxFolderTreeFolder> additionalChildren = new ArrayList<>();
              for (BoxFolderTreeFolder child : children) {
                  BoxFolder folderItems = new BoxFolder(this._boxClient, child.getItem().getID());
                  int foundFolder = -1;
                  for (int i = 0; i < tree.folders.size(); i++) {
                      if (child.getItem().getID() == tree.folders.get(i).getItem().getID()) {
                          foundFolder = i;
                      }
                  }
                  String path = String.format("%s/%s", child.getPath(), child.getItem().getID());
                  for (BoxItem.Info item : folderItems.getChildren()) {
                      if (foundFolder >= 0) {
                          tree.folders.get(foundFolder).children.add(new BoxFolderTreeItem(item));
                      }
                      if (item instanceof BoxFile.Info) {
                          BoxFile.Info fileInfo = (BoxFile.Info) item;
                          tree.files.add(new BoxFolderTreeFile(fileInfo, path));
                      } else if (item instanceof BoxFolder.Info) {
                          BoxFolder.Info folderInfo = (BoxFolder.Info) item;
                          BoxFolderTreeFolder nestedFolder = new BoxFolderTreeFolder(folderInfo, path);
                          tree.folders.add(nestedFolder);
                          additionalChildren.add(nestedFolder);
                      }
                  }
              }
              if (additionalChildren.size() == 0) {
                  return tree;
              } else {
                  return Dive(tree, additionalChildren, currentDepth);
              }
          }
      }

      private Boolean inTooDeep(int depthCount) {
          if (this._maxDepth < 0) {
              return false;
          } else {
              return (depthCount >= this._maxDepth);
          }
      }

      public class BoxFolderTree {
          private String rootId;
          private ArrayList<BoxFolderTreeFile> files = new ArrayList<>();
          private ArrayList<BoxFolderTreeFolder> folders = new ArrayList<>();

          public String getRootId() {
              return this.rootId;
          }

          public void setRootId(String id) {
              this.rootId = id;
          }

          public String writeJSON() {
              JsonObject requestJSON = new JsonObject();

              JsonArray filesJSON = new JsonArray();
              for (BoxFolderTreeFile file : files) {
                  filesJSON.add(file.convertToJSON());
              }

              JsonArray foldersJSON = new JsonArray();
              for (BoxFolderTreeFolder folder : folders) {
                  foldersJSON.add(folder.convertToJSON());
              }
              requestJSON.add("rootId", this.rootId);
              requestJSON.add("files", filesJSON);
              requestJSON.add("folders", foldersJSON);
              return requestJSON.toString();
          }
      }

      public class BoxFolderTreeItem {
          private BoxItem.Info item;

          public BoxFolderTreeItem(BoxItem.Info item) {
              this.item = item;
          }

          public JsonObject convertToJSON() {
              JsonObject itemJSON = new JsonObject();
              itemJSON.add("id", this.item.getID());
              itemJSON.add("name", this.item.getName());
              String type = (item instanceof BoxFile.Info == true) ? "file" : "folder";
              itemJSON.add("type", type);
              return itemJSON;
          }
      }

      public class BoxFolderTreeFile {
          private BoxFile.Info item;
          private String path;

          public BoxFolderTreeFile(BoxFile.Info item, String path) {
              this.item = item;
              this.path = path;
          }

          public BoxFile.Info getItem() {
              return this.item;
          }

          public void setItem(BoxFile.Info info) {
              this.item = info;
          }

          public String getPath() {
              return this.path;
          }

          public void setPath(String path) {
              this.path = path;
          }

          public JsonObject convertToJSON() {
              JsonObject itemJSON = new JsonObject();
              JsonObject fileJSON = new JsonObject();
              fileJSON.add("id", this.item.getID());
              fileJSON.add("type", "file");
              fileJSON.add("name", this.item.getName());

              itemJSON.add("path", this.path);
              itemJSON.add("item", fileJSON);
              return itemJSON;
          }
      }

      public class BoxFolderTreeFolder {
          private BoxFolder.Info item;
          private String path;
          private ArrayList<BoxFolderTreeItem> children;

          public BoxFolderTreeFolder(BoxFolder.Info item, String path) {
              this.item = item;
              this.path = path;
              this.children = new ArrayList<>();
          }

          public BoxFolder.Info getItem() {
              return this.item;
          }

          public void setItem(BoxFolder.Info info) {
              this.item = info;
          }

          public String getPath() {
              return this.path;
          }

          public void setPath(String path) {
              this.path = path;
          }

          public JsonObject convertFolderToJSON() {
              JsonObject itemJSON = new JsonObject();
              JsonObject folderJSON = new JsonObject();
              folderJSON.add("id", this.item.getID());
              folderJSON.add("type", "folder");
              folderJSON.add("name", this.item.getName());

              itemJSON.add("path", this.path);
              itemJSON.add("item", folderJSON);
              return itemJSON;
          }

          public JsonObject convertToJSON() {
              JsonObject folderJSON = this.convertFolderToJSON();
              JsonArray children = new JsonArray();
              for (BoxFolderTreeItem item : this.children) {
                  children.add(item.convertToJSON());
              }
              folderJSON.add("children", children);
              return folderJSON;
          }
      }

      public static void main(String[] args) throws Exception {
          Path configPath = Paths.get("config.json");
          try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) {
              BoxConfig boxConfig = BoxConfig.readFrom(reader);
              BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection
                      .getAppEnterpriseConnection(boxConfig);

              BoxFolderTreeBuilder treeBuilder = new BoxFolderTreeBuilder(serviceAccountClient, "43491738095", 2);
              BoxFolderTree tree = treeBuilder.buildFolderTreeWithFlatLists();
              System.out.println(tree.writeJSON());
          }
      }
  }
  ```

  ```js Node theme={null}
  class BoxFolderTreeBuilder {
      constructor(boxClient, options) {
          options = options || {};
          boxClient._useIterators = true;
          this.boxClient = boxClient;
          this.maxDepth = options.maxDepth || -1;
          this.rootFolderId = options.rootFolderId || "0";
      }

      async buildFolderTreeWithFlatLists() {
          let tree = {
              rootId: this.rootFolderId,
              folders: [],
              files: []
          }
          let folderItemsIterator = await this.boxClient.folders.getItems(this.rootFolderId);
          let collection = await BoxUtilities.autoPage(folderItemsIterator);
          let rootFolderChildren = [];

          const path = `${this.rootFolderId}`;
          collection.forEach((item) => {
              if (item.type === "file") {
                  tree.files.push({
                      item,
                      path
                  })
              } else if (item.type === "folder") {
                  let folderTreeFolder = {
                      item,
                      path,
                      children: []
                  }
                  tree.folders.push(folderTreeFolder);
                  rootFolderChildren.push(folderTreeFolder);
              }
          });
          tree = await this.dive(tree, rootFolderChildren, 1);
          return tree;
      }

      async dive(tree, children, currentDepth) {
          if (this.inTooDeep(currentDepth)) {
              return tree;
          } else {
              currentDepth++;
              let additionalChildren = [];
              let childrenPromises = [];
              children.forEach((child) => {
                  let foundFolder = -1;
                  childrenPromises.push(this.boxClient.folders.getItems(child.item.id)
                      .then((folderItemsIterator) => {
                          return BoxUtilities.autoPage(folderItemsIterator)
                              .then((collection) => {
                                  for (let i = 0; i < tree.folders.length; i++) {
                                      if (child.item.id === tree.folders[i].item.id) {
                                          foundFolder = i;
                                      }
                                  }

                                  const path = `${child.path}/${child.item.id}`;
                                  collection.forEach((item) => {
                                      if (foundFolder >= 0) {
                                          tree.folders[foundFolder].children.push(item);
                                      }

                                      if (item.type === "file") {
                                          tree.files.push({
                                              item,
                                              path
                                          })
                                      } else if (item.type === "folder") {
                                          let folderTreeFolder = {
                                              item,
                                              path,
                                              children: []
                                          }
                                          tree.folders.push(folderTreeFolder);
                                          additionalChildren.push(folderTreeFolder);
                                      }
                                  });
                                  return;
                              });
                      }));
              });
              await Promise.all(childrenPromises);
              if (additionalChildren.length === 0) {
                  return tree;
              } else {
                  return this.dive(tree, additionalChildren, currentDepth);
              }
          }
      }

      inTooDeep(depthCount) {
          if (this.maxDepth < 0) {
              return false;
          } else {
              return (depthCount >= this.maxDepth);
          }
      }
  }

  class BoxUtilities {
      static async autoPage(iterator, collection = []) {
          let moveToNextItem = async () => {
              let item = await iterator.next();
              if (item.value) {
                  collection.push(item.value);
              }

              if (item.done !== true) {
                  return moveToNextItem();
              } else {
                  return collection;
              }
          }
          return moveToNextItem();
      }
  }

  let folderTreeBuilder = new BoxFolderTreeBuilder(client);
  folderTreeBuilder.buildFolderTreeWithFlatLists()
      .then((tree) => {
          console.log(JSON.stringify(tree));
      })
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Change Folder Owner
Source: https://developer.box.com/guides/folders/single/change-owner



<RelatedLinks title="REQUIRED GUIDES" />

To change the owner of a folder, first invite the user you wish to
transfer the folder to as a collaborator on the folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/collaborations" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "item": {
           "type": "file",
           "id": "11446498"
         },
         "accessible_by": {
           "type": "user",
           "login": "user@example.com"
         },
         "role": "editor"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.userCollaborations.createCollaboration({
    item: {
      type: 'folder' as CreateCollaborationRequestBodyItemTypeField,
      id: folder.id,
    } satisfies CreateCollaborationRequestBodyItemField,
    accessibleBy: {
      type: 'user' as CreateCollaborationRequestBodyAccessibleByTypeField,
      id: user.id,
    } satisfies CreateCollaborationRequestBodyAccessibleByField,
    role: 'editor' as CreateCollaborationRequestBodyRoleField,
  } satisfies CreateCollaborationRequestBody);
  ```

  ```python Python v10 theme={null}
  client.user_collaborations.create_collaboration(
      CreateCollaborationItem(type=CreateCollaborationItemTypeField.FOLDER, id=folder.id),
      CreateCollaborationAccessibleBy(
          type=CreateCollaborationAccessibleByTypeField.USER, id=user.id
      ),
      CreateCollaborationRole.EDITOR,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.UserCollaborations.CreateCollaborationAsync(requestBody: new CreateCollaborationRequestBody(item: new CreateCollaborationRequestBodyItemField() { Type = CreateCollaborationRequestBodyItemTypeField.Folder, Id = folder.Id }, accessibleBy: new CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.User) { Id = user.Id }, role: CreateCollaborationRequestBodyRoleField.Editor));
  ```

  ```swift Swift v10 theme={null}
  try await client.userCollaborations.createCollaboration(requestBody: CreateCollaborationRequestBody(item: CreateCollaborationRequestBodyItemField(type: CreateCollaborationRequestBodyItemTypeField.folder, id: folder.id), accessibleBy: CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.user, id: user.id), role: CreateCollaborationRequestBodyRoleField.editor))
  ```

  ```java Java v10 theme={null}
  client.getUserCollaborations().createCollaboration(new CreateCollaborationRequestBody(new CreateCollaborationRequestBodyItemField.Builder().type(CreateCollaborationRequestBodyItemTypeField.FOLDER).id(folder.getId()).build(), new CreateCollaborationRequestBodyAccessibleByField.Builder(CreateCollaborationRequestBodyAccessibleByTypeField.USER).id(user.getId()).build(), CreateCollaborationRequestBodyRoleField.EDITOR))
  ```

  ```java Java v5 theme={null}
  BoxCollaborator user = new BoxUser(api, "user-id")
  BoxFolder folder = new BoxFolder(api, "folder-id");
  folder.collaborate(user, BoxCollaboration.Role.EDITOR);
  ```

  ```python Python v4 theme={null}
  from boxsdk.object.collaboration import CollaborationRole

  user = client.user(user_id='11111')
  collaboration = client.folder(folder_id='22222').collaborate(user, CollaborationRole.VIEWER)

  collaborator = collaboration.accessible_by
  item = collaboration.item
  has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
  print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')
  ```

  ```cs .NET v6 theme={null}
  // collaborate folder 11111 with user 22222
  BoxCollaborationRequest requestParams = new BoxCollaborationRequest()
  {
      Item = new BoxRequestEntity()
      {
          Type = BoxType.folder,
          Id = "11111"
      },
      Role = "editor",
      AccessibleBy = new BoxCollaborationUserRequest()
      {
          Type = BoxType.user,
          Id = "22222"
      }
  };
  BoxCollaboration collab = await client.CollaborationsManager.AddCollaborationAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  // Invite user 123456 to collaborate on folder 987654
  client.collaborations.createWithUserID('123456', '987654', client.collaborationRoles.EDITOR)
  	.then(collaboration => {
  		/* collaboration -> {
  			type: 'collaboration',
  			id: '11111',
  			created_by: 
  			{ type: 'user',
  				id: '22222',
  				name: 'Inviting User',
  				login: 'inviter@example.com' },
  			created_at: '2016-11-16T21:33:31-08:00',
  			modified_at: '2016-11-16T21:33:31-08:00',
  			expires_at: null,
  			status: 'accepted',
  			accessible_by: 
  			{ type: 'user',
  				id: '123456',
  				name: 'Collaborator User',
  				login: 'collaborator@example.com' },
  			role: 'editor',
  			acknowledged_at: '2016-11-16T21:33:31-08:00',
  			item: 
  			{ type: 'folder',
  				id: '987654',
  				sequence_id: '0',
  				etag: '0',
  				name: 'Collaborated Folder' } }
  		*/
  	});
  ```
</CodeGroup>

Then, update the created collaboration by changing the role of
that invited user to `owner`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X PUT https://api.box.com/2.0/collaborations/1234 \
      -H "authorization: Bearer <ACCESS_TOKEN>" \
      -H "content-type: application/json" \
      -d '{
        "role": "owner"
      }'
  ```

  ```csharp .NET theme={null}
  BoxCollaborationRequest requestParams = new BoxCollaborationRequest()
  {
      Id = "12345",
      Role = "owner"
  };
  BoxCollaboration collab = await client.CollaborationsManager.EditCollaborationAsync(requestParams);
  ```

  ```java Java theme={null}
  Collection<BoxCollaboration.Info> pendingCollaborations = BoxCollaboration.getPendingCollaborations(api);
  for (BoxCollaboration.Info collabInfo : pendingCollaborations) {
      collabInfo.setRole(BoxCollaboration.Role.OWNER);
      collabInfo.getResource().updateInfo(collabInfo);
  }
  ```

  ```python Python theme={null}
  from boxsdk.object.collaboration import CollaborationRole, CollaborationStatus

  collaboration = client.collaboration(collab_id='12345')
  updated_collaboration = collaboration.update_info(CollaborationRole.OWNER)
  ```

  ```js Node theme={null}
  client.collaborations.update('12345', {role: client.collaborationRoles.OWNER})
      .then(collaboration => {
          // ...
      });
  ```
</CodeGroup>

<Warning>
  Depending on the settings, a user with access to a folder might be able to
  invite other users, yet in all cases only the current owner of a folder can
  transfer the ownership.
</Warning>


# Create Folder Lock
Source: https://developer.box.com/guides/folders/single/create-lock



To create a lock on a folder in Box you will need to provide our API with the
`id` of the folder for which the lock should be applied. Optionally you may
supply the specific `locked_operations` to be applied with the folder lock.

<Note>
  **Folder Locks**

  When using any folder lock API endpoints, you must be authenticated as the
  owner/co-owner of the folder you are trying to access.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/folder_locks" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "folder": {
           "type": "folder",
           "id": "33552487093"
         },
         "locked_operations": {
           "move": true,
           "delete": true
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderLocks.createFolderLock({
    folder: {
      id: folder.id,
      type: 'folder',
    } satisfies CreateFolderLockRequestBodyFolderField,
    lockedOperations: {
      move: true,
      delete: true,
    } satisfies CreateFolderLockRequestBodyLockedOperationsField,
  } satisfies CreateFolderLockRequestBody);
  ```

  ```python Python v10 theme={null}
  client.folder_locks.create_folder_lock(
      CreateFolderLockFolder(id=folder.id, type="folder"),
      locked_operations=CreateFolderLockLockedOperations(move=True, delete=True),
  )
  ```

  ```cs .NET v10 theme={null}
  await client.FolderLocks.CreateFolderLockAsync(requestBody: new CreateFolderLockRequestBody(folder: new CreateFolderLockRequestBodyFolderField(id: folder.Id, type: "folder")) { LockedOperations = new CreateFolderLockRequestBodyLockedOperationsField(move: true, delete: true) });
  ```

  ```swift Swift v10 theme={null}
  try await client.folderLocks.createFolderLock(requestBody: CreateFolderLockRequestBody(folder: CreateFolderLockRequestBodyFolderField(id: folder.id, type: "folder"), lockedOperations: CreateFolderLockRequestBodyLockedOperationsField(move: true, delete: true)))
  ```

  ```java Java v10 theme={null}
  client.getFolderLocks().createFolderLock(new CreateFolderLockRequestBody.Builder(new CreateFolderLockRequestBodyFolderField("folder", folder.getId())).lockedOperations(new CreateFolderLockRequestBodyLockedOperationsField(true, true)).build())
  ```
</CodeGroup>

<Warning>
  **Setting Locked Operations**

  If the `locked_operations` object is included with a folder lock request,
  both `move` and `delete` need to be set to `true`. Supplying only one lock
  operation in the object, or setting the values of both to something other
  than `true` will produce an error. These options are in place to allow
  for additional operations in the future.
</Warning>

## Lock Operations

There are two possible lock operations that may be applied to a folder, `move`
and `delete`.

The `move` lock will prevent the folder from being moved to a new location or
owner while the lock is still applied.

The `delete` lock will prevent the folder from being deleted while the lock is
still applied.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete Folder
Source: https://developer.box.com/guides/folders/single/delete



<RelatedLinks title="REQUIRED GUIDES" />

To remove a folder in Box you will need to provide our API with the ID of the
folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/folders/4353455" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folders.deleteFolderById(newFolder.id);
  ```

  ```python Python v10 theme={null}
  client.folders.delete_folder_by_id(new_folder.id)
  ```

  ```cs .NET v10 theme={null}
  await client.Folders.DeleteFolderByIdAsync(folderId: newFolder.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.folders.deleteFolderById(folderId: newFolder.id)
  ```

  ```java Java v10 theme={null}
  client.getFolders().deleteFolderById(newFolder.getId())
  ```

  ```java Java v5 theme={null}
  // Delete the folder and all its contents
  BoxFolder folder = new BoxFolder(api, "id");
  folder.delete(true);
  ```

  ```python Python v4 theme={null}
  client.folder(folder_id='22222').delete()
  ```

  ```cs .NET v6 theme={null}
  await client.FoldersManager.DeleteAsync("11111", recursive: true);
  ```

  ```javascript Node v4 theme={null}
  client.folders.delete('12345', {recursive: true})
      .then(() => {
          // deletion succeeded — no value returned
      });
  ```
</CodeGroup>

## Deleting non-empty folders

This API returns an error if the folder is not empty. When deleting a
folder, you can pass in the `recursive` parameter to force a
folder to be deleted even if it is not empty. This will delete all
items within this folder, including any of their descendants.

## Folder locking

The enterprise settings determine whether the folder will
be permanently deleted from Box or moved to the trash.

During this operation, part of the file tree will be locked, mainly
the source folder and all of its descendants.

For the duration of the operation, no other move, copy, delete, or restore
operation can be performed on any of the locked folders.

## Timeout

Timeout for this operation is 600 seconds. The operation will complete
after an `HTTP 503` has been returned.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete Folder Lock
Source: https://developer.box.com/guides/folders/single/delete-lock



To remove a lock applied to a folder in Box, call the
`DELETE /folder_locks/:id` API with the id of the folder lock.

<Note>
  **Folder Locks**

  When using any folder lock API endpoints, you must be authenticated as the
  owner/co-owner of the folder you are trying to access.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/folder_locks/93134" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderLocks.deleteFolderLockById(folderLock.id!);
  ```

  ```python Python v10 theme={null}
  client.folder_locks.delete_folder_lock_by_id(folder_lock.id)
  ```

  ```cs .NET v10 theme={null}
  await client.FolderLocks.DeleteFolderLockByIdAsync(folderLockId: NullableUtils.Unwrap(folderLock.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.folderLocks.deleteFolderLockById(folderLockId: folderLock.id!)
  ```

  ```java Java v10 theme={null}
  client.getFolderLocks().deleteFolderLockById(folderLock.getId())
  ```
</CodeGroup>

<Note>
  **Locating the folder Lock ID**

  To delete a folder lock you must supply the folder lock ID to the API. A
  folder lock ID is supplied in the response when
  <Link href="/guides/folders/single/create-lock">creating a folder lock</Link>, or
  when <Link href="/guides/folders/single/get-locks">listing locks</Link> on a given folder.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get Folder Lock
Source: https://developer.box.com/guides/folders/single/get-locks



To get a list of the current locks on a folder in Box, call the
`GET /folder_locks/` API with the id of the folder supplied as a `folder_id`
query string parameter.

<Note>
  **Folder Locks**

  When using any folder lock API endpoints, you must be authenticated as the
  owner/co-owner of the folder you are trying to access.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/folder_locks?folder_id=33552487093" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderLocks.getFolderLocks({
    folderId: folder.id,
  } satisfies GetFolderLocksQueryParams);
  ```

  ```python Python v10 theme={null}
  client.folder_locks.get_folder_locks(folder.id)
  ```

  ```cs .NET v10 theme={null}
  await client.FolderLocks.GetFolderLocksAsync(queryParams: new GetFolderLocksQueryParams(folderId: folder.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.folderLocks.getFolderLocks(queryParams: GetFolderLocksQueryParams(folderId: folder.id))
  ```

  ```java Java v10 theme={null}
  client.getFolderLocks().getFolderLocks(new GetFolderLocksQueryParams(folder.getId()))
  ```
</CodeGroup>

## Folder ID

The `id` of any folder can be determined by visiting a folder in the web
application and copying the `id` from the URL. For example, for the URL
`https://*.app.box.com/folder/123` the `folder_id` is `123`.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Download File Representation
Source: https://developer.box.com/guides/representations/download-a-representation



<RelatedLinks title="REQUIRED GUIDES" />

Use the `url_template` that was received when
<Link href="/guides/representations/request-a-representation">selecting the representation</Link> to download
the representation. Replace the `{+asset_path}` depending on
the type of representation.

## Paginated representations

For paged representations like PDFs replace `{+asset_path}`
with the desired page number and the file extension, for example
`1.pdf`.

```sh theme={null}
curl https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/pdf/content/3.pdf \
    -H "authorization: Bearer ACCESS_TOKEN"
```

## Non-paginated representations

For non-paged representations, replace the `{+asset_path}` with
an empty string.

```sh theme={null}
curl https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/jpg_32x32/content/ \
    -H "authorization: Bearer ACCESS_TOKEN"
```

## Optional query parameters

When fetching the representation the following optional headers
are supported.

| Parameter | Options | Default |
| - | - | - |
| `set_content_disposition_type` | `inline` / `attachment` | `null` |

Sets the `content-disposition` header in the API response with the specified
value. A disposition type of `attachment` causes most web browsers to prompt
the user to save the response to their device, where the type `inline`
will open the file in the browser.

If not supplied, the `content-disposition` header is not included in the
response.

| Parameter | Options | Default |
| - | - | - |
| `set_content_disposition_filename` | Filename without extension | `null` |

Allows the application to define the downloaded representation's file name.

If not defined, the file name is derived from the source file name in Box,
replacing the extension with the representation's file type.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Representations
Source: https://developer.box.com/guides/representations/index



A representation is an alternative asset for a file stored in Box. These assets
can be PDFs, thumbnails, or text extractions. Representations allow you to access content in different formats without manually converting files, such as by extracting text from documents to send to language models for processing.

Representations are automatically generated for the supported file types, either
when uploading to Box or when requesting the asset.

These representations are exposed through the `GET /files/:id` endpoint by using
the `fields=representations` query parameter and the `x-rep-hints` header.

The workflow involves:

1. <Link href="/guides/representations/list-all-representations">Getting the list of available representations for a file.</Link>
2. <Link href="/guides/representations/request-a-representation">Checking a specific representation's status and retrieving its `url_template`.</Link>
3. <Link href="/guides/representations/download-a-representation">Downloading the representation if available.</Link>


# List All Representations for File
Source: https://developer.box.com/guides/representations/list-all-representations



To see what representations are available for a file you can call the
<Link href="/reference/get-files-id">`GET /files/:id`</Link> endpoint while requesting the
<Link href="/reference/resources/file#param-representations">`representations`</Link> field.

```sh theme={null}
curl https://api.box.com/2.0/files/123?fields=representations \
    -H "authorization: Bearer ACCESS_TOKEN"
```

The response will include a list of representations in the following format

```json theme={null}
...
{
  "info": {
    "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/jpg_thumb_32x32"
  },
  "properties": {
      "dimensions": "32x32",
      "paged": "false",
      "thumb": "true"
  },
  "representation": "jpg"
}
...
```

## Response fields

Every representation will include a set of properties and the type of
representation.

* The optional `dimensions` field represents the file's dimensions in pixels as width by height.

* The optional `paged` field specifies if this representation is a paged document. Some images and PDFs will often be paged documents.

* The optional `thumb` field specifies if this representation is suitable as a file thumbnail.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get Markdown Representation
Source: https://developer.box.com/guides/representations/markdown

Generate and download Markdown representations using the Box API.

<RelatedLinks title="REQUIRED GUIDES" />

A markdown representation provides a way to extract text from a document while retaining structures such as headers, tables, lists, and formatting cues. Markdown conversion speeds depend on file size and content.

## Supported file types

Markdown representations work with the following document formats:

* Microsoft Office: Word (.docx), PowerPoint (.pptx), Excel (.xls, .xlsx, .xlsm)
* Google Workspace: Google Docs (.gdoc), Google Slides (.gslide, .gslides), Google Sheets (.gsheet)
* PDF files (.pdf)

## Create a markdown representation

This process describes how to generate and download a Markdown representation of a file using the Box API.

To first create a markdown representation:

* <Link href="/guides/representations/list-all-representations">Get the list of representations available for a file</Link>
* <Link href="/guides/representations/request-a-representation">Request a markdown representation</Link> by passing the `x-rep-hints`-header with the value `[markdown]`.
* <Link href="/guides/representations/download-a-representation">Download the markdown</Link> by calling the `url_template`, replacing the `{+asset_path}` with an empty string.

Generated representations are cached by Box for subsequent requests.

### Get available representations

Request the file’s available representations, specifying a Markdown representation hint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X GET \ 
    'https://api.box.com/2.0/files/12345?fields=id%2Cname%2Crepresentations' \ 
    -H 'X-Rep-Hints: [markdown]' \ 
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.files.getFileById(
    "12345",
    {
      queryParams: {
        fields: ["id", "name", "representations"],
      } satisfies GetFileByIdQueryParams,
      headers: {
        xRepHints: "[markdown]",
      } satisfies GetFileByIdHeadersInput,
    } satisfies GetFileByIdOptionalsInput,
  );
  ```

  ```python Python v10 theme={null}
  client.files.get_file_by_id(
      "12345",
      fields=["id", "name", "representations"],
      x_rep_hints="[markdown]",
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Files.GetFileByIdAsync(
      fileId: "12345",
      queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"id", "name", "representations"}) },
      headers: new GetFileByIdHeaders(xRepHints: "[markdown]")
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.files.getFileById(
      fileId: "12345",
      queryParams: GetFileByIdQueryParams(fields: ["id", "name", "representations"]),
      headers: GetFileByIdHeaders(xRepHints: "[markdown]")
  )
  ```

  ```java Java v10 theme={null}
  client.getFiles().getFileById(
      "12345",
      new GetFileByIdQueryParams.Builder().fields(Arrays.asList("id", "name", "representations")).build(),
      new GetFileByIdHeaders("[markdown]")
  )
  ```
</CodeGroup>

## Response example

```json theme={null}
{
  "type": "file",
  "id": "{file_id}",
  "etag": "1",
  "name": "test.docx",
  "representations": {
    "entries": [
      {
        "representation": "markdown",
        "properties": {},
        "info": {
          "url": "https://api.box.com/2.0/internal_files/{file_id}/versions/{version_id}/representations/{representation}"
        },
        "status": {
          "state": "none"
        },
        "content": {
          "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/{file_id}/versions/{version_id}/representations/{representation}/content/{+asset_path}"
        }
      }
    ]
  }
}
```

### Trigger Markdown generation

If the state is `none`, request the info URL to begin generating the Markdown representation.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X GET \ 
    'https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown' \ 
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await fetch(
    "https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown",
    {
      headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
    },
  );
  ```

  ```python Python v10 theme={null}
  requests.get(
      "https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown",
      headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
  )
  ```

  ```cs .NET v10 theme={null}
  using var httpClient = new HttpClient();
  httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");
  await httpClient.GetAsync("https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown");
  ```

  ```swift Swift v10 theme={null}
  var request = URLRequest(url: URL(string: "https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown")!)
  request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
  _ = try await URLSession.shared.data(for: request)
  ```

  ```java Java v10 theme={null}
  HttpClient httpClient = HttpClient.newHttpClient();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown"))
      .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
      .GET()
      .build();
  httpClient.send(request, HttpResponse.BodyHandlers.discarding());
  ```
</CodeGroup>

### Check representation status

Re-query the file to check the current status of the Markdown representation.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X GET \ 
    'https://api.box.com/2.0/files/12345?fields=id%2Cname%2Crepresentations' \ 
    -H 'X-Rep-Hints: [markdown]' \ 
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.files.getFileById(
    "12345",
    {
      queryParams: {
        fields: ["id", "name", "representations"],
      } satisfies GetFileByIdQueryParams,
      headers: {
        xRepHints: "[markdown]",
      } satisfies GetFileByIdHeadersInput,
    } satisfies GetFileByIdOptionalsInput,
  );
  ```

  ```python Python v10 theme={null}
  client.files.get_file_by_id(
      "12345",
      fields=["id", "name", "representations"],
      x_rep_hints="[markdown]",
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Files.GetFileByIdAsync(
      fileId: "12345",
      queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"id", "name", "representations"}) },
      headers: new GetFileByIdHeaders(xRepHints: "[markdown]")
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.files.getFileById(
      fileId: "12345",
      queryParams: GetFileByIdQueryParams(fields: ["id", "name", "representations"]),
      headers: GetFileByIdHeaders(xRepHints: "[markdown]")
  )
  ```

  ```java Java v10 theme={null}
  client.getFiles().getFileById(
      "12345",
      new GetFileByIdQueryParams.Builder().fields(Arrays.asList("id", "name", "representations")).build(),
      new GetFileByIdHeaders("[markdown]")
  )
  ```
</CodeGroup>

When the status changes from `pending` to `success`, the Markdown file is ready to download. The status indicates if the representation is available. Available options are `success`, `viewable`, `pending`, or `none`. `Success` means you can immediately download the representation, while `none` indicates the representation can be generated.

### Download the Markdown representation

Once the representation is ready, use the `content/url_template` to download it.

<CodeGroup>
  ```sh cURL theme={null}
  curl -L \ 
  'https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/1415005153353/representations/markdown/content/index.md' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -o file_name.md
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await fetch(
    "https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/",
    {
      headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
    },
  );
  ```

  ```python Python v10 theme={null}
  requests.get(
      "https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/",
      headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
  )
  ```

  ```cs .NET v10 theme={null}
  using var httpClient = new HttpClient();
  httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");
  await httpClient.GetAsync("https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/");
  ```

  ```swift Swift v10 theme={null}
  var request = URLRequest(url: URL(string: "https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/")!)
  request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
  _ = try await URLSession.shared.data(for: request)
  ```

  ```java Java v10 theme={null}
  HttpClient httpClient = HttpClient.newBuilder()
      .followRedirects(HttpClient.Redirect.NORMAL)
      .build();
  HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/"))
      .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
      .GET()
      .build();
  httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray());
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get PDF Representation
Source: https://developer.box.com/guides/representations/pdf



<RelatedLinks title="REQUIRED GUIDES" />

A PDF representation provides a predictable way to embed documents
in mobile and web applications. PDF representations support watermarks
if the original file has been watermarked.

PDF representations are generated upon uploading the source file to Box, though
a watermarked PDF is generated upon fetching the watermarked file for
the first time.

## The process

To get a PDF representation follow the following steps

* <Link href="/guides/representations/list-all-representations">List all representations</Link>
* <Link href="/guides/representations/request-a-representation">Request a PDF</Link> by passing the `x-rep-hints`-header for the desired file type `[pdf]`.
* <Link href="/guides/representations/download-a-representation">Download the PDF</Link> by calling the `url_template`, replacing the `{+asset_path}` with the page of the PDF to request, for example `1.pdf`.

## Watermarked PDFs

To retrieve a watermarked PDF the underlying file itself needs to be
watermarked in Box. You can watermark a file either via the Box web application
or using the <Link href="/reference/put-files-id-watermark">`PUT /files/:id/watermark/`</Link> API.

Once watermarked, a watermarked PDF representation of the file is generated.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Request Desired Representation
Source: https://developer.box.com/guides/representations/request-a-representation



<RelatedLinks title="REQUIRED GUIDES" />

To select a specific representation call the <Link href="/reference/get-files-id">`GET /files/:id`</Link>
endpoint with a <Link href="/reference/get-files-id#param-x-rep-hints">`x-rep-hints`</Link>-header defining the
required representation format.

```sh theme={null}
curl https://api.box.com/2.0/files/123?fields=representations \
    -H "x-rep-hints: [pdf]" \
    -H "authorization: Bearer ACCESS_TOKEN"
```

When the status changes from `pending` to `success`, the representation is ready to download. The status indicates if the representation is available. Available options are `success`, `viewable`, `pending`, or `none`. `Success` means you can immediately download the representation, while `none` indicates the representation can be generated.

## Multiple dimensions

Some formats will require the `dimensions` to be passed in to select a
specific size. This can be achieved by appending the `dimensions` to the
header.

```sh theme={null}
curl https://api.box.com/2.0/files/123?fields=representations \
    -H "x-rep-hints: [jpg?dimensions=94x94]" \
    -H "authorization: Bearer ACCESS_TOKEN"
```

## Multiple representations

Multiple representations can be fetched by chaining the different
types in the `x-rep-hints`-header.

```sh theme={null}
curl https://api.box.com/2.0/files/123?fields=representations \
    -H "x-rep-hints: [pdf][jpg?dimensions=94x94]" \
    -H "authorization: Bearer ACCESS_TOKEN"
```

## API Response

This API call will result in one or more representations with a `url_template`
value that includes a `{+asset_path}` value.

```json theme={null}
{
  "etag": "1",
  "id": "123",
  "representations": {
    "entries": [
      {
        "content": {
          "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/pdf/content/{+asset_path}"
        },
        "info": {
          "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/pdf"
        },
        "properties": {},
        "representation": "pdf",
        "status": {
          "state": "success"
        }
      }
    ]
  },
  "type": "file"
}
```

<Note>
  The `url_template` in this response is an **opaque** URL. This URL format
  might change over time and no assumptions should be made about its format
  except for the presence of the `{+asset_path}` variable.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Supported File Types
Source: https://developer.box.com/guides/representations/supported-file-types



The following file types are supported by the representation API.

## 3D Graphics and Modeling Files

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.3ds` | No | No | No | No |
| `.box3d` | No | No | No | No |
| `.dae` | No | No | No | No |
| `.fbx` | No | No | No | No |
| `.mtl` | No | No | No | No |
| `.obj` | No | No | No | No |
| `.ply` | No | No | No | No |
| `.stl` | No | No | No | No |

## Audio

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.aac` | No | No | No | No |
| `.aif` | No | No | No | No |
| `.aifc` | No | No | No | No |
| `.aiff` | No | No | No | No |
| `.amr` | No | No | No | No |
| `.au` | No | No | No | No |
| `.flac` | No | No | No | No |
| `.m4a` | No | No | No | No |
| `.mp3` | No | No | No | No |
| `.ogg` | No | Yes | No | No |
| `.ra` | No | No | No | No |
| `.wav` | No | No | No | No |
| `.wma` | No | No | No | No |

## CAD

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.dwg` | Yes | Yes | No | No |

## Documents

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.boxnote` | No | No | Yes | No |
| `.doc` | Yes | Yes | Yes | No |
| `.docx` | Yes | Yes | Yes | Yes |
| `.gdoc` | Yes | Yes | Yes | Yes |
| `.html` | Yes | No | Yes | No |
| `.msg` | Yes | No | Yes | No |
| `.odt` | Yes | Yes | Yes | No |
| `.pages` | Yes | Yes | No | No |
| `.pdf` | Yes | Yes | Yes | Yes |
| `.rtf` | Yes | Yes | Yes | No |
| `.wpd` | Yes | Yes | Yes | No |
| `.xhtml` | Yes | No | Yes | No |
| `.xml` | Yes | No | Yes | No |
| `.xsd` | Yes | No | Yes | No |
| `.xsl` | Yes | No | Yes | No |
| `.xbd` | Yes | Yes | Yes | No |
| `.xdw` | Yes | Yes | Yes | No |

## Drawing

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.ai` | No | Yes | No | No |
| `.boxcanvas` | No | No | Yes | No |
| `.indd` | Yes | Yes | No | No |
| `.psd` | No | Yes | No | No |
| `.svg` | No | Yes | No | No |

## Image

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.bmp` | No | Yes | No | No |
| `.cr2` | No | Yes | No | No |
| `.crw` | No | Yes | No | No |
| `.dcm` | No | Yes | No | No |
| `.dicm` | No | Yes | No | No |
| `.dicom` | No | Yes | No | No |
| `.dng` | No | Yes | No | No |
| `.eps` | No | Yes | No | No |
| `.gif` | No | Yes | No | No |
| `.heic` | No | Yes | No | No |
| `.indd` | Yes | Yes | No | No |
| `.idml` | Yes | Yes | No | No |
| `.indt` | Yes | Yes | No | No |
| `.inx` | Yes | Yes | No | No |
| `.jpeg` | No | Yes | No | No |
| `.jpg` | No | Yes | No | No |
| `.nef` | No | Yes | No | No |
| `.png` | No | Yes | No | No |
| `.ps` | No | Yes | No | No |
| `.psd` | No | Yes | No | No |
| `.raf` | No | Yes | No | No |
| `.raw` | No | Yes | No | No |
| `.svg` | No | Yes | No | No |
| `.svs` | No | Yes | No | No |
| `.tif` | No | Yes | No | No |
| `.tiff` | No | Yes | No | No |
| `.tga` | No | Yes | No | No |
| `.webp` | No | Yes | No | No |

## Presentation

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.gslide` | Yes | Yes | Yes | Yes |
| `.gslides` | Yes | Yes | Yes | Yes |
| `.key` | Yes | Yes | No | No |
| `.odp` | Yes | Yes | Yes | No |
| `.otp` | Yes | Yes | Yes | No |
| `.ppt` | Yes | Yes | Yes | No |
| `.pptx` | Yes | Yes | Yes | Yes |

## Spreadsheet

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.csv` | Yes | Yes | Yes | No |
| `.gsheet` | Yes | Yes | Yes | Yes |
| `.numbers` | Yes | Yes | No | No |
| `.ods` | Yes | Yes | Yes | No |
| `.tsv` | Yes | Yes | Yes | No |
| `.xls` | Yes | Yes | Yes | Yes |
| `.xlsm` | Yes | Yes | Yes | Yes |
| `.xlsx` | Yes | Yes | Yes | Yes |

## Text-Based Files

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.as` | Yes | No | Yes | No |
| `.as3` | Yes | No | Yes | No |
| `.asm` | Yes | No | Yes | No |
| `.bat` | Yes | No | Yes | No |
| `.c` | Yes | No | Yes | No |
| `.cc` | Yes | No | Yes | No |
| `.cmake` | Yes | No | Yes | No |
| `.cpp` | Yes | No | Yes | No |
| `.cs` | Yes | No | Yes | No |
| `.css` | Yes | No | Yes | No |
| `.cxx` | Yes | No | Yes | No |
| `.diff` | Yes | No | Yes | No |
| `.erb` | Yes | No | Yes | No |
| `.fdx` | Yes | No | Yes | No |
| `.groovy` | Yes | No | Yes | No |
| `.h` | Yes | No | Yes | No |
| `.haml` | Yes | No | Yes | No |
| `.hh` | Yes | No | Yes | No |
| `.java` | Yes | No | Yes | No |
| `.js` | Yes | No | Yes | No |
| `.json` | Yes | No | Yes | No |
| `.less` | Yes | No | Yes | No |
| `.log` | Yes | No | Yes | No |
| `.m` | Yes | No | Yes | No |
| `.make` | Yes | No | Yes | No |
| `.md` | Yes | No | Yes | No |
| `.ml` | Yes | No | Yes | No |
| `.mm` | Yes | No | Yes | No |
| `.php` | Yes | No | Yes | No |
| `.pl` | Yes | No | Yes | No |
| `.plist` | Yes | No | Yes | No |
| `.properties` | Yes | No | Yes | No |
| `.py` | Yes | No | Yes | No |
| `.rb` | Yes | No | Yes | No |
| `.rst` | Yes | No | Yes | No |
| `.sass` | Yes | No | Yes | No |
| `.scala` | Yes | No | Yes | No |
| `.scm` | Yes | No | Yes | No |
| `.script` | Yes | No | Yes | No |
| `.sh` | Yes | No | Yes | No |
| `.sml` | Yes | No | Yes | No |
| `.sql` | Yes | No | Yes | No |
| `.txt` | Yes | No | Yes | No |
| `.vi` | Yes | No | Yes | No |
| `.vim` | Yes | No | Yes | No |
| `.vtt` | Yes | No | Yes | No |
| `.webdoc` | Yes | No | Yes | No |
| `.yaml` | Yes | No | Yes | No |

## Video

| File Type | PDF Support? | Thumbnails? | Text? | Markdown? |
| - | - | - | - | - |
| `.3g2` | No | Yes | No | No |
| `.3gp` | No | Yes | No | No |
| `.avi` | No | Yes | No | No |
| `.flv` | No | Yes | No | No |
| `.m2v` | No | Yes | No | No |
| `.m2ts` | No | Yes | No | No |
| `.m4v` | No | Yes | No | No |
| `.mkv` | No | Yes | No | No |
| `.mov` | No | Yes | No | No |
| `.mp4` | No | Yes | No | No |
| `.mpeg` | No | Yes | No | No |
| `.mpg` | No | Yes | No | No |
| `.mts` | No | Yes | No | No |
| `.ogg` | No | Yes | No | No |
| `.qt` | No | Yes | No | No |
| `.ts` | No | Yes | No | No |
| `.swf` | No | Yes | No | No |
| `.wmv` | No | Yes | No | No |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get Text Representation
Source: https://developer.box.com/guides/representations/text



<RelatedLinks title="REQUIRED GUIDES" />

A text representation provides a way to extract plain text
from a document.

Text is generated for all document file types including plain text and
code files supported by Box. This does not include image files as these
do not have a text layer.

Text representations are generated upon upload of the file, similarly to PDFs
and thumbnails. They are not generated for files larger than 500
megabytes.

## The process

To get a text representation follow the following steps

* <Link href="/guides/representations/list-all-representations">List all representations</Link>
* <Link href="/guides/representations/request-a-representation">Request a text representation</Link> by passing the `x-rep-hints`-header with the value `[extracted_text]`.
* <Link href="/guides/representations/download-a-representation">Download the text</Link> by calling the `url_template`, replacing the `{+asset_path}` with an empty string.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get Basic Thumbnail
Source: https://developer.box.com/guides/representations/thumbnail



<RelatedLinks title="REQUIRED GUIDES" />

A thumbnail is a small image, either as `.png` or as `.jpg` that can be used in
an application as a representation of the file, for example as a placeholder for
a link that downloads or previews the file.

<Info>
  The preferred way to get a thumbnail for a file is using the
  <Link href="/guides/representations/thumbnail-representation">representations API</Link>.
</Info>

## Requesting

To request a file thumbnail use the <Link href="/reference/get-files-id-thumbnail-id">`GET
/files/:id/thumbnail.:extension`</Link>
endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/files/12345/thumbnail.png" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.files.getFileThumbnailById(
    thumbnailFile.id,
    'png' as GetFileThumbnailByIdExtension,
  );
  ```

  ```python Python v10 theme={null}
  client.files.get_file_thumbnail_by_id(
      thumbnail_file.id, GetFileThumbnailByIdExtension.PNG
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Files.GetFileThumbnailByIdAsync(fileId: thumbnailFile.Id, extension: GetFileThumbnailByIdExtension.Png);
  ```

  ```swift Swift v10 theme={null}
  try await client.files.getFileThumbnailById(fileId: thumbnailFile.id, extension_: GetFileThumbnailByIdExtension.png, downloadDestinationUrl: destinationPath)
  ```

  ```java Java v10 theme={null}
  client.getFiles().getFileThumbnailById(thumbnailFile.getId(), GetFileThumbnailByIdExtension.PNG)
  ```

  ```python Python v4 theme={null}
  file_id = '11111'

  thumbnail = client.file(file_id).get_thumbnail_representation('92x92', extension='jpg')
  ```

  ```cs .NET v6 theme={null}
  Stream thumbnailContents = await client.FilesManager.GetThumbnailAsync("11111", maxWidth: 160, maxHeight: 160);
  ```
</CodeGroup>

When a thumbnail was successfully created, this will return the thumbnail
in the body of the response as binary data.

## Asynchronous thumbnail creation

Sometimes the thumbnail can not be created directly. Instead, the API will
return an `HTTP 202` with a `location` response header. The location
is for a temporary image that can be used while the thumbnail is being
generated.

A `retry-after` response header is also provided to present you with
an estimated amount of seconds before retrying this endpoint.

## Supported file sizes

The following formats and sizes of thumbnails are available.

| File Type | Dimensions |
| - | - |
| JPG | `32x32`, `94x94`, `160x160`, `320x320`, `1024x1024`, `2048x2048`\* |
| PNG | `1024x1024`\*, `2048x2048`\* |

Some restrictions apply to the sizes marked as `*`.

## File size restrictions

### Original file size

Thumbnails are not scaled up. If the original file size of the file uploaded to
Box is smaller than the representation dimensions, the resulting thumbnail is
capped at the size of the original file.

## Supported file types

At this time the following file types are supported.

| File Type | File Extensions |
| - | - |
| Documents | `doc`, `docx`, `gdoc`, `gsheet`, `gslide`, `gslides`, `odp`, `ods`, `odt`, `pdf`, `ppt`, `pptx`, `rtf`, `wpd`, `xls`, `xlsm`, `xlsx`, `key`, `pages`, `numbers` |
| Images | `ai`, `bmp`, `dcm`, `dicm`, `eps`, `gif`, `idml`, `indd`, `indt`, `inx`, `jpeg`, `jpg`, `png`, `ps`, `psd`, `svg`, `svs`, `tif`, `tiff`, `tga` |
| Audio | `aac`, `aifc`, `aiff`, `amr`, `au`, `flac`, `m4a`, `mp3`, `ogg`, `ra`, `wav`, `wma` |
| Video | `3g2`, `3gp`, `avi`, `m2v`, `m2ts`, `m4v`, `mkv`, `mov`, `mp4`, `mpeg`, `mpg`, `mts`, `ogg`, `qt`, `wmv` |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get Thumbnail Representation
Source: https://developer.box.com/guides/representations/thumbnail-representation



<RelatedLinks title="REQUIRED GUIDES" />

A thumbnail is a small image, either as `.png` or as `.jpg` that can be used in
an application as a representation of the file, for example as a placeholder for
a link that downloads or previews the file.

All thumbnail representations except `1024x1024` and `2048x2048` PNGs are
generated upon uploading the source file to Box.

<Warning>
  A deprecated way to get a thumbnail for a file is using the
  <Link href="/guides/representations/thumbnail">thumbnail API</Link>.
</Warning>

## The process

To get a thumbnail representation follow the following steps:

* <Link href="/guides/representations/list-all-representations">List all representations</Link>
* <Link href="/guides/representations/request-a-representation">Request a thumbnail</Link> by passing the `x-rep-hints`-header for the desired thumbnail format and size, for example `[jpg?dimensions=32x32]`.
* <Link href="/guides/representations/download-a-representation">Download the thumbnail</Link> by calling the `url_template`, replacing the `{+asset_path}` with an empty string.

<Warning>
  Sometimes the thumbnail can not be created directly. Instead,
  the API will return an `HTTP 202` with a `location` response header.
  The location is for a temporary image that can be used while the thumbnail
  is being generated.
</Warning>

A retry-after response header is also provided to present you with an
estimated amount of seconds before retrying this endpoint.

## Examples

The following are some example `x-rep-hints`-header values:

| `x-rep-hints: [jpg?dimensions=32x32]` |
| - |
| Returns a `32x32` JPEG thumbnail |

| `x-rep-hints: [jpg?dimensions=32x32][jpg?dimensions=1024x1024]` |
| - |
| Returns `32x32` and `1024x1024` JPEG thumbnails |

| `x-rep-hints: [jpg?dimensions=32x32][png?dimensions=2048x2048]` |
| - |
| Returns a `32x32` JPEG and a `2048x2048` PNG thumbnail |

| `x-rep-hints: [jpg?dimensions=2048x2048,png?dimensions=2048x2048]` |
| - |
| Returns a `2048x2048` JPEG or a `2048x2048` PNG thumbnail, returning the first representation that is available. If neither is available it returns no representations |

## Supported file sizes

The following formats and sizes of thumbnails are available.

| File Type | Dimensions |
| - | - |
| JPG | `32x32`, `94x94`, `160x160`, `320x320`, `1024x1024`, `2048x2048`\* |
| PNG | `1024x1024`\*, `2048x2048`\* |

Some restrictions apply to the sizes marked as `*`.

## File size restrictions

### JPEG `2048x2048`

The JPEG `2048x2048` size is only available when the
original file is a JPEG. We recommend either requesting a PNG or both a PNG
and a JPEG for this dimension.

### Video files

JPEG `2048x2048`, PNG `2048x2048` and PNG `1024x1024` representations are not
available for video files.

### Original file size

Thumbnails are not scaled up. If the original file size of the file uploaded to
Box is smaller than the representation dimensions, the resulting thumbnail is
capped at the size of the original file.

## Supported file types

At this time the following file types are supported.

| File Type | File Extensions |
| - | - |
| Documents | `doc`, `docx`, `gdoc`, `gsheet`, `gslide`, `gslides`, `odp`, `ods`, `odt`, `pdf`, `ppt`, `pptx`, `rtf`, `wpd`, `xls`, `xlsm`, `xlsx`, `key`, `pages`, `numbers` |
| Images | `ai`, `bmp`, `dcm`, `dicm`, `eps`, `gif`, `idml`, `indd`, `indt`, `inx`, `jpeg`, `jpg`, `png`, `ps`, `psd`, `svg`, `svs`, `tif`, `tiff`, `tga` |
| Audio | `aac`, `aifc`, `aiff`, `amr`, `au`, `flac`, `m4a`, `mp3`, `ogg`, `ra`, `wav`, `wma` |
| Video | `3g2`, `3gp`, `avi`, `m2v`, `m2ts`, `m4v`, `mkv`, `mov`, `mp4`, `mpeg`, `mpg`, `ogg`, `mts`, `qt`, `wmv` |

<Warning>
  For **document** file types the representation returned will be a placeholder
  icon and not an actual thumbnail.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create or Update Shared Link
Source: https://developer.box.com/guides/shared-links/create-or-update



Shared links may be created or updated directly for file, folder, or web link
resources to generate a read-only URL to permit users with the appropriate
access level to view the content.

<Note>
  You may only have one active shared link for a file, folder, or web link at
  any time.
</Note>

At minimum the information needed to create a shared link will be:

* The type of resource, either a file, folder, or web link.
* The ID of that resource.

Optionally when creating a shared link the following may be specified:

* The access level, which may be one of:
  * open: A public shared link. Anyone with the link may access the link.
  * company: Anyone within your enterprise may access the link.
  * collaborators: Anyone collaborated on the content may access the link.
* An expiration time when the shared link will automatically disable.
* A password required to access the resource.

<Note>
  If an access level is not specified when creating a shared link it will use
  the default access level specified by the enterprise admin.
</Note>

## Create or Update Shared Link for File

To create a shared link on a file, specify the ID of the file with any optional
shared link parameters.

## Create or Update Shared Link for Folder

To create a shared link on a folder, specify the ID of the folder with any
optional shared link parameters.

## Create or Update Shared Link for Web Link

To create a shared link on a web link, specify the ID of the web link with any
optional shared link parameters.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Find Item from Shared Link
Source: https://developer.box.com/guides/shared-links/find-for-item



The <Link href="/reference/get-shared-items">find item for shared link</Link> API is designed to
accept a shared link as an input using a `BoxApi` header and return the file or
folder object that the shared link is set for.

To get the file or folder object associated with a shared link, supply
the full shared link URL in the request.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/shared_items" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "boxapi: shared_link=https://app.box.com/s/gjasdasjhasd&shared_link_password=letmein"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await userClient.sharedLinksFiles.findFileForSharedLink(
    {} satisfies FindFileForSharedLinkQueryParams,
    {
      boxapi: ''.concat(
        'shared_link=',
        fileFromApi.sharedLink!.url,
        '&shared_link_password=Secret123@',
      ) as string,
    } satisfies FindFileForSharedLinkHeadersInput,
  );
  ```

  ```python Python v10 theme={null}
  user_client.shared_links_files.find_file_for_shared_link(
      "".join(
          [
              "shared_link=",
              file_from_api.shared_link.url,
              "&shared_link_password=Secret123@",
          ]
      )
  )
  ```

  ```cs .NET v10 theme={null}
  await userClient.SharedLinksFiles.FindFileForSharedLinkAsync(queryParams: new FindFileForSharedLinkQueryParams(), headers: new FindFileForSharedLinkHeaders(boxapi: string.Concat("shared_link=", NullableUtils.Unwrap(fileFromApi.SharedLink).Url, "&shared_link_password=Secret123@")));
  ```

  ```swift Swift v10 theme={null}
  try await userClient.sharedLinksFiles.findFileForSharedLink(queryParams: FindFileForSharedLinkQueryParams(), headers: FindFileForSharedLinkHeaders(boxapi: "\("shared_link=")\(fileFromApi.sharedLink!.url)\("&shared_link_password=Secret123@")"))
  ```

  ```java Java v10 theme={null}
  userClient.getSharedLinksFiles().findFileForSharedLink(new FindFileForSharedLinkQueryParams(), new FindFileForSharedLinkHeaders(String.join("", "shared_link=", fileFromApi.getSharedLink().getUrl(), "&shared_link_password=Secret123@")))
  ```

  ```java Java v5 theme={null}
  String sharedLink = "https://app.box.com/s/abcdefghijklmnopqrstuvwxyz123456";
  String password = "foo";
  BoxItem.Info itemInfo = BoxItem.getSharedItem(api, sharedLink, password);
  ```

  ```python Python v4 theme={null}
  file = client.get_shared_item('https://app.box.com/s/gjasdasjhasd', password='letmein')
  ```

  ```javascript Node v4 theme={null}
  client.sharedItems.get(
      'https://app.box.com/s/1a2b3c4d5e',
      null,
      {fields: 'type,id,parent,extension,shared_link'},
      callback
  );
  ```
</CodeGroup>

<Info>
  Please note that when the shared link is for a folder, the response of this
  API does not include the list of nested items within that folder.

  To further traverse the items in the folder, use the same `BoxApi` header to
  <Link href="/reference/get-folders-id">get a nested folder's information</Link>, <Link href="/reference/get-folders-id-items">list the items in
  those folders</Link>, <Link href="/reference/get-files-id">get a nested file's
  information</Link>, or <Link href="/reference/get-files-id-content">download a file</Link>
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Shared Links
Source: https://developer.box.com/guides/shared-links/index

Generate URL-based access to files, folders, and web links stored in Box with configurable access levels.

Shared links are URLs that are generated for files, folders, web links stored
in Box, which provide direct, read-only access to the resource.

Shared links which are set to an open access level allow anyone with the URL to
access the item, while shared links with company or collaborators access levels
may only be accessed by appropriate authenticated Box users. See
[here][community_create_shared_link] for all of the options and admin settings
related to shared links.

Users can access shared items by entering the shared link URL in a browser.
Applications can also access shared items using the
<Link href="/reference/get-shared-items">Shared Item API</Link>.

## Quick example

Create an open shared link on a file:

```bash theme={null}
curl -X PUT https://api.box.com/2.0/files/FILE_ID \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "shared_link": {
      "access": "open"
    }
  }'
```

[community_create_shared_link]: https://docs.box.com/en/box-fundamentals/for-users/collaborating/using-shared-links/creating-shared-links


# Shared Link Permissions
Source: https://developer.box.com/guides/shared-links/permissions



The shared link resource has three permissions that can be updated using the
`permissions` field: `can_preview`, `can_download`, `can_edit`.

<Warning>
  The `can_edit` option can only be `true` for files. Also, if the admin has
  restricted shared links from having edit access in the admin console, you
  will not be able to set `can_edit` to `true`.
</Warning>

```sh theme={null}
curl -i -X PUT 'https://api.box.com/2.0/files/123456789?fields=shared_link' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer [ACCESS TOKEN]' \
    -d '{
      "shared_link": {
        "permissions": {
          "can_preview": true,
          "can_download": true,
          "can_edit": true
        }
      }
    }'
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Remove Shared Link
Source: https://developer.box.com/guides/shared-links/remove



A shared link may be removed from a resource by calling the
<Link href="/reference/put-files-id">update file</Link> or
<Link href="/reference/put-folders-id">update folder</Link> or
<Link href="/reference/put-web-links-id">update weblink</Link> endpoint and setting the
`shared_link` value to `null`.

<Warning>
  If you delete the shared link and create a new one, the new shared link will
  have a different URL and users with the old URL will not be able to access
  the resource.
</Warning>

## Remove Shared Link on File

To remove a shared link on a file, specify the ID of file to set the
`shared_link` field to `null`.

## Remove Shared Link on Folder

To remove a shared link on a folder, specify the ID of folder to set the
`shared_link` field to `null`.

## Remove Shared Link on Web Link

To remove a shared link on a web link, specify the ID of web link to set the
`shared_link` field to `null`.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Assign a task to a user
Source: https://developer.box.com/guides/tasks/assignments/assign



To assign a task to a user you will need to provide the
<Link href="/reference/post-task-assignments">`POST /task_assignments`</Link> API with the `id` of the
task and the user's details. For the user an application can either use the user
`id` or the user's login email, which Box refers to as their `login`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/task_assignments" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "task": {
           "id": "11446498",
           "type": "task"
         },
         "assign_to": {
           "id": "4823213"
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.taskAssignments.createTaskAssignment({
    task: new CreateTaskAssignmentRequestBodyTaskField({
      type: 'task' as CreateTaskAssignmentRequestBodyTaskTypeField,
      id: task.id!,
    }),
    assignTo: {
      id: currentUser.id,
    } satisfies CreateTaskAssignmentRequestBodyAssignToField,
  } satisfies CreateTaskAssignmentRequestBody);
  ```

  ```python Python v10 theme={null}
  client.task_assignments.create_task_assignment(
      CreateTaskAssignmentTask(type=CreateTaskAssignmentTaskTypeField.TASK, id=task.id),
      CreateTaskAssignmentAssignTo(id=current_user.id),
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.TaskAssignments.CreateTaskAssignmentAsync(requestBody: new CreateTaskAssignmentRequestBody(task: new CreateTaskAssignmentRequestBodyTaskField(type: CreateTaskAssignmentRequestBodyTaskTypeField.Task, id: NullableUtils.Unwrap(task.Id)), assignTo: new CreateTaskAssignmentRequestBodyAssignToField() { Id = currentUser.Id }));
  ```

  ```swift Swift v10 theme={null}
  try await client.taskAssignments.createTaskAssignment(requestBody: CreateTaskAssignmentRequestBody(task: CreateTaskAssignmentRequestBodyTaskField(type: CreateTaskAssignmentRequestBodyTaskTypeField.task, id: task.id!), assignTo: CreateTaskAssignmentRequestBodyAssignToField(id: currentUser.id)))
  ```

  ```java Java v10 theme={null}
  client.getTaskAssignments().createTaskAssignment(new CreateTaskAssignmentRequestBody(new CreateTaskAssignmentRequestBodyTaskField.Builder(task.getId()).type(CreateTaskAssignmentRequestBodyTaskTypeField.TASK).build(), new CreateTaskAssignmentRequestBodyAssignToField.Builder().id(currentUser.getId()).build()))
  ```

  ```java Java v5 theme={null}
  BoxUser user = new BoxUser(api, "user-id")
  BoxTask task = new BoxTask(api, "id");
  task.addAssignment(user);
  ```

  ```py Python v4 theme={null}
  user = client.user(user_id='11111')
  assignment = client.task(task_id='12345').assign(user)
  print(f'Assignment ID is {assignment.id} and is assigned to user {assignment.assigned_to.name}')
  ```

  ```csharp .NET v6 theme={null}
  // Assign task 11111 to user 22222
  var assignmentParams = new BoxTaskAssignmentRequest()
  {
      Task = new BoxTaskRequest()
      {
          Id = "11111"
      },
      AssignTo = new BoxAssignmentRequest()
      {
          Id = "22222"
      }
  };
  BoxTaskAssignment assignment = await client.TasksManager.CreateTaskAssignmentAsync(assignmentParams);
  ```

  ```js Node v4 theme={null}
  // Assign task 11111 to user 22222
  var taskID = '11111';
  var userID = '22222';
  client.tasks.assignByUserID(taskID, userID)
   .then(assignment => {
    /* assignment -> {
     type: 'task_assignment',
     id: '12345',
     item: 
     { type: 'file',
      id: '33333',
      sequence_id: '0',
      etag: '0',
      sha1: '7840095ee096ee8297676a138d4e316eabb3ec96',
      name: 'script.js' },
     assigned_to: 
     { type: 'user',
      id: '22222',
      name: 'Sample Assignee',
      login: 'assignee@exmaple.com' },
     message: null,
     completed_at: null,
     assigned_at: '2013-05-10T11:43:41-07:00',
     reminded_at: null,
     resolution_state: 'incomplete',
     assigned_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' } }
    */
   });
  ```
</CodeGroup>

<Note>
  # Notifications

  When creating a task an email notification is sent to the user who the task is
  assigned to.
</Note>

<Warning>
  # Permissions

  Both the user assigning the task and the user the task is being assigned to
  need to be a collaborator on the file.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Change task assignment state
Source: https://developer.box.com/guides/tasks/assignments/change-state



To update a task assignment's state call the
<Link href="/reference/put-task-assignments-id">`PUT /tasks/:task_id/assignments`</Link> API and
include a `resolution_state`, such as `completed`, `incomplete`,
`approved`, or `rejected`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/task_assignments/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "message": "New message",
         "resolution_state": "completed"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.taskAssignments.updateTaskAssignmentById(taskAssignment.id!, {
    requestBody: {
      message: 'updated message',
      resolutionState:
        'approved' as UpdateTaskAssignmentByIdRequestBodyResolutionStateField,
    } satisfies UpdateTaskAssignmentByIdRequestBody,
  } satisfies UpdateTaskAssignmentByIdOptionalsInput);
  ```

  ```python Python v10 theme={null}
  client.task_assignments.update_task_assignment_by_id(
      task_assignment.id,
      message="updated message",
      resolution_state=UpdateTaskAssignmentByIdResolutionState.APPROVED,
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.TaskAssignments.UpdateTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id), requestBody: new UpdateTaskAssignmentByIdRequestBody() { Message = "updated message", ResolutionState = UpdateTaskAssignmentByIdRequestBodyResolutionStateField.Approved });
  ```

  ```swift Swift v10 theme={null}
  try await client.taskAssignments.updateTaskAssignmentById(taskAssignmentId: taskAssignment.id!, requestBody: UpdateTaskAssignmentByIdRequestBody(message: "updated message", resolutionState: UpdateTaskAssignmentByIdRequestBodyResolutionStateField.approved))
  ```

  ```java Java v10 theme={null}
  client.getTaskAssignments().updateTaskAssignmentById(taskAssignment.getId(), new UpdateTaskAssignmentByIdRequestBody.Builder().message("updated message").resolutionState(UpdateTaskAssignmentByIdRequestBodyResolutionStateField.APPROVED).build())
  ```

  ```java Java v5 theme={null}
  String assignmentID = "12345";
  BoxTaskAssignment taskAssignment = new BoxTaskAssignment(api, assignmentID);
  BoxTaskAssignment.Info info = taskAssignment.getInfo();
  info.setResolutionState(BoxTaskAssignment.ResolutionState.APPROVED);
  taskAssignment.updateInfo(info);
  ```

  ```py Python v4 theme={null}
  from boxsdk.object.task_assignment import ResolutionState
  updated_task = {'resolution_state': ResolutionState.APPROVED}
  updated_assignment = client.task_assignment(assignment_id='12345').update_info(data=updated_task)
  print(f'Assignment ID is {updated_assignment.id} and resolution state is {updated_assignment.resolution_state}')
  ```

  ```csharp .NET v6 theme={null}
  var requestParams = new BoxTaskAssignmentUpdateRequest()
  {
      Id = "12345",
      ResolutionState = ResolutionStateType.approved
  };
  BoxTaskAssignment updatedAssignment = await client.TasksManager.UpdateTaskAssignmentAsync(requestParams);
  ```

  ```js Node v4 theme={null}
  // Complete a task
  client.tasks.updateAssignment(
   '12345',
   {
    message: 'Done!',
    resolution_state: client.tasks.resolutionStates.COMPLETE
   })
   .then(assignment => {
    /* assignment -> {
     type: 'task_assignment',
     id: '12345',
     item: 
     { type: 'file',
      id: '33333',
      sequence_id: '0',
      etag: '0',
      sha1: '7840095ee096ee8297676a138d4e316eabb3ec96',
      name: 'script.js' },
     assigned_to: 
     { type: 'user',
      id: '22222',
      name: 'Sample Assignee',
      login: 'assignee@exmaple.com' },
     message: 'Done!',
     completed_at: null,
     assigned_at: '2013-05-10T11:43:41-07:00',
     reminded_at: null,
     resolution_state: 'complete',
     assigned_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' } }
    */
   });
  ```
</CodeGroup>

## Resolution states

Box currently supports two types of tasks defined by the `action` value:
`review` tasks and `complete` tasks.

The type of task determines the possible resolution states a task can be in and
the interface shown to a user in the web and mobile apps.

| Task action | Possible resolution states |
| - | - |
| `review` | `incomplete`, `approved`, `rejected` |
| `complete` | `incomplete`, `complete` |

A `review` task starts out in an `incomplete` state and can be marked as
`incomplete`, `approved`, or `rejected`. In the user interface a user is
provided with a text box and a pair of buttons to approve or reject the task.

A `complete` task starts out in an `incomplete` state and can be marked
`incomplete` or `completed`. Once this task is marked completed, no
further changes can be made to the task's state. In the user interface a user is
provided with a text box and a button to mark the task as completed.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get task assignment information
Source: https://developer.box.com/guides/tasks/assignments/get



To get information about an assigned task, call the
<Link href="/reference/get-task-assignments-id">`GET /tasks/:task_id/assignments`</Link> API with the
`id` of the task assignment.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/task_assignments/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.taskAssignments.getTaskAssignmentById(taskAssignment.id!);
  ```

  ```python Python v10 theme={null}
  client.task_assignments.get_task_assignment_by_id(task_assignment.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.TaskAssignments.GetTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.taskAssignments.getTaskAssignmentById(taskAssignmentId: taskAssignment.id!)
  ```

  ```java Java v10 theme={null}
  client.getTaskAssignments().getTaskAssignmentById(taskAssignment.getId())
  ```

  ```java Java v5 theme={null}
  String assignmentID = "4256974";
  BoxTaskAssignment.Info assignmentInfo = new BoxTaskAssignment(api, assignmentID).getInfo();
  ```

  ```py Python v4 theme={null}
  assignment= client.task_assignment('12345').get()
  print(f'Assignment ID is {assignment.id} and assignment type is {assignment.type}')
  ```

  ```csharp .NET v6 theme={null}
  BoxTaskAssignment assignment = await client.TasksManager.GetTaskAssignmentAsync("12345");
  ```

  ```js Node v4 theme={null}
  client.tasks.getAssignment('12345')
   .then(assignment => {
    /* assignment -> {
     type: 'task_assignment',
     id: '12345',
     item: 
     { type: 'file',
      id: '33333',
      sequence_id: '0',
      etag: '0',
      sha1: '7840095ee096ee8297676a138d4e316eabb3ec96',
      name: 'script.js' },
     assigned_to: 
     { type: 'user',
      id: '22222',
      name: 'Sample Assignee',
      login: 'assignee@exmaple.com' },
     message: null,
     completed_at: null,
     assigned_at: '2013-05-10T11:43:41-07:00',
     reminded_at: null,
     resolution_state: 'incomplete',
     assigned_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' } }
    */
   });
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Assigning tasks
Source: https://developer.box.com/guides/tasks/assignments/index



When a task is delegated to a user in Box it creates a task assignment. A task
assignment is a request for that user to complete the task.

The way a task is resolved depends on the `action` type of a task and the
`resolution_state` used to define how a task is resolved.

<Card href={localizeLink("/guides/tasks")} title="Learn about types of tasks" />


# List a task's assignments
Source: https://developer.box.com/guides/tasks/assignments/list



To list all of the assignments for a specific task, call the
<Link href="/reference/get-task-assignments-id">`GET /tasks/:task_id/assignments`</Link> with the task
`id`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/task_assignments/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.taskAssignments.getTaskAssignmentById(taskAssignment.id!);
  ```

  ```python Python v10 theme={null}
  client.task_assignments.get_task_assignment_by_id(task_assignment.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.TaskAssignments.GetTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.taskAssignments.getTaskAssignmentById(taskAssignmentId: taskAssignment.id!)
  ```

  ```java Java v10 theme={null}
  client.getTaskAssignments().getTaskAssignmentById(taskAssignment.getId())
  ```

  ```java Java v5 theme={null}
  String assignmentID = "4256974";
  BoxTaskAssignment.Info assignmentInfo = new BoxTaskAssignment(api, assignmentID).getInfo();
  ```

  ```py Python v4 theme={null}
  assignment= client.task_assignment('12345').get()
  print(f'Assignment ID is {assignment.id} and assignment type is {assignment.type}')
  ```

  ```csharp .NET v6 theme={null}
  BoxTaskAssignment assignment = await client.TasksManager.GetTaskAssignmentAsync("12345");
  ```

  ```js Node v4 theme={null}
  client.tasks.getAssignment('12345')
   .then(assignment => {
    /* assignment -> {
     type: 'task_assignment',
     id: '12345',
     item: 
     { type: 'file',
      id: '33333',
      sequence_id: '0',
      etag: '0',
      sha1: '7840095ee096ee8297676a138d4e316eabb3ec96',
      name: 'script.js' },
     assigned_to: 
     { type: 'user',
      id: '22222',
      name: 'Sample Assignee',
      login: 'assignee@exmaple.com' },
     message: null,
     completed_at: null,
     assigned_at: '2013-05-10T11:43:41-07:00',
     reminded_at: null,
     resolution_state: 'incomplete',
     assigned_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' } }
    */
   });
  ```
</CodeGroup>

<RelatedLinks title="RELATED GUIDES" />


# Unassign a task
Source: https://developer.box.com/guides/tasks/assignments/unassign



To unassign a task, you will need to provide the
<Link href="/reference/delete-task-assignments-id">`DELETE /task_assignments`</Link> API with the `id`
of the task assignment.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/task_assignments/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.taskAssignments.deleteTaskAssignmentById(taskAssignment.id!);
  ```

  ```python Python v10 theme={null}
  client.task_assignments.delete_task_assignment_by_id(task_assignment.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.TaskAssignments.DeleteTaskAssignmentByIdAsync(taskAssignmentId: NullableUtils.Unwrap(taskAssignment.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.taskAssignments.deleteTaskAssignmentById(taskAssignmentId: taskAssignment.id!)
  ```

  ```java Java v10 theme={null}
  client.getTaskAssignments().deleteTaskAssignmentById(taskAssignment.getId())
  ```

  ```java Java v5 theme={null}
  BoxTaskAssignment taskAssignment = new BoxTaskAssignment(api, "id");
  taskAssignment.delete();
  ```

  ```py Python v4 theme={null}
  client.task_assignment(assignment_id='12345').delete()
  print('The task assignment was successfully delete!')
  ```

  ```csharp .NET v6 theme={null}
  await client.TasksManager.DeleteTaskAssignmentAsync("12345");
  ```

  ```js Node v4 theme={null}
  client.tasks.deleteAssignment('12345')
   .then(() => {
    // deletion succeeded — no value returned
   });
  ```
</CodeGroup>

<Warning>
  # Permissions

  The user deleting the assignment needs to be a collaborator on the file.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Change an assignment's message
Source: https://developer.box.com/guides/tasks/assignments/update-message



To update a task assignment's message call the
<Link href="/reference/put-task-assignments-id">`PUT /tasks/:task_id/assignments`</Link> API, and
include the new `message` for the task assignment.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create a task
Source: https://developer.box.com/guides/tasks/create



To create a task, you will need to provide the <Link href="/reference/post-tasks">`POST /tasks`</Link> API
with the `action` for the task, as well as an `item` to represent the file to
add the task to.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/tasks" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "item": {
           "id": "11446498",
           "type": "file"
         },
         "action": "review"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.tasks.createTask({
    item: {
      type: 'file' as CreateTaskRequestBodyItemTypeField,
      id: file.id,
    } satisfies CreateTaskRequestBodyItemField,
    message: 'test message',
    dueAt: dateTime,
    action: 'review' as CreateTaskRequestBodyActionField,
    completionRule: 'all_assignees' as CreateTaskRequestBodyCompletionRuleField,
  } satisfies CreateTaskRequestBody);
  ```

  ```python Python v10 theme={null}
  client.tasks.create_task(
      CreateTaskItem(type=CreateTaskItemTypeField.FILE, id=file.id),
      action=CreateTaskAction.REVIEW,
      message="test message",
      due_at=date_time,
      completion_rule=CreateTaskCompletionRule.ALL_ASSIGNEES,
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.Tasks.CreateTaskAsync(requestBody: new CreateTaskRequestBody(item: new CreateTaskRequestBodyItemField() { Type = CreateTaskRequestBodyItemTypeField.File, Id = file.Id }) { Message = "test message", DueAt = dateTime, Action = CreateTaskRequestBodyActionField.Review, CompletionRule = CreateTaskRequestBodyCompletionRuleField.AllAssignees });
  ```

  ```swift Swift v10 theme={null}
  try await client.tasks.createTask(requestBody: CreateTaskRequestBody(item: CreateTaskRequestBodyItemField(type: CreateTaskRequestBodyItemTypeField.file, id: file.id), message: "test message", dueAt: dateTime, action: CreateTaskRequestBodyActionField.review, completionRule: CreateTaskRequestBodyCompletionRuleField.allAssignees))
  ```

  ```java Java v10 theme={null}
  client.getTasks().createTask(new CreateTaskRequestBody.Builder(new CreateTaskRequestBodyItemField.Builder().id(file.getId()).type(CreateTaskRequestBodyItemTypeField.FILE).build()).action(CreateTaskRequestBodyActionField.REVIEW).message("test message").dueAt(dateTime).completionRule(CreateTaskRequestBodyCompletionRuleField.ALL_ASSIGNEES).build())
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  Date dueAt = new Date();
  file.addTask(BoxTask.Action.REVIEW, "Please review this file.", dueAt);
  ```

  ```py Python v4 theme={null}
  message = 'Please review this'
  due_at = "2014-04-03T11:09:43-07:00"
  task = client.file(file_id='11111').create_task(message, due_at)
  print(f'Task message is {task.message} and it is due at {task.due_at}')
  ```

  ```csharp .NET v6 theme={null}
  var taskParams = new BoxTaskCreateRequest()
  {
      Item = new BoxRequestEntity()
      {
          Type = BoxType.file,
          Id = "11111"
      },
      Message = "Please review!"
  };
  BoxTask task = await client.TasksManager.CreateTaskAsync(taskParams);
  ```

  ```js Node v4 theme={null}
  var options = {
   message: 'Please review for publication!',
   due_at: '2014-04-03T11:09:43-07:00'
  };
  client.tasks.create('22222', options)
   .then(task => {
    /* task -> {
     type: 'task',
     id: '11111',
     item: 
     { type: 'file',
      id: '22222',
      sequence_id: '0',
      etag: '0',
      sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
      name: 'box-logo.png' },
     due_at: '2014-04-03T11:09:43-07:00',
     action: 'review',
     message: 'Please review for publication!',
     task_assignment_collection: { total_count: 0, entries: [] },
     is_completed: false,
     created_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' },
     created_at: '2013-04-03T11:12:54-07:00' }
    */
   });
  ```
</CodeGroup>

## Task actions

Box currently supports two types of tasks defined by the `action` value:
`review` tasks and `complete` tasks.

The type of task determines the possible resolution states a task can be in and
the interface shown to a user in the web and mobile apps.

| Task action | Possible resolution states |
| - | - |
| `review` | `incomplete`, `approved`, `rejected` |
| `complete` | `incomplete`, `complete` |

A `review` task starts out in an `incomplete` state and can be marked as
`incomplete`, `approved`, or `rejected`. In the user interface a user is
provided with a text box and a pair of buttons to approve or reject the task.

A `complete` task starts out in an `incomplete` state and can be marked
`incomplete` or `completed`. Once this task is marked completed, no
further changes can be made to the task's state. In the user interface a user is
provided with a text box and a button to mark the task as completed.

## Completion rules

A task on a file can be assigned to more than one collaborator on the file, and
a task has a `completion_rule` that can be used to define if all users who've
been assigned the task (`all_assignees`) or only one assignee (`any_assignee`)
need to complete the task.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete a task
Source: https://developer.box.com/guides/tasks/delete



To remove a task, call the <Link href="/reference/delete-tasks-id">`DELETE /tasks/:task_id`</Link> API
with the `id` of the task.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/tasks/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.tasks.deleteTaskById(task.id!);
  ```

  ```python Python v10 theme={null}
  client.tasks.delete_task_by_id(task.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.Tasks.DeleteTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.tasks.deleteTaskById(taskId: task.id!)
  ```

  ```java Java v10 theme={null}
  client.getTasks().deleteTaskById(task.getId())
  ```

  ```java Java v5 theme={null}
  BoxTask task = new BoxTask(api, "id");
  task.delete();
  ```

  ```py Python v4 theme={null}
  client.client.task('12345').delete()
  print('The task was successfully delete!')
  ```

  ```csharp .NET v6 theme={null}
  await client.TasksManager.DeleteTaskAsync("11111");
  ```

  ```js Node v4 theme={null}
  client.tasks.delete('11111')
   .then(() => {
    // deletion succeeded — no value returned
   });
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Lists all tasks for a file
Source: https://developer.box.com/guides/tasks/for-file



To list all of the tasks for a specific file, call the
<Link href="/reference/get-files-id-tasks">`GET /files/:id/tasks`</Link> with the `id` of the file.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/files/12345/tasks" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.tasks.getFileTasks(file.id);
  ```

  ```python Python v10 theme={null}
  client.tasks.get_file_tasks(file.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.Tasks.GetFileTasksAsync(fileId: file.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.tasks.getFileTasks(fileId: file.id)
  ```

  ```java Java v10 theme={null}
  client.getTasks().getFileTasks(file.getId())
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  List<BoxTask.Info> tasks = file.getTasks();
  ```

  ```py Python v4 theme={null}
  tasks = client.file(file_id='11111').get_tasks()
  for task in tasks:
      print(f'Task ID is {task.id} and the type is {task.type}')
  ```

  ```csharp .NET v6 theme={null}
  BoxCollection<BoxTask> tasks = await client.FilesManager.FilesManager.GetFileTasks("11111");
  ```

  ```js Node v4 theme={null}
  client.files.getTasks('11111')
   .then(tasks => {
    /* tasks -> {
     total_count: 1,
     entries: 
     [ { type: 'task',
      id: '22222',
      item: 
       { type: 'file',
       id: '11111',
       sequence_id: '6',
       etag: '6',
       sha1: '81cc829fb8366fcfc108aa6c5a9bde01a6a10c16',
       name: 'box-logo.png' },
      due_at: null } ] }
    */
   });
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get information about a task
Source: https://developer.box.com/guides/tasks/get



To get information about an assigned task, call the
<Link href="/reference/get-tasks-id">`GET /tasks/:task_id`</Link> API with the
`id` of the task.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/tasks/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.tasks.getTaskById(task.id!);
  ```

  ```python Python v10 theme={null}
  client.tasks.get_task_by_id(task.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.Tasks.GetTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.tasks.getTaskById(taskId: task.id!)
  ```

  ```java Java v10 theme={null}
  client.getTasks().getTaskById(task.getId())
  ```

  ```java Java v5 theme={null}
  BoxTask task = new BoxTask(api, "id");
  BoxTask.Info info = task.getInfo();
  ```

  ```py Python v4 theme={null}
  task = client.task(task_id='12345').get()
  print(f'Task ID is {task.id} and the type is {task.type}')
  ```

  ```csharp .NET v6 theme={null}
  BoxTask task = await client.TasksManager.GetTaskAsync("11111");
  ```

  ```js Node v4 theme={null}
  client.tasks.get('11111')
   .then(task => {
    /* task -> {
     type: 'task',
     id: '11111',
     item: 
     { type: 'file',
      id: '22222',
      sequence_id: '0',
      etag: '0',
      sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
      name: 'box-logo.png' },
     due_at: '2014-04-03T11:09:43-07:00',
     action: 'review',
     message: 'Please review for publication!',
     task_assignment_collection: { total_count: 0, entries: [] },
     is_completed: false,
     created_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' },
     created_at: '2013-04-03T11:12:54-07:00' }
    */
   });
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Tasks overview
Source: https://developer.box.com/guides/tasks/index



Tasks allow users to request collaborators on a file to review a file or
complete a piece of work. Tasks can be used by developers to create file-centric
workflows. Learn more about tasks from the [**Adding Comments and
Tasks**][community] article on our support site.

<Frame>
  <img alt="Box Tasks in UI" />
</Frame>

## Task actions

Box currently supports two types of tasks defined by the `action` value:
`review` tasks and `complete` tasks.

The type of task determines the possible resolution states a task can be in and
the interface shown to a user in the web and mobile apps.

| Task action | Possible resolution states |
| - | - |
| `review` | `incomplete`, `approved`, `rejected` |
| `complete` | `incomplete`, `complete` |

A `review` task starts out in an `incomplete` state and can be marked as
`incomplete`, `approved`, or `rejected`. In the user interface a user is
provided with a text box and a pair of buttons to approve or reject the task.

A `complete` task starts out in an `incomplete` state and can be marked
`incomplete` or `completed`. Once this task is marked completed, no
further changes can be made to the task's state. In the user interface a user is
provided with a text box and a button to mark the task as completed.

## Completion rules

A task on a file can be assigned to more than one collaborator on the file, and
a task has a `completion_rule` that can be used to define if all users who've
been assigned the task (`all_assignees`) or only one assignee (`any_assignee`)
need to complete the task.

[community]: https://support.box.com/hc/en-us/articles/360043695954-Adding-Comments-and-Tasks


# Make changes to an existing task
Source: https://developer.box.com/guides/tasks/update



To update a task in Box you will need to call the
<Link href="/reference/put-tasks-id">`PUT /tasks/:task_id`</Link> API with the ID of the task. This API
can be used to change the `action` type of the task, add a `message`, or change
the due date.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/tasks/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "action": "review"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.tasks.updateTaskById(task.id!, {
    requestBody: {
      message: 'updated message',
    } satisfies UpdateTaskByIdRequestBody,
  } satisfies UpdateTaskByIdOptionalsInput);
  ```

  ```python Python v10 theme={null}
  client.tasks.update_task_by_id(task.id, message="updated message")
  ```

  ```csharp .NET v10 theme={null}
  await client.Tasks.UpdateTaskByIdAsync(taskId: NullableUtils.Unwrap(task.Id), requestBody: new UpdateTaskByIdRequestBody() { Message = "updated message" });
  ```

  ```swift Swift v10 theme={null}
  try await client.tasks.updateTaskById(taskId: task.id!, requestBody: UpdateTaskByIdRequestBody(message: "updated message"))
  ```

  ```java Java v10 theme={null}
  client.getTasks().updateTaskById(task.getId(), new UpdateTaskByIdRequestBody.Builder().message("updated message").build())
  ```

  ```java Java v5 theme={null}
  BoxTask task = new BoxTask(api, "id");
  BoxTask.Info info = task.new Info();
  info.setMessage("An edited message.");
  task.updateInfo(info);
  ```

  ```py Python v4 theme={null}
  task_update = {'message': 'New Message', 'due_at': '2014-04-03T11:09:43-10:00'}
  updated_task = client.task(task_id='12345').update_info(data=task_update)
  print(f'New task message is {updated_task.message} and the new due time is {updated_task.due_at}')
  ```

  ```csharp .NET v6 theme={null}
  var updates = new BoxTaskUpdateRequest()
  {
      Id = "22222",
      Message = "Could you please review this?"
  };
  BoxTask updatedTask = await client.TasksManager.UpdateTaskAsync(updates);
  ```

  ```js Node v4 theme={null}
  client.tasks.update('11111', { message: 'Could you please review?' })
   .then(task => {
    /* task -> {
     type: 'task',
     id: '11111',
     item: 
     { type: 'file',
      id: '22222',
      sequence_id: '0',
      etag: '0',
      sha1: '0bbd79a105c504f99573e3799756debba4c760cd',
      name: 'box-logo.png' },
     due_at: '2014-04-03T11:09:43-07:00',
     action: 'review',
     message: 'Could you please review?',
     task_assignment_collection: { total_count: 0, entries: [] },
     is_completed: false,
     created_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' },
     created_at: '2013-04-03T11:12:54-07:00' }
    */
   });
  ```
</CodeGroup>

## Task actions

Box currently supports two types of tasks defined by the `action` value:
`review` tasks and `complete` tasks.

The type of task determines the possible resolution states a task can be in and
the interface shown to a user in the web and mobile apps.

| Task action | Possible resolution states |
| - | - |
| `review` | `incomplete`, `approved`, `rejected` |
| `complete` | `incomplete`, `complete` |

A `review` task starts out in an `incomplete` state and can be marked as
`incomplete`, `approved`, or `rejected`. In the user interface a user is
provided with a text box and a pair of buttons to approve or reject the task.

A `complete` task starts out in an `incomplete` state and can be marked
`incomplete` or `completed`. Once this task is marked completed, no
further changes can be made to the task's state. In the user interface a user is
provided with a text box and a button to mark the task as completed.

## Completion rules

A task on a file can be assigned to more than one collaborator on the file, and
a task has a `completion_rule` that can be used to define if all users who've
been assigned the task (`all_assignees`) or only one assignee (`any_assignee`)
need to complete the task.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Trash
Source: https://developer.box.com/guides/trash/index



Before items are deleted they might end up in a user's trash. The trash can be
managed by a user through any of the Box apps, and by an application via the
API.

## Two-stage Deletion Process

Box uses a two-stage process to remove or **trash** [files], [folders], and
[web links] before permanently deleting them.

By default, items can be restored after they are **trashed** within a 30 day
time frame before they are **purged**. The purge window can be modified by
an enterprise administrator.

More details can be found in the Box community article on [Managing Trash].

[files]: /reference/delete-files-id

[folders]: /reference/delete-folders-id

[web links]: /reference/delete-web-links-id

[Managing Trash]: https://support.box.com/hc/en-us/articles/360044196093-Manage-Trash


# Permanently Delete File
Source: https://developer.box.com/guides/trash/permanently-delete-file



Once a file has been moved to the trash, it will stay in the trash for 30
days by default before being purged. Administrators of Business or
Enterprise accounts can alter the purge window. If you wish to permanently
delete the file from the trash before the purge window expires, make a `DELETE`
request to `/files/:file_id/trash` using the trashed file's `ID`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/files/12345/trash" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.trashedFiles.deleteTrashedFileById(file.id);
  ```

  ```python Python v10 theme={null}
  client.trashed_files.delete_trashed_file_by_id(file.id)
  ```

  ```cs .NET v10 theme={null}
  await client.TrashedFiles.DeleteTrashedFileByIdAsync(fileId: file.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.trashedFiles.deleteTrashedFileById(fileId: file.id)
  ```

  ```java Java v10 theme={null}
  client.getTrashedFiles().deleteTrashedFileById(file.getId())
  ```

  ```java Java v5 theme={null}
  String fileID = "87398";
  BoxTrash trash = new BoxTrash(api);
  trash.deleteFile(fileID);
  ```

  ```python Python v4 theme={null}
  file_to_delete = client.file(file_id='11111')
  client.trash().permanently_delete_item(file_to_delete)
  print('The file was deleted from trash!')
  ```

  ```cs .NET v6 theme={null}
  await client.FilesManager.PurgeTrashedAsync("11111");
  ```

  ```javascript Node v4 theme={null}
  client.files.deletePermanently('11111')
  	.then(() => {
  		// deletion succeeded — no value returned
  	});
  ```
</CodeGroup>

<RelatedLinks title="RELATED RESOURCES" />


# Permanently Delete Folder
Source: https://developer.box.com/guides/trash/permanently-delete-folder



Once a folder has been moved to the trash, it will stay in the trash for 30
days by default before being purged. Administrators of Business or
Enterprise accounts can alter the purge window. If you wish to permanently
delete the folder from the trash before the purge window expires, make a
`DELETE` request to `/folders/:folder_id/trash` using the trashed folder's `ID`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/folders/4353455/trash" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.trashedFolders.deleteTrashedFolderById(folder.id);
  ```

  ```python Python v10 theme={null}
  client.trashed_folders.delete_trashed_folder_by_id(folder.id)
  ```

  ```cs .NET v10 theme={null}
  await client.TrashedFolders.DeleteTrashedFolderByIdAsync(folderId: folder.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.trashedFolders.deleteTrashedFolderById(folderId: folder.id)
  ```

  ```java Java v10 theme={null}
  client.getTrashedFolders().deleteTrashedFolderById(folder.getId())
  ```

  ```java Java v5 theme={null}
  String folder = "123456";
  BoxTrash trash = new BoxTrash(api);
  trash.deleteFolder(folderID);
  ```

  ```python Python v4 theme={null}
  folder = client.folder(folder_id='22222')
  client.trash().permanently_delete_item(folder)
  print('The folder was deleted from trash!')
  ```

  ```cs .NET v6 theme={null}
  await client.FoldersManager.PurgeTrashedFolderAsync("22222");
  ```

  ```javascript Node v4 theme={null}
  client.folders.deletePermanently('22222')
  	.then(() => {
  		// deletion succeeded — no value returned
  	});
  ```
</CodeGroup>

<RelatedLinks title="RELATED RESOURCES" />


# Permanently Delete Web Link
Source: https://developer.box.com/guides/trash/permanently-delete-web-link



Once a web link has been moved to the trash, it will stay in the trash for 30
days by default before being purged. Administrators of Business or
Enterprise accounts can alter the purge window. If you wish to permanently
delete the web link from the trash before the purge window expires, make a
`DELETE` request to `/web_links/:web_link_id/trash` using the trashed web
link's `ID`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/web_links/12345/trash" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.trashedWebLinks.deleteTrashedWebLinkById(weblink.id);
  ```

  ```python Python v10 theme={null}
  client.trashed_web_links.delete_trashed_web_link_by_id(weblink.id)
  ```

  ```cs .NET v10 theme={null}
  await client.TrashedWebLinks.DeleteTrashedWebLinkByIdAsync(webLinkId: weblink.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.trashedWebLinks.deleteTrashedWebLinkById(webLinkId: weblink.id)
  ```

  ```java Java v10 theme={null}
  client.getTrashedWebLinks().deleteTrashedWebLinkById(weblink.getId())
  ```

  ```python Python v4 theme={null}
  web_link = client.web_link(web_link_id='33333')
  client.trash().permanently_delete_item(web_link)
  print('The web link was deleted from trash!')
  ```
</CodeGroup>


# Restore File
Source: https://developer.box.com/guides/trash/restore-file



To restore a file that has been moved to the trash, but has not yet been
purged, make a `POST` request to the `/files/:file_id` endpoint. This will
place the file in the original folder if it is still available, or you
optionally can specify a `parent` folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/files/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.trashedFiles.restoreFileFromTrash(file.id);
  ```

  ```python Python v10 theme={null}
  client.trashed_files.restore_file_from_trash(file.id)
  ```

  ```cs .NET v10 theme={null}
  await client.TrashedFiles.RestoreFileFromTrashAsync(fileId: file.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.trashedFiles.restoreFileFromTrash(fileId: file.id)
  ```

  ```java Java v10 theme={null}
  client.getTrashedFiles().restoreFileFromTrash(file.getId())
  ```

  ```java Java v5 theme={null}
  String fileID = "125367";
  String newName = "Presentation 2018 ORIGINAL.pptx";
  String newParentID = "98765";

  BoxTrash trash = new BoxTrash(api);
  // Avoid conflicts at the original location
  trash.restoreFile(fileID, newName, newParentID);
  ```

  ```python Python v4 theme={null}
  file_to_restore = client.file(file_id='11111')
  restored_file = client.trash().restore_item(file_to_restore)
  print(f'File ID is {restored_file.id} and name is {restored_file.name}')
  ```

  ```cs .NET v6 theme={null}
  var requestParams = new BoxFileRequest()
  {
      Name = "Name in case of conflict",
      Parent = new BoxRequestEntity()
      {
          // File will be placed in this folder if original location no longer exists
          Id = "12345" 
      }
  };
  BoxFile restoredFile = await client.FilesManager.RestoreTrashedAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  client.files.restoreFromTrash(
  	'11111',
  	{
  		// New name in case of conflict
  		name: 'New Name',
  		// File will be placed in this folder if original location no longer exists
  		parent_id: '0'
  	})
  	.then(restoredFile => {
  		/* trashedFile -> {
  			type: 'file',
  			id: '11111',
  			sequence_id: '2',
  			etag: '2',
  			sha1: '4bd9e98652799fc57cf9423e13629c151152ce6c',
  			name: 'Screenshot_1_30_13_6_37_PM.png',
  			description: '',
  			size: 163265,
  			path_collection: 
  			{ total_count: 1,
  				entries: 
  				[ { type: 'folder',
  					id: '0',
  					sequence_id: null,
  					etag: null,
  					name: 'All Files' } ] },
  			created_at: '2013-01-30T18:43:56-08:00',
  			modified_at: '2013-01-30T18:44:00-08:00',
  			trashed_at: null,
  			purged_at: null,
  			content_created_at: '2013-01-30T18:43:56-08:00',
  			content_modified_at: '2013-01-30T18:44:00-08:00',
  			created_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			modified_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			owned_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			shared_link: null,
  			parent: 
  			{ type: 'folder',
  				id: '0',
  				sequence_id: null,
  				etag: null,
  				name: 'All Files' },
  			item_status: 'active' }
  		*/
  	});
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Restore Folder
Source: https://developer.box.com/guides/trash/restore-folder



To restore a folder that has been moved to the trash, but has not yet been
purged, make a `POST` request to the `/folders/:folder_id` endpoint. This will
place the folder in the original parent folder if it is still available, or you
optionally can specify a `parent` folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/folders/4353455" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.trashedFolders.restoreFolderFromTrash(folder.id);
  ```

  ```python Python v10 theme={null}
  client.trashed_folders.restore_folder_from_trash(folder.id)
  ```

  ```cs .NET v10 theme={null}
  await client.TrashedFolders.RestoreFolderFromTrashAsync(folderId: folder.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.trashedFolders.restoreFolderFromTrash(folderId: folder.id)
  ```

  ```java Java v10 theme={null}
  client.getTrashedFolders().restoreFolderFromTrash(folder.getId())
  ```

  ```java Java v5 theme={null}
  String folderID = "125367";
  String newName = "My Documents ORIGINAL";
  String newParentID = "98765";

  BoxTrash trash = new BoxTrash(api);
  // Avoid conflicts at the original location
  trash.restoreFolder(folderID, newName, newParentID);
  ```

  ```python Python v4 theme={null}
  folder_to_restore = client.folder(folder_id='22222')
  restored_folder = client.trash().restore_item(folder_to_restore)
  print(f'Folder ID is {restored_folder.id} and name is {restored_folder.name}')
  ```

  ```cs .NET v6 theme={null}
  var requestParams = new BoxFolderRequest()
  {
      Name = "Name in case of conflict",
      Parent = new BoxRequestEntity()
      {
          // Folder will be placed in this parent folder if original location no longer exists
          Id = "12345" 
      }
  };
  BoxFolder restoredFolder = await client.FoldersManager.RestoreTrashedFolderAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  client.folders.restoreFromTrash(
  	'22222',
  	{
  		// New name in case of conflict
  		name: 'New Name',
  		// Folder will be placed in this parent folder if the original parent no longer exists
  		parent_id: '0'
  	})
  	.then(restoredFolder => {
  		/* trashedFolder -> {
  			type: 'folder',
  			id: '22222',
  			sequence_id: '1',
  			etag: '1',
  			name: 'Old Files',
  			created_at: '2013-05-06T22:37:30-07:00',
  			modified_at: '2013-05-06T22:39:08-07:00',
  			description: '',
  			size: 18482,
  			path_collection: 
  			{ total_count: 1,
  				entries: 
  				[ { type: 'folder',
  					id: '0',
  					sequence_id: null,
  					etag: null,
  					name: 'All Files' } ] },
  			created_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			modified_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			trashed_at: null,
  			purged_at: null,
  			content_created_at: '2013-05-06T22:37:30-07:00',
  			content_modified_at: '2013-05-06T22:39:08-07:00',
  			owned_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			shared_link: null,
  			folder_upload_email: null,
  			parent: 
  			{ type: 'folder',
  				id: '0',
  				sequence_id: null,
  				etag: null,
  				name: 'All Files' },
  			item_status: 'active' }
  		*/
  	});
  ```
</CodeGroup>

<Warning>
  During a folder restoration operation, part of the file tree will be locked,
  such as the source folder for the request and all of its descendants, as
  well as the destination folder.

  During the restoration of the folder, no other move, copy, delete, or
  restore operation can be performed on the locked folders.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Restore Web Link
Source: https://developer.box.com/guides/trash/restore-web-link



To restore a web link that has been moved to the trash, but has not yet been
purged, make a `POST` request to the `/web_links/:web_link_id` endpoint. This
will place the web link in the original parent folder if it is still
available, or you optionally can specify a `parent` folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/web_links/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.trashedWebLinks.restoreWeblinkFromTrash(weblink.id);
  ```

  ```python Python v10 theme={null}
  client.trashed_web_links.restore_weblink_from_trash(weblink.id)
  ```

  ```cs .NET v10 theme={null}
  await client.TrashedWebLinks.RestoreWeblinkFromTrashAsync(webLinkId: weblink.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.trashedWebLinks.restoreWeblinkFromTrash(webLinkId: weblink.id)
  ```

  ```java Java v10 theme={null}
  client.getTrashedWebLinks().restoreWeblinkFromTrash(weblink.getId())
  ```

  ```python Python v4 theme={null}
  web_link_to_restore = client.web_link(web_link_id='33333')
  restored_web_link = client.trash().restore_item(web_link_to_restore)
  print(f'Web link ID is {restored_web_link.id} and name is {restored_web_link.name}')
  ```
</CodeGroup>


# Preflight Check
Source: https://developer.box.com/guides/uploads/check



The Pre-flight check API allows an application to verify that a file will be
accepted by Box before it uploads any bytes. It can both be used for new files,
as well as uploading new versions of existing files.

## Checklist

Preflight checks perform all the same checks as if the file was
actually uploaded including:

* The permission of the application and the user to upload to the folder
* Any file name collisions
* Any file size caps and limits
* Any folder and file name restrictions
* Any folder and account storage quotas

## Check for new file

To perform a check for a new file, call the
<Link href="/reference/options-files-content">`OPTIONS /files/content`</Link> API with the same
parameters (except for the binary content) as if uploading an actual file.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X OPTIONS "https://api.box.com/2.0/files/content" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{"name":"Contract.pdf", "parent":{"id":"11446498"}}'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.uploads.preflightFileUploadCheck({
    name: newFileName,
    size: 1024 * 1024,
    parent: { id: '0' } satisfies PreflightFileUploadCheckRequestBodyParentField,
  } satisfies PreflightFileUploadCheckRequestBody);
  ```

  ```python Python v10 theme={null}
  client.uploads.preflight_file_upload_check(
      name=new_file_name, size=1024 * 1024, parent=PreflightFileUploadCheckParent(id="0")
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Uploads.PreflightFileUploadCheckAsync(requestBody: new PreflightFileUploadCheckRequestBody() { Name = newFileName, Size = 1024 * 1024, Parent = new PreflightFileUploadCheckRequestBodyParentField() { Id = "0" } });
  ```

  ```java Java v10 theme={null}
  client.getUploads().preflightFileUploadCheck(new PreflightFileUploadCheckRequestBody.Builder().name(newFileName).size(1024 * 1024).parent(new PreflightFileUploadCheckRequestBodyParentField.Builder().id("0").build()).build())
  ```

  ```java Java v5 theme={null}
  String fileName = "My Doc.pdf";
  BoxFolder rootFolder = BoxFolder.getRootFolder(api);
  try {
      folder.canUpload(fileName, 98734576);

      // If the file upload would not have succeeded, it will not be attempted
      folder.uploadFile(fileContents, fileName);
  } catch (BoxAPIException ex) (

  )
  ```

  ```javascript Node v4 theme={null}
  // Verify that uploading a 200MB file named "Preso.ppt" to folder 12345 would succeed
  client.files.preflightUploadFile(
  		'12345',
  		{
  			name: 'Preso.ppt',
  			size: 200000000
  		},
  		null,
  		callback
  	);
  ```
</CodeGroup>

## Check for new file version

To perform a check for a new version of a file, call the
<Link href="/reference/options-files-content">`OPTIONS /files/:id/content`</Link> API with the same
parameters (except for the binary content) as if uploading an actual file.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X OPTIONS "https://api.box.com/2.0/files/12345/content" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{"name":"Contract.pdf", "parent":{"id":"11446498"}}'
  ```

  ```javascript Node v4 theme={null}
  // Check if uploading a larger version of this file will succeed
  client.files.preflightUploadNewFileVersion('87646', {size: 300000000}, null, callback);
  ```
</CodeGroup>

## Checks & Chunk Uploads

When performing a <Link href="/guides/uploads/chunked">chunked upload</Link>, performing a preflight check is not
required as <Link href="/guides/uploads/chunked/create-session">creating an Upload Session</Link> also performs a
preflight check.

## Response codes

When the API call detects any problems, an HTTP `409 Conflict` status code is
returned with a message to describe the possible conflict. If no problems were
discovered, it returns an HTTP `200 OK` status code and the upload can proceed.

A `200 OK` response does not guarantee that the upload call will actually
succeed. Pre-flight checks have shown to reduce failed uploads by over 99%, yet
concurrency issues still come into play when uploading a file.

Highly active folders, common filenames, and accounts near their quota
limits may get a `200 OK` for the preflight check, and then have a real conflict
during the actual upload.

## Response body

In many cases, the preflight check will return valuable data in the API response
when a conflict has been detected. For example, when a name collision has been
detected, the application can use the `SHA-1` that is returned in the error
response to check if the existing file is identical to the one it is trying to
upload.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Commit Upload Session
Source: https://developer.box.com/guides/uploads/chunked/commit-session

Commit a chunked upload session to create a file from the uploaded parts, including parts the server already has.

<RelatedLinks title="REQUIRED GUIDES" />

The final step in a chunked upload is to commit the session.

To commit a file upload session, call the
<Link href="/reference/post-files-upload-sessions-id-commit">`POST /files/upload_sessions/:id/commit`</Link> with a list of uploaded
parts to commit.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://upload.box.com/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" \
       -H "content-type: application/json" \
       -d '{
         "parts": [
           {
             "part_id": "BFDF5379",
             "offset": 0,
             "size": 8388608,
  	     "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
           },
  		     {
             "part_id": "E8A3ED8E",
             "offset": 8388608,
             "size": 1611392,
  	     "sha1": "234b65934ed521fcfe3424b7d814ab8ded5185dc"
           }
         ],
         "attributes": {
           "content_modified_at": "2017-04-08T00:58:08Z"
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.chunkedUploads.createFileUploadSessionCommit(
    uploadSessionId,
    { parts: parts } satisfies CreateFileUploadSessionCommitRequestBody,
    { digest: digest } satisfies CreateFileUploadSessionCommitHeadersInput,
  );
  ```

  ```python Python v10 theme={null}
  client.chunked_uploads.create_file_upload_session_commit(
      upload_session_id, parts, digest
  )
  ```

  ```cs .NET v10 theme={null}
  await client.ChunkedUploads.CreateFileUploadSessionCommitAsync(uploadSessionId: uploadSessionId, requestBody: new CreateFileUploadSessionCommitRequestBody(parts: parts), headers: new CreateFileUploadSessionCommitHeaders(digest: digest));
  ```

  ```swift Swift v10 theme={null}
  try await client.chunkedUploads.createFileUploadSessionCommit(uploadSessionId: uploadSessionId, requestBody: CreateFileUploadSessionCommitRequestBody(parts: parts), headers: CreateFileUploadSessionCommitHeaders(digest: digest))
  ```

  ```java Java v10 theme={null}
  client.getChunkedUploads().createFileUploadSessionCommit(uploadSessionId, new CreateFileUploadSessionCommitRequestBody(parts), new CreateFileUploadSessionCommitHeaders(digest))
  ```

  ```java Java v5 theme={null}
  //Creates the file hash
  byte[] digestBytes = digest.digest();
  //Base64 encoding of the hash
  String digestStr = Base64.encode(digestBytes);

  //Commit the upload session. If there is a failure, abort the commit.
  BoxFile.Info fileInfo = session.commit(digestStr, parts, null, null, null);
  ```

  ```python Python v4 theme={null}
  import hashlib

  sha1 = hashlib.sha1()
  # sha1 should have been updated with all the bytes of the file

  file_atributes = {
      'description': 'A file uploaded via Chunked Upload',
  }

  upload_session = client.upload_session('11493C07ED3EABB6E59874D3A1EF3581')
  uploaded_file = upload_session.commit(sha1.digest(), file_atributes=file_atributes)
  print(f'Successfully uploaded file {uploaded_file.id} with description {uploaded_file.description}')
  ```

  ```javascript Node v4 theme={null}
  // Finalize upload session 93D9A837B45F
  client.files.commitUploadSession(
  	'93D9A837B45F',
  	fileHash.digest('base64'),
  	{description: 'A file I uploaded in chunks!'},
  	callback
  );
  ```
</CodeGroup>

<Info>
  Additionally, any file `attributes` can be passed along with the `parts` to
  further add information to the file. See the <Link href="/reference/post-files-content">`POST /files/content`</Link>
  API for more details.
</Info>

## Part hashes

Each entry in `parts` can include a `sha1` or a `sha512` hash. Include
`sha512` on every entry or on none of them. If only some entries include
`sha512`, the API returns a `400 Bad Request` error with the code
`invalid_parts_field`.

If you used <Link href="/reference/post-files-upload-sessions-id-plan">`POST /files/upload_sessions/:id/plan`</Link>
to skip parts the server already has, list each of those parts in `parts` like
any other part. Use the `part_id`, `offset`, and `size` from the `hits` in the
plan response. Then:

* If the other entries include `sha512`, include the `sha512` value from the
  plan response.
* If the other entries include `sha1` or no hash, leave the hash out of these
  entries.

<Note>
  The `digest` header for the whole file supports SHA-1 only, even if you
  uploaded the parts with SHA-512 digests.
</Note>

## Response

When successful, the API returns an HTTP `201 Created` status code with a
<Link href="/reference/resources/file">`File`</Link> object.

In some cases, creating the parts might not be ready yet and the API will return
a `202 Accepted` status code instead. In this case the application should check
the `retry-after` header and retry committing after the number of seconds
specified.

<RelatedLinks title="RELATED APIS" />


# Create Upload Session
Source: https://developer.box.com/guides/uploads/chunked/create-session



To create an upload session, call the
<Link href="/reference/post-files-upload-sessions">`POST /files/upload_sessions`</Link> API with the desired `file_name`
and `folder_id` to put the file in, as well as the `file_size` of the file to be
uploaded.

To create a session for a new version of an existing file, call the
<Link href="/reference/post-files-id-upload-sessions">`POST /files/:id/upload_sessions`</Link> API instead. In this
case, the `file_name` and `folder_id` are only required when renaming or moving
the file in the process.

## Pre-flight Check

Creating an upload session also performs a <Link href="/guides/uploads/check">preflight check</Link>, making it
unnecessary to do so separately when working with chunked uploads.

## Response

When a session is created successfully the response includes an <Link href="/reference/resources/upload-session">Upload
Session</Link> that provides a session ID, the number of parts, the
part sizes, as well as links to the relevant next API endpoints to use.

```json theme={null}
{
  "id": "F971964745A5CD0C001BBE4E58196BFD",
  "type": "upload_session",
  "session_expires_at": "2012-12-12T10:53:43-08:00",
  "part_size": 1024,
  "total_parts": 1000,
  "num_parts_processed": 455,
  "session_endpoints": {
    "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
    "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
    "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "log_event": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log"
  }
}
```

The upload session defines the size of the parts to use when uploading the
individual parts.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Upload All Files in Folder
Source: https://developer.box.com/guides/uploads/chunked/folder



Sometimes an application might want to upload all files from a folder. To do so
with the SDKs and the CLI requires traversing the folder tree, finding every
file and uploading it accordingly.

<Tabs>
  <Tab title=".NET">
    ```csharp theme={null}
    using System;
    using System.Collections.Generic;
    using System.Diagnostics;
    using System.Dynamic;
    using System.IO;
    using System.Linq;
    using System.Net;
    using System.Net.Sockets;
    using System.Runtime.InteropServices;
    using System.Security.Cryptography;
    using System.Text;
    using System.Threading.Tasks;
    using Box.V2;
    using Box.V2.Auth;
    using Box.V2.Config;
    using Box.V2.Converter;
    using Box.V2.Exceptions;
    using Box.V2.JWTAuth;
    using Box.V2.Models;
    using Newtonsoft.Json;

    namespace BoxPlayground {
        public class Program {
            static void Main (string[] args) {
                ExecuteMainAsync ().Wait ();
            }
            const long CHUNKED_UPLOAD_MINIMUM = 200000;
            private static async Task ExecuteMainAsync () {
                var directoryName = "dotnetUploadFolder";
                var parentFolderId = "0";
                var files = Directory.EnumerateFiles (directoryName);
                using (FileStream fs = new FileStream ("./config.json", FileMode.Open)) {
                    var session = new BoxJWTAuth (BoxConfig.CreateFromJsonFile (fs));
                    var client = session.AdminClient (session.AdminToken ());
                    var folderId = "";
                    try {
                        var createdFolder = await client.FoldersManager.CreateAsync (
                            new BoxFolderRequest {
                                Parent = new BoxRequestEntity {
                                        Id = parentFolderId
                                    },
                                    Name = directoryName
                            });
                        folderId = createdFolder.Id;
                    } catch (BoxConflictException<BoxFolder> e) {
                        folderId = e.ConflictingItems.FirstOrDefault ().Id;
                        System.Console.WriteLine ($"Found existing folder: {folderId}");
                    }
                    var fileUploadTasks = new List<Task<BoxFile>> ();
                    foreach (var file in files) {
                        fileUploadTasks.Add (Task.Run (
                            async () => {
                                System.Console.WriteLine (file);
                                var fileName = file.Split (Path.DirectorySeparatorChar)
                                    .Where ((item) => { return item != directoryName; }).FirstOrDefault ();
                                System.Console.WriteLine (fileName);
                                var fileInfo = new FileInfo (file);
                                var preflightRequest = new BoxPreflightCheckRequest {
                                    Name = fileName,
                                    Size = fileInfo.Length,
                                    Parent = new BoxRequestEntity {
                                    Id = folderId
                                    }
                                };
                                using (FileStream toUpload = new FileStream (file, FileMode.Open)) {
                                    try {
                                        var preflightCheck = await client.FilesManager.PreflightCheck (preflightRequest);
                                        if (toUpload.Length < CHUNKED_UPLOAD_MINIMUM) {
                                            using (SHA1 sha1 = SHA1.Create ()) {
                                                var fileUploadRequest = new BoxFileRequest {
                                                Name = fileName,
                                                Parent = new BoxRequestEntity {
                                                Id = folderId
                                                }
                                                };
                                                var fileSHA = sha1.ComputeHash (toUpload);
                                                System.Console.WriteLine (fileSHA);
                                                return await client.FilesManager.UploadAsync (fileRequest: fileUploadRequest, stream: toUpload, contentMD5: fileSHA);
                                            }
                                        } else {
                                            return await client.FilesManager.UploadUsingSessionAsync (stream: toUpload, fileName: fileName, folderId: folderId);
                                        }
                                    } catch (BoxPreflightCheckConflictException<BoxFile> e) {
                                        if (toUpload.Length < CHUNKED_UPLOAD_MINIMUM) {
                                            using (SHA1 sha1 = SHA1.Create ()) {
                                                var fileSHA = sha1.ComputeHash (toUpload);
                                                return await client.FilesManager.UploadNewVersionAsync (fileName: e.ConflictingItem.Name, fileId: e.ConflictingItem.Id, stream: toUpload, contentMD5: fileSHA);
                                            }
                                        } else {
                                            await client.FilesManager.UploadFileVersionUsingSessionAsync (fileId: e.ConflictingItem.Id, stream: toUpload);
                                            return await client.FilesManager.GetInformationAsync (e.ConflictingItem.Id);
                                        }
                                    }
                                }

                            }));
                    }

                    var uploaded = await Task.WhenAll (fileUploadTasks);
                    foreach (var file in uploaded) {
                        System.Console.WriteLine (file.Id);
                    }
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    public class UploadAllFilesInFolder {

        public static final int CHUNKED_UPLOAD_MINIMUM = 20000;

        public static void main(String[] args) throws Exception {
            String directoryName = "javaUploadFolder";
            Path configPath = Paths.get("config.json");
            Path uploadFolderPath = Paths.get(directoryName);
            try (BufferedReader reader = Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) {
                BoxConfig boxConfig = BoxConfig.readFrom(reader);
                BoxDeveloperEditionAPIConnection client = BoxDeveloperEditionAPIConnection.getAppEnterpriseConnection(boxConfig);
                String parentFolderId = "0";
                String createdFolderId;
                BoxFolder createFolderInParentFolder = new BoxFolder(client, parentFolderId);
                try {
                    BoxFolder.Info createdFolder = createFolderInParentFolder.createFolder(directoryName);
                    System.out.println("Creating folder...");
                    System.out.println(createdFolder.getID());
                    createdFolderId = createdFolder.getID();
            } catch (BoxAPIException e) {
                    String existingFolderId = getIdFromConflict(e.getMessage());
                    System.out.println("Found existing folder...");
                    System.out.println(existingFolderId);
                    createdFolderId = existingFolderId;
            }
                ArrayList < BoxFile.Info > uploadedFiles = new ArrayList < > ();
                try (DirectoryStream < Path > directory = Files.newDirectoryStream(uploadFolderPath)) {

                    for (Path path: directory) {
                    String fileName = path.getFileName().toString();
                    System.out.println(path);
                    System.out.println(fileName);
                    byte[] fileBytes = Files.readAllBytes(path);
                    int fileSize = fileBytes.length;
                    boolean useChunkedUpload = (fileSize > CHUNKED_UPLOAD_MINIMUM) ? true : false;
                    uploadedFiles.add(uploadEachFile(client, createdFolderId, fileName, fileSize, fileBytes, useChunkedUpload));
                    }
                }
                for (BoxFile.Info file: uploadedFiles) {
                    System.out.println(file.getID());
                }
            }
        }

        private static BoxFile.Info uploadEachFile(BoxDeveloperEditionAPIConnection client, String folderId, String fileName, int fileSize, byte[] fileBytes, boolean useChunkedUpload)
        throws IOException, InterruptedException, NoSuchAlgorithmException {
            try {
                BoxFolder folder = new BoxFolder(client, folderId);
                folder.canUpload(fileName, fileSize);
                if (useChunkedUpload) {
                    System.out.println("Using chunked upload...");
                    return folder.uploadLargeFile(new ByteArrayInputStream(fileBytes), fileName, fileSize);
                } else {
                    System.out.println("Using normal upload...");
                    MessageDigest md = MessageDigest.getInstance("SHA-1");
                    try (Formatter formatter = new Formatter()) {
                        for (byte b: md.digest(fileBytes)) {
                            formatter.format("%02x", b);
                        }
                        String fileSHA = formatter.toString();
                        FileUploadParams fileUpload = new FileUploadParams();
                        fileUpload.setContent(new ByteArrayInputStream(fileBytes));
                        fileUpload.setSHA1(fileSHA);
                        fileUpload.setName(fileName);
                        return folder.uploadFile(fileUpload);
                    }
                }
            } catch (BoxAPIException e) {
                if (e.getResponseCode() == 409) {
                    // You can use the ID returned from the conflict error to continue
                    String conflictId = getIdFromConflict(e.getResponse());
                    System.out.println("Found existing file: " + conflictId);
                    BoxFile uploadFileVersion = new BoxFile(client, conflictId);
                    if (useChunkedUpload) {
                        System.out.println("Using chunked upload...");
                        return uploadFileVersion.uploadLargeFile(new ByteArrayInputStream(fileBytes), fileSize);
                    } else {
                        System.out.println("Using normal upload...");
                        MessageDigest md = MessageDigest.getInstance("SHA-1");
                        try (Formatter formatter = new Formatter()) {
                        for (byte b: md.digest(fileBytes)) {
                            formatter.format("%02x", b);
                        }
                        String fileSHA = formatter.toString();
                        uploadFileVersion.uploadVersion(new ByteArrayInputStream(fileBytes), fileSHA);
                        return uploadFileVersion.getInfo();
                        }
                    }
                } else {
                    throw e;
                }
            }
        }

        private static String getIdFromConflict(String message) {
            String id = "";
            Pattern p = Pattern.compile("\"id\":\"[0-9]+\"");
            Pattern p2 = Pattern.compile("[0-9]+");
            Matcher m = p.matcher(message);
            if (m.find()) {
                String sub = m.group();
                Matcher m2 = p2.matcher(sub);
                if (m2.find()) {
                id = m2.group();
                }
            }
            return id;
        }
    }
    ```
  </Tab>

  <Tab title="Node">
    ```js theme={null}
    "use strict";
    const fs = require("fs");
    const path = require("path");
    const box = require("box-node-sdk");
    const crypto = require("crypto");

    let configFile = fs.readFileSync("config.json");
    configFile = JSON.parse(configFile);

    let session = box.getPreconfiguredInstance(configFile);
    let client = session.getAppAuthClient("enterprise");

    const CHUNKED_UPLOAD_MINIMUM = 200000;

    const parentFolderId = "0";
    const directoryName = "uploadFolder";
    let files = [];

    fs.readdirSync(directoryName).forEach(file => {
        files.push({
            fileName: file,
            content: fs.readFileSync(path.join(__dirname, directoryName, file))
        });
    });

    client.folders
        .create(parentFolderId, directoryName)
        .then(createdFolder => {
            console.log(createdFolder);
            return processFiles(client, files, createdFolder.id);
        })
        .catch(err => {
            let conflictId = handleFolderConflictError(err);
            if (conflictId) {
                console.log(`Found an existing folder: ${conflictId}`);
                return processFiles(client, files, conflictId);
            } else {
                throw err;
            }
        })
        .then(results => {
            console.log(results);
        })
        .catch(err => {
            console.log(err);
        });

    function processFiles(client, files, folderId) {
        let fileUploadPromises = [];
        files.forEach(file => {
            fileUploadPromises.push(
                uploadAFile(client, folderId, file.fileName, file.content)
            );
        });

        return Promise.all(fileUploadPromises);
    }

    function uploadAFile(client, folderId, fileName, toUploadFile) {
      return client.files
        .preflightUploadFile(folderId, {
            name: fileName,
            size: toUploadFile.length
        })
        .then(preflightResults => {
          console.log(preflightResults);
          if (toUploadFile.length < CHUNKED_UPLOAD_MINIMUM) {
              console.log("Using normal upload...");
              let fileSha = crypto
                  .createHash("sha1")
                  .update(toUploadFile)
                  .digest("hex");
              client.setCustomHeader("content-md5", fileSha);
              return client.files.uploadFile(folderId, fileName, toUploadFile);
          } else {
            console.log("Using chunked upload...");
            client.setCustomHeader("content-md5", null);
            return client.files
                .getChunkedUploader(
                    folderId,
                    toUploadFile.length,
                    fileName,
                    toUploadFile
                )
                .then(uploader => {
                    return new Promise((resolve, reject) => {
                        uploader.on("error", err => {
                            reject(err);
                        });

                        uploader.on("chunkUploaded", part => {
                            console.log("Part uploaded...");
                            console.log(part);
                        });
                        uploader.on("uploadComplete", file => {
                            console.log("File upload complete!");
                            resolve(file);
                        });
                        console.log("Starting chunked uploader...");
                        uploader.start();
                    });
                });
          }
        })
        .catch(err => {
            let conflictId = handleFileConflictError(err);
            if (conflictId) {
                console.log(`Found existing file with that name: ${conflictId}`);
                return uploadANewFileVersion(client, conflictId, toUploadFile);
            } else {
                throw err;
            }
        });
    }

    function uploadANewFileVersion(client, conflictId, toUploadFile) {
        if (toUploadFile.length < CHUNKED_UPLOAD_MINIMUM) {
            console.log("Using normal upload...");
            let fileSha = crypto
                .createHash("sha1")
                .update(toUploadFile)
                .digest("hex");
            client.setCustomHeader("content-md5", fileSha);
            // You can optionally rename a folder while uploading a new version.
            // let newFileName = "ubuntu-no-gui.iso";
            // let options = {
            //     name: newFileName
            // }
            // return client.files.uploadNewFileVersion(conflictId, options, toUploadFile);
            return client.files.uploadNewFileVersion(conflictId, toUploadFile);
        } else {
            console.log("Using chunked upload...");
            // You can optionally rename a folder while uploading a new version.
            // let newFileName = "ubuntu-no-gui.iso";
            // let options = {
            //     name: newFileName
            // }
            // return client.files.getNewVersionChunkedUploader(conflictId, toUploadFile.length, toUploadFile, options)
            client.setCustomHeader("content-md5", null);
            return client.files
              .getNewVersionChunkedUploader(
                  conflictId,
                  toUploadFile.length,
                  toUploadFile,
                  null
              )
              .then(uploader => {
                  return new Promise((resolve, reject) => {
                      uploader.on("error", err => {
                          reject(err);
                      });

                      uploader.on("chunkUploaded", part => {
                          console.log("Part uploaded...");
                          console.log(part);
                      });
                      uploader.on("uploadComplete", file => {
                          console.log("File upload complete!");
                          resolve(file);
                      });
                      console.log("Starting chunked uploader...");
                      uploader.start();
                  });
              });
        }
    }

    function handleFileConflictError(e) {
        if (e && e.response && e.response.body) {
            let errorBody = e.response.body;
            if (errorBody.status === 409) {
                if (
                    errorBody.context_info &&
                    errorBody.context_info.conflicts &&
                    errorBody.context_info.conflicts
                ) {
                    let conflict = errorBody.context_info.conflicts;
                    if (conflict && conflict.id) {
                        return conflict.id;
                    }
                }
            }
        }
    }

    function handleFolderConflictError(e) {
        if (e && e.response && e.response.body) {
            let errorBody = e.response.body;
            if (errorBody.status === 409) {
                if (
                    errorBody.context_info &&
                    errorBody.context_info.conflicts &&
                    errorBody.context_info.conflicts.length > 0
                ) {
                    let conflict = errorBody.context_info.conflicts[0];
                    if (conflict && conflict.id) {
                        return conflict.id;
                    }
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```sh theme={null}
    box folders:upload ./folder_name_to_upload --parent-folder=$folder_id
    ```
  </Tab>
</Tabs>

## Breakdown

The scripts above use the Box SDKs and the CLI to upload an entire folder. For
the SDK scripts, they start by creating a directory in Box to match the local
folder.

After the new directory is created, it uploads all files within the directory
making sure to use all available Box features to make the uploads successful.

Using the <Link href="/guides/uploads/check">Preflight</Link> API the files are checked for conflicts and
size restrictions before they are uploaded. If a naming conflict is found, the
script instead uploads a new version of that file.

Using the `SHA` hash of the file the scripts add a `content-md5` header on
upload to make sure the file is successfully uploaded to Box without any bytes
lost or tampered with.

Finally, if a file size exceeds 20MB, the script uses the <Link href="/guides/uploads/chunked">Chunked
Upload</Link> feature to make sure uploads are more reliable for larger
files.

<RelatedLinks title="RELATED APIS" />


# Chunked Uploads
Source: https://developer.box.com/guides/uploads/chunked/index



The Chunked Upload API provides a way to reliably upload large files to Box by
chunking them into a sequence of parts that can be uploaded individually.

By using this API the application uploads a file in parts, allowing it to recover
from a failed request more reliably. It means an application only needs to
retry the upload of a single part instead of the entire file.

An additional benefit of chunked uploads is that parts can be uploaded
in parallel, allowing for a potential performance improvement.

## Overview

Chunked uploads require a sequence of API calls to be made.

1. **<Link href="/guides/uploads/chunked/create-session">Create an upload session</Link>**: The application creates an upload session for a new file or new version of a file. The session defines the (new) name of the file, its size, and the parent folder.
2. **<Link href="/guides/uploads/chunked/upload-part">Upload parts</Link>**: The application uploads the separate parts of the file as chunks.
3. **<Link href="/guides/uploads/chunked/commit-session">Commit session</Link>**: The application commits the session, at which moment the integrity of the file is checked before it is placed in the location specified when the session was created.

<Info>
  Most of <Link href="/guides/uploads/chunked/with-sdks">the Box SDKs support chunked uploads</Link> out of the Box, removing
  the complexity from the application code.
</Info>

## Restrictions

The Chunked Upload API is intended for large files with a minimum size of 20MB.
The API does not support uploads of files with a size smaller than this.

This API does not support re-uploading or overwriting of parts in a session.
Once a part has been uploaded, it is immutable.

The lifetime of an upload session is 7 days. During this time, the client can
upload parts at their own pace.

To avoid wasting resources, and avoid potential data corruption, the client should
make sure that the underlying file has not been changed on disk since beginning
the upload.


# Upload Part
Source: https://developer.box.com/guides/uploads/chunked/upload-part

Upload each part of a large file to a chunked upload session, using a SHA-1 or SHA-512 digest to verify the content.

<RelatedLinks title="REQUIRED GUIDES" />

When you want to upload a large file,
you can split it into smaller parts and
upload them using the Upload Part API.

## Create Upload Session

First, <Link href="/guides/uploads/chunked/create-session">create an upload session</Link>. The resulting
object defines the size of each part and the number of parts to upload.

```json theme={null}
{
  "id": "F971964745A5CD0C001BBE4E58196BFD",
  "type": "upload_session",
  "session_expires_at": "2012-12-12T10:53:43-08:00",
  "part_size": 1024,
  "total_parts": 1000,
  "num_parts_processed": 455,
  "session_endpoints": {
    "upload_part": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "commit": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
    "abort": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "list_parts": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
    "status": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
    "log_event": "https://upload.box.com/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log"
  }
}
```

## Split File

Split the file into parts to be uploaded.
If you want to use the command line,
use the `split` command:

```bash theme={null}
split -b <PART_SIZE> <FILE_NAME> <YOUR_PART_NAME>
```

For example:

```bash theme={null}
split -b 8388608 video.mp3 videopart
```

This will result in your file divided into several files.

## Get SHA Digest

You can use a SHA-1 or a SHA-512 digest to verify each part.
To get the value for the `SHA` digest,
use one of the following openSSL commands
to encode the file part:

```bash theme={null}
# SHA-1
openssl sha1 -binary <FILE_PART_NAME> | base64

# SHA-512
openssl sha512 -binary <FILE_PART_NAME> | base64
```

For example:

```bash theme={null}
openssl sha1 -binary videoparta | base64
```

The result is a base-64 encoded message used to verify the upload.
Pass it in the `digest` header as `sha=BASE64_ENCODED_DIGEST` for SHA-1,
or `sha-512=BASE64_ENCODED_DIGEST` for SHA-512.

## Upload Part

Upload the bytes for the part you want to upload, specifying the byte
range for the part and the `SHA` digest to ensure the content is
uploaded correctly.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://upload.box.com/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "digest: sha=fpRyg5eVQletdZqEKaFlqwBXJzM=" \
       -H "content-range: bytes 8388608-16777215/445856194" \
       -H "content-type: application/octet-stream" \
       --data-binary @<FILE_NAME>
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.chunkedUploads.uploadFilePart(
    acc.uploadSessionId,
    generateByteStreamFromBuffer(chunkBuffer),
    {
      digest: digest,
      contentRange: contentRange,
    } satisfies UploadFilePartHeadersInput,
  );
  ```

  ```python Python v10 theme={null}
  client.chunked_uploads.upload_file_part(
      acc.upload_session_id,
      generate_byte_stream_from_buffer(chunk_buffer),
      digest,
      content_range,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.ChunkedUploads.UploadFilePartAsync(uploadSessionId: acc.UploadSessionId, requestBody: Utils.GenerateByteStreamFromBuffer(buffer: chunkBuffer), headers: new UploadFilePartHeaders(digest: digest, contentRange: contentRange));
  ```

  ```swift Swift v10 theme={null}
  try await client.chunkedUploads.uploadFilePart(uploadSessionId: acc.uploadSessionId, requestBody: Utils.generateByteStreamFromBuffer(buffer: chunkBuffer), headers: UploadFilePartHeaders(digest: digest, contentRange: contentRange))
  ```

  ```java Java v10 theme={null}
  client.getChunkedUploads().uploadFilePart(acc.getUploadSessionId(), generateByteStreamFromBuffer(chunkBuffer), new UploadFilePartHeaders(digest, contentRange))
  ```

  ```java Java v5 theme={null}
  //Reading a large file
  FileInputStream fis = new FileInputStream("My_Large_File.txt");
  //Create the digest input stream to calculate the digest for the whole file.
  DigestInputStream dis = new DigestInputStream(fis, digest);

  List<BoxFileUploadSessionPart> parts = new ArrayList<BoxFileUploadSessionPart>();

  //Get the part size. Each uploaded part should match the part size returned as part of the upload session.
  //The last part of the file can be less than part size if the remaining bytes of the last part is less than
  //the given part size
  long partSize = sessionInfo.getPartSize();
  //Start byte of the part
  long offset = 0;
  //Overall of bytes processed so far
  long processed = 0;
  while (processed < fileSize) {
      long diff = fileSize - processed;
      //The size last part of the file can be less than the part size.
      if (diff < partSize) {
          partSize = diff;
      }

      //Upload a part. It can be uploaded asynchorously
      BoxFileUploadSessionPart part = session.uploadPart(dis, offset, (int)partSize, fileSize);
      parts.add(part);

      //Increase the offset and proceesed bytes to calculate the Content-Range header.
      processed += partSize;
      offset += partSize;
  }
  ```

  ```python Python v4 theme={null}
  upload_session = client.upload_session('11493C07ED3EABB6E59874D3A1EF3581')
  offset = upload_session.part_size * 3
  total_size = 26000000
  part_bytes = b'abcdefgh'
  part = upload_session.upload_part_bytes(part_bytes, offset, total_size)
  print(f'Successfully uploaded part ID {part["part_id"]}')
  ```

  ```javascript Node v4 theme={null}
  // Upload the part starting at byte offset 8388608 to upload session '93D9A837B45F' with part ID 'feedbeef'
  client.files.uploadPart('93D9A837B45F', part, 8388608, 2147483648, {part_id: 'feedbeef'}, callback);
  ```
</CodeGroup>

### Content Range

Each part’s size must be exactly equal in size to the part size
specified in the upload session that you created.
One exception is the last part of the file, as
this can be smaller. The `Content-Range` parameter
definition follows this pattern:

```yaml theme={null}
-H "Content-Range: bytes <LOWER_BOUND>-<HIGHER_BOUND>/<TOTAL_SIZE>"
```

When providing the value for `Content-Range`, remember that:

* The lower bound of each part's byte range must be a multiple of the part size.
* The higher bound must be a multiple of the part size - 1.

For example, if the part size is `8388608`,
the content range for the first two parts will be:

```yaml theme={null}
-H "Content-Range: bytes 0-8388607/32127641" \ ## first part
-H "Content-Range: bytes 8388608-16777215/32127641" \ ## second part
```

## Response

After each upload, the resulting response includes
the `ID` and `SHA` hashes of the part uploaded.

```json theme={null}
{
  "part_id": "6F2D3486",
  "offset": 16777216,
  "size": 3222784,
  "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
  "sha512": "ae78a0ca28abffe70ac9aba830556cd6eb3fcf1501dbd9b2d7a5f45992c00812cb07b51bbd0a9174e2295671c0e86f30354afa91d281d4fbee6a323a483d6383"
}
```

The response always includes `sha512`, as a lowercase hexadecimal string.
It includes `sha1` only if you uploaded the part with a SHA-1 digest.

<Warning>
  Keep all the JSON responses from all part
  uploads as they are needed to <Link href="/guides/uploads/chunked/commit-session">commit the session</Link>.
</Warning>

## Range Overlap

If a part upload request fails with any error code
`range_overlaps_existing_part` then the application
made a mistake in cutting up the file into parts
and tried to upload a part into a range that already had
content uploaded for it. The application should assume
that this last part was not persisted to the session.

## Parallel uploads

Although you can upload the parts in parallel, try to upload them in
order as much as is possible. Parts with a lower byte offset should be uploaded
before parts with a higher byte offset.

The recommended approach is to upload 3 to 5 parts in parallel from a queue
of parts, ordered by byte offset. If a part upload fails, retry it
before you upload further parts.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Chunked Upload with SDKs
Source: https://developer.box.com/guides/uploads/chunked/with-sdks



The Box SDKs make it possible to perform a chunked upload with the built-in
SDK methods.

The SDKs also support uploading new versions of files through similar methods.

<RelatedLinks title="RELATED APIS" />


# Upload New File
Source: https://developer.box.com/guides/uploads/direct/file



<RelatedLinks title="REQUIRED GUIDES" />

To upload a file to Box via direct upload, make an API call to the
<Link href="/reference/post-files-content">`POST /files/content`</Link> API with the content of the file, the desired
file name, and the folder ID.

<Tip>
  To upload files to the Archive folder, you need to first enable the <Link href="/guides/api-calls/permissions-and-errors/scopes">Global
  Content Manager</Link> (GCM) scope in the Developer Console.
</Tip>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://upload.box.com/api/2.0/files/content" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: multipart/form-data" \
       -F attributes='{"name":"Contract.pdf", "parent":{"id":"11446498"}}' \
       -F file=@<FILE_NAME>
  ```

  ```typescript Node/TypeScript v10 theme={null}
  const fs = require('fs');

  const attrs = { name: 'filename.txt', parent: { id: '0' } };
  const body = {
    attributes: attrs,
    file: fs.createReadStream('filename.txt'),
  };
  const files = await client.uploads.uploadFile(body);
  const file = files.entries[0];
  console.log(`File uploaded with id ${file.id}, name ${file.name}`);
  ```

  ```python Python v10 theme={null}
  client.uploads.upload_file(
      UploadFileAttributes(
          name=new_file_name, parent=UploadFileAttributesParentField(id="0")
      ),
      file_content_stream,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Uploads.UploadFileAsync(requestBody: new UploadFileRequestBody(attributes: new UploadFileRequestBodyAttributesField(name: newFileName, parent: new UploadFileRequestBodyAttributesParentField(id: "0")), file: fileContentStream));
  ```

  ```swift Swift v10 theme={null}
  // Create InputStream for a file based on URL
  guard let fileStream = InputStream(url: URL(string: "<URL_TO_YOUR_FILE>")!) else {
      fatalError("Could not read a file")
  }

  // Create a request body with the required parameters
  let requestBody = UploadFileRequestBody(
      attributes: UploadFileRequestBodyAttributesField(
          name: "filename.txt",
          parent: UploadFileRequestBodyAttributesFieldParentField(id: "0")
      ),
      file: fileStream
  )

  // Call uploadFile method
  let files = try await client.uploads.uploadFile(requestBody: requestBody)

  // Print some data from the reponse
  if let file = files.entries?[0] {
      print("File uploaded with id \(file.id), name \(file.name!)")
  }
  ```

  ```java Java v10 theme={null}
  client.getUploads().uploadFile(new UploadFileRequestBody(new UploadFileRequestBodyAttributesField(newFileName, new UploadFileRequestBodyAttributesParentField("0")), fileContentStream))
  ```

  ```java Java v5 theme={null}
  BoxFolder rootFolder = BoxFolder.getRootFolder(api);
  FileInputStream stream = new FileInputStream("My File.txt");
  BoxFile.Info newFileInfo = rootFolder.uploadFile(stream, "My File.txt");
  stream.close();
  ```

  ```python Python v4 theme={null}
  folder_id = '22222'
  new_file = client.folder(folder_id).upload('/home/me/document.pdf')
  print(f'File "{new_file.name}" uploaded to Box with file ID {new_file.id}')
  ```

  ```cs .NET v6 theme={null}
  using (FileStream fileStream = new FileStream(filePath, FileMode.Open))
  {
      BoxFileRequest requestParams = new BoxFileRequest()
      {
          Name = uploadFileName,
          Parent = new BoxRequestEntity() { Id = "0" }
      };

      BoxFile file = await client.FilesManager.UploadAsync(requestParams, fileStream);
  }
  ```

  ```javascript Node v4 theme={null}
  var fs = require('fs');
  var stream = fs.createReadStream('/path/to/My File.pdf');
  var folderID = '0'
  client.files.uploadFile(folderID, 'My File.pdf', stream)
  	.then(file => {
  		/* file -> {
  			total_count: 1,
  			entries: 
  			[ { type: 'file',
  				id: '11111',
  				file_version: 
  					{ type: 'file_version',
  					id: '22222',
  					sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' },
  				sequence_id: '0',
  				etag: '0',
  				sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33',
  				name: 'My File.pdf',
  				description: '',
  				size: 68431,
  				path_collection: 
  					{ total_count: 1,
  					entries: 
  					[ { type: 'folder',
  						id: '0',
  						sequence_id: null,
  						etag: null,
  						name: 'All Files' } ] },
  				created_at: '2017-05-16T15:18:02-07:00',
  				modified_at: '2017-05-16T15:18:02-07:00',
  				trashed_at: null,
  				purged_at: null,
  				content_created_at: '2017-05-16T15:18:02-07:00',
  				content_modified_at: '2017-05-16T15:18:02-07:00',
  				created_by: 
  					{ type: 'user',
  					id: '33333',
  					name: 'Test User',
  					login: 'test@example.com' },
  				modified_by: 
  					{ type: 'user',
  					id: '33333',
  					name: 'Test User',
  					login: 'test@example.com' },
  				owned_by: 
  					{ type: 'user',
  					id: '33333',
  					name: 'Test User',
  					login: 'test@example.com' },
  				shared_link: null,
  				parent: 
  					{ type: 'folder',
  					id: '0',
  					sequence_id: null,
  					etag: null,
  					name: 'All Files' }
  				item_status: 'active' } ] }
  		*/
  	});
  ```
</CodeGroup>

<Info>
  **Preflight check**

  To prevent wasting time and bandwidth uploading a file that is going to be
  rejected it is recommended to perform a <Link href="/guides/uploads/check">pre-flight check</Link> before
  uploading the file.
</Info>

## Request Format

The request body of this API uses a content type of `multipart/form-data`. This
is used to transmit two parts, namely the file attributes and the file's actual
content.

The first part is called `attributes` and contains a JSON object with
information about the file, including the name of the file and the `id` of the
parent folder.

The following is an example of a `test.txt` being uploaded to the root folder of
the user.

```sh theme={null}
POST /api/2.0/files/content HTTP/1.1
Host: upload.box.com
Authorization: Bearer [ACCESS_TOKEN]
content-length: 343
content-type: multipart/form-data; boundary=------------------------9fd09388d840fef1

--------------------------9fd09388d840fef1
content-disposition: form-data; name="attributes"

{"name":"test.txt", "parent":{"id":"0"}}
--------------------------9fd09388d840fef1
content-disposition: form-data; name="file"; filename="test.txt"
content-type: text/plain

Test file text.

--------------------------9fd09388d840fef1--
```

<Warning>
  The `attributes` JSON part of the multi-part body must come before the `file`
  part of the multipart form data. When out of order, the API will return an HTTP
  `400` status code with an error code of `metadata_after_file_contents`.
</Warning>

## Options

To learn more about all the parameters available when uploading files, head over
to the <Link href="/reference/post-files-content">reference documentation for this API call</Link>. These parameters
include a `content-md5` that can be set to ensure a file is not corrupted in
transit, and the ability to explicitly specify the file creation time at a
different time than the upload time.

## Restrictions

Direct uploads are limited to a maximum file size of 50MB. For larger files,
please use the <Link href="/guides/uploads/chunked">chunked upload APIs</Link>.

Upload limits are dictated by the type of account of the authenticated user.
More information can be found <Link href="https://support.box.com/hc/en-us/articles/360043697314-Understand-the-Maximum-File-Size-You-Can-Upload-to-Box">in our product documentation on this topic</Link>.

<RelatedLinks title="RELATED APIS" />


# Upload File Version
Source: https://developer.box.com/guides/uploads/direct/file-version



<RelatedLinks title="REQUIRED GUIDES" />

To upload a new version of a file to Box via direct upload, make an API call to
the <Link href="/reference/post-files-id-content">`POST /files/:id/content`</Link> API with the content of the file, the
desired file name, and the folder ID.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://upload.box.com/api/2.0/files/12345/content" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: multipart/form-data" \
       -F attributes='{"name":"Contract.pdf", "parent":{"id":"11446498"}}' \
       -F file=@<FILE_NAME>
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.uploads.uploadFileVersion(file.id, {
    attributes: {
      name: file.name!,
    } satisfies UploadFileVersionRequestBodyAttributesField,
    file: generateByteStream(20),
  } satisfies UploadFileVersionRequestBody);
  ```

  ```python Python v10 theme={null}
  client.uploads.upload_file_version(
      uploaded_file.id,
      UploadFileVersionAttributes(name=new_file_version_name),
      new_file_content_stream,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Uploads.UploadFileVersionAsync(fileId: uploadedFile.Id, requestBody: new UploadFileVersionRequestBody(attributes: new UploadFileVersionRequestBodyAttributesField(name: newFileVersionName), file: newFileContentStream));
  ```

  ```java Java v10 theme={null}
  client.getUploads().uploadFileVersion(uploadedFile.getId(), new UploadFileVersionRequestBody(new UploadFileVersionRequestBodyAttributesField(newFileVersionName), newFileContentStream))
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  FileInputStream stream = new FileInputStream("My File.txt");
  file.uploadNewVersion(stream);
  ```

  ```python Python v4 theme={null}
  file_id = '11111'
  file_path = '/path/to/file.pdf'

  updated_file = client.file(file_id).update_contents(file_path)
  print(f'File "{updated_file.name}" has been updated')
  ```

  ```cs .NET v6 theme={null}
  using (FileStream fileStream = new FileStream(filePath, FileMode.Open))
  {
      BoxFile file = await client.FilesManager
          .UploadNewVersionAsync("File v2.pdf", "11111", fileStream);
  }
  ```

  ```javascript Node v4 theme={null}
  var fs = require('fs');
  var stream = fs.createReadStream('/path/to/file.pdf');
  client.files.uploadNewFileVersion('11111', stream)
  	.then(file => {
          /* file -> {
              total_count: 1,
              entries: 
              [ { type: 'file',
                  id: '11111',
                  file_version: 
                      { type: 'file_version',
                      id: '22222',
                      sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33' },
                  sequence_id: '0',
                  etag: '0',
                  sha1: '0beec7b5ea3f0fdbc95d0dd47f3c5bc275da8a33',
                  name: 'My File.pdf',
                  description: '',
                  size: 68431,
                  path_collection: 
                      { total_count: 1,
                      entries: 
                      [ { type: 'folder',
                          id: '0',
                          sequence_id: null,
                          etag: null,
                          name: 'All Files' } ] },
                  created_at: '2017-05-16T15:18:02-07:00',
                  modified_at: '2017-05-16T15:18:02-07:00',
                  trashed_at: null,
                  purged_at: null,
                  content_created_at: '2017-05-16T15:18:02-07:00',
                  content_modified_at: '2017-05-16T15:18:02-07:00',
                  created_by: 
                      { type: 'user',
                      id: '33333',
                      name: 'Test User',
                      login: 'test@example.com' },
                  modified_by: 
                      { type: 'user',
                      id: '33333',
                      name: 'Test User',
                      login: 'test@example.com' },
                  owned_by: 
                      { type: 'user',
                      id: '33333',
                      name: 'Test User',
                      login: 'test@example.com' },
                  shared_link: null,
                  parent: 
                      { type: 'folder',
                      id: '0',
                      sequence_id: null,
                      etag: null,
                      name: 'All Files' }
                  item_status: 'active' } ] }
          */
      })
  ```
</CodeGroup>

<Info>
  **Preflight check**

  To prevent wasting time and bandwidth uploading a file that is going to be
  rejected it is recommended to perform a <Link href="/guides/uploads/check">pre-flight check</Link> before
  uploading the file.
</Info>

## Request Format

The request body of this API uses a content type of `multipart/form-data`. This
is used to transmit two parts, namely the file attributes and the file's actual
content.

The first part is called `attributes` and contains a JSON object with
information about the file, including the name of the file and the `id` of the
parent folder.

The following is an example of a `test.txt` being uploaded to the root folder of
the user.

```sh theme={null}
POST /api/2.0/files/123/content HTTP/1.1
Host: upload.box.com
Authorization: Bearer [ACCESS_TOKEN]
content-length: 343
content-type: multipart/form-data; boundary=------------------------9fd09388d840fef1

--------------------------9fd09388d840fef1
content-disposition: form-data; name="attributes"

{"name":"test.txt", "parent":{"id":"0"}}
--------------------------9fd09388d840fef1
content-disposition: form-data; name="file"; filename="test.txt"
content-type: text/plain

Test file text.

--------------------------9fd09388d840fef1--
```

<Warning>
  The `attributes` JSON part of the multi-part body must come before the `file`
  part of the multipart form data. When out of order, the API will return an HTTP
  `400` status code with an error code of `metadata_after_file_contents`.
</Warning>

## Options

To learn more about all the parameters available when uploading files, head over
to the <Link href="/reference/post-files-id-content">reference documentation for this API call</Link>. These parameters
include a `content-md5` that can be set to ensure a file is not corrupted in
transit, and the ability to explicitly specify the file creation time at a
different time than the upload time.

For file versions an additional <Link href="/guides/api-calls/ensure-consistency">`if-match` header</Link> can be passed
along to prevent overwriting a file that has already been updated since the
application last inspected the content.

## Restrictions

Direct uploads are limited to a maximum file size of 50MB. For larger files,
please use the <Link href="/guides/uploads/chunked">chunked upload APIs</Link>.

Upload limits are dictated by the type of account of the authenticated user.
More information can be found <Link href="https://support.box.com/hc/en-us/articles/360043697314-Understand-the-Maximum-File-Size-You-Can-Upload-to-Box">in our product documentation on this topic</Link>.

<RelatedLinks title="RELATED APIS" />


# Direct Uploads
Source: https://developer.box.com/guides/uploads/direct/index



The most straightforward way to upload a file to Box is using a direct upload.
Direct uploads allow an application to upload a file in one request. For file
sizes over 50MB we recommend using the <Link href="/guides/uploads/chunked">chunked upload endpoint</Link>.

The maximum file size limit for uploads to Box varies depending on your account
type. For more details, please refer to our [pricing comparison page][pcp].

* Free personal: 250 MB
* Starter: 2 GB
* Business: 5 GB
* Business Plus: 15 GB
* Enterprise: 50 GB
* Digital Workplace Suite: 50 GB
* Digital Workplace Global Suite: 50 GB
* Digital Business Suite: 50 GB
* Digital Business Global Suite: 50 GB
* Enterprise Plus: 150 GB
* Enterprise Advanced: 500 GB

To confirm the file size limit for your account, log into Box. Click on the
circle in the top right corner and select **Account Settings** from the dropdown
menu. On the page that displays, scroll down to the **Account Details**
section. Your **Max File Size** is listed here.

## Upload domain

Uploads to Box happen via a different domain (`upload.box.com`) than regular API
calls. This is something to keep in mind when writing your own upload code. All
official Box SDKs will take care of choosing the right domain for each API call.

[pcp]: https://www.box.com/pricing


# Uploads
Source: https://developer.box.com/guides/uploads/index

Upload files to Box using direct upload for files up to 50 MB or chunked upload for larger files with retry control.

The Box API supports two distinct methods of file upload. The <Link href="/guides/uploads/direct">direct file
upload API</Link> supports files up to 50MB in size and sends all the binary
data to the Box API in 1 API request.

The <Link href="/guides/uploads/chunked">chunked upload APIs</Link> support files from 20MB in size and allow an
application to upload the file in parts, allowing for more control to catch any
errors and retry parts individually.

<Tip>
  To upload files to the Archive folder, you need to first enable the <Link href="/guides/api-calls/permissions-and-errors/scopes">Global
  Content Manager</Link> (GCM) scope in the Developer Console.
</Tip>

## Quick example

Upload a file to the root folder:

```bash theme={null}
curl -X POST https://upload.box.com/api/2.0/files/content \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -F attributes='{"name": "example.pdf", "parent": {"id": "0"}}' \
  -F file=@example.pdf
```

## Upload limits

Upload limits are dictated by the type of account of the authenticated user.
More information can be found <Link href="https://support.box.com/hc/en-us/articles/360043697314-Understand-the-Maximum-File-Size-You-Can-Upload-to-Box">in our product documentation on this topic</Link>.

## Preflight check

The Pre-flight check API allows an application to verify that a file will be
accepted by Box before it uploads any bytes. It can both be used for new files,
as well as uploading new versions of existing files.

<Card href={localizeLink("/guides/uploads/check")} title="Learn more about pre-flight checks" />

## Upload domain

Uploads to Box happen via a different domain (`upload.box.com`) than regular API
calls. This is something to keep in mind when writing your own upload code. All
the Box SDKs will take care of choosing the right domain for the right API call.

[fsizes]: https://support.box.com/hc/en-us/articles/360043697314-Understand-the-Maximum-File-Size-You-Can-Upload-to-Box


# Recursively upload a folder with Python
Source: https://developer.box.com/guides/uploads/tutorials/recursive-folder-upload-python

Learn how to upload a local folder tree to Box with a recursive Python script that creates folders, uploads files, and handles naming conflicts.

This tutorial shows you how to build a recursive upload script that
combines <Link href="/guides/uploads/direct">direct uploads</Link>,
<Link href="/guides/uploads/chunked">chunked uploads</Link>, and
<Link href="/guides/uploads/check">preflight checks</Link> to handle
duplicate files, duplicate folders, and large files automatically.

<SignupCTA>
  A free Box developer account gives you a Developer Console, API access, and a test environment so you can upload entire folder trees to Box and build content workflows.
</SignupCTA>

<Info>
  The code samples in this tutorial use the
  <Link href="https://github.com/box/box-python-sdk">Box Python SDK (v10)</Link>.
</Info>

## Prerequisites

* A Box application with the <Link href="/guides/api-calls/permissions-and-errors/scopes/#read-and-write-all-files-and-folders">Read and write all files and folders stored in Box</Link> scope (`root_readwrite`) enabled
* Python 3.8 or later installed on your computer
* The Box Python SDK installed (`pip install "boxsdk~=10"`)
* An authenticated <Link href="/guides/authentication">Box client</Link>
* Completion of the <Link href="/guides/uploads/tutorials/upload-methods-python">Upload methods with Python</Link> tutorial, which defines the `file_upload` and `file_upload_chunked` helper functions this tutorial reuses to avoid duplicating upload logic

## Handle duplicate folders

Before you access a subfolder, check whether it already exists in Box.
If a folder with the same name exists, use the existing folder instead of
creating a new one:

```python Python v10 theme={null}
from box_sdk_gen import BoxAPIError, CreateFolderParent


def create_or_get_box_folder(client, folder_name, parent_folder_id):
    try:
        folder = client.folders.create_folder(
            folder_name, CreateFolderParent(id=parent_folder_id)
        )
    except BoxAPIError as err:
        if err.response_info.body.get("code") == "item_name_in_use":
            folder_id = err.response_info.context_info["conflicts"][0][
                "id"
            ]
            folder = client.folders.get_folder_by_id(folder_id)
        else:
            raise
    return folder
```

## Recursively upload a folder

Combine the helper functions into a single recursive function that walks the
local directory tree. For each item, the function:

1. Creates the folder in Box, or retrieves the existing folder, and then recurses into it.
2. Checks the file size to choose a direct or chunked upload. Files that are **20 MB or larger** use chunked upload; smaller files use direct upload.
3. Uploads a new version when a file with the same name already exists, by using the helpers from the upload methods tutorial.

```python Python v10 theme={null}
import pathlib

MIN_CHUNKED_SIZE = 20 * 1024 * 1024  # 20 MB


def folder_upload(
    client,
    box_base_folder_id,
    local_folder_path,
    min_chunked_size=MIN_CHUNKED_SIZE,
):
    local_folder = pathlib.Path(local_folder_path)
    for item in local_folder.iterdir():
        if item.is_dir():
            new_box_folder = create_box_folder(
                client, item.name, box_base_folder_id
            )
            folder_upload(client, new_box_folder.id, item, min_chunked_size)
        else:
            if item.stat().st_size < min_chunked_size:
                file_upload(client, str(item), box_base_folder_id)
            else:
                file_upload_chunked(client, str(item), box_base_folder_id)
```

The `min_chunked_size` parameter defaults to 20 MB, which is the minimum size for
<Link href="/guides/uploads/chunked">chunked uploads</Link>. You can
increase this threshold, but you cannot decrease it.

## Complete example

The following script authenticates a Box client, creates a destination
folder (or reuses an existing one), and recursively uploads the contents of a
local directory. It reuses the `create_box_folder` helper to get or create the
destination folder in the root folder (`"0"`):

```python Python v10 theme={null}
def main():
    client = get_authenticated_client()
    demo_folder = create_box_folder(client, "my-upload-folder", "0")
    folder_upload(client, demo_folder.id, "/path/to/local/folder")


if __name__ == "__main__":
    main()
```

## Resources

* <Link href="https://github.com/box-community/box-python-gen-workshop/blob/main/workshops/files/files.md">Box Python SDK workshop: files and uploads</Link>
* <Link href="https://github.com/box/box-python-sdk/blob/main/docs/uploads.md">Box Python SDK: Uploading a file</Link>
* <Link href="https://github.com/box/box-python-sdk/blob/main/docs/chunked_uploads.md">Box Python SDK: Chunked uploads</Link>

<RelatedLinks title="RELATED GUIDES" />


# Upload methods with Python
Source: https://developer.box.com/guides/uploads/tutorials/upload-methods-python

Learn how to upload files to Box with the Python SDK by using direct upload and chunked upload, including the `upload_big_file` convenience method, manual upload sessions, preflight checks, and conflict handling.

This tutorial covers two ways to upload content to Box by using the Python SDK: <Link href="/guides/uploads/direct">direct upload</Link> and <Link href="/guides/uploads/chunked">chunked upload</Link>. For chunked upload, you can use the SDK convenience method or manage the upload session yourself. Learn how each method works and how to combine <Link href="/guides/uploads/check">preflight checks</Link> with conflict handling to upload new files or update existing ones.

| Method | Best for | Minimum size | Maximum size |
| - | - | - | - |
| <Link href="/guides/uploads/direct">Direct upload</Link> | Small files, simple workflows | No minimum | 50 MB |
| <Link href="/guides/uploads/chunked">Chunked upload</Link> | Large files | 20 MB | No limit |

<SignupCTA>
  A free Box developer account gives you a Developer Console, API access, and a test environment so you can start uploading files to Box and building content workflows.
</SignupCTA>

<Info>
  The code samples in this tutorial use the
  <Link href="https://github.com/box/box-python-sdk">Box Python SDK (v10)</Link>.
</Info>

## Prerequisites

* A Box application with the <Link href="/guides/api-calls/permissions-and-errors/scopes/#read-and-write-all-files-and-folders">Read and write all files and folders stored in Box</Link> scope (`root_readwrite`) enabled
* Python 3.8 or later installed on your computer
* The Box Python SDK installed (`pip install "boxsdk~=10"`)
* An authenticated <Link href="/guides/authentication">Box client</Link>

## Direct upload

To upload a file, call the `upload_file` method. For more information about the direct upload API, see
<Link href="/guides/uploads/direct/file">Upload New File</Link>.

Run a <Link href="/guides/uploads/check">preflight check</Link> first. If
a file with the same name already exists, the error response includes the
conflicting file ID. If you don't want to override the content of the file with
that name, change the name and upload it as a new file. The sample below assumes
you want to override the file content, so it uses that ID to upload a
<Link href="/guides/uploads/direct/file-version">new version</Link>:

```python Python v10 theme={null}
import os

from box_sdk_gen import (
    BoxAPIError,
    PreflightFileUploadCheckParent,
    UploadFileAttributes,
    UploadFileAttributesParentField,
    UploadFileVersionAttributes,
)


def upload_file_or_file_version(client, file_path, folder_id):
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)

    with open(file_path, "rb") as file_stream:
        try:
            client.uploads.preflight_file_upload_check(
                name=file_name,
                size=file_size,
                parent=PreflightFileUploadCheckParent(id=folder_id),
            )
            files = client.uploads.upload_file(
                UploadFileAttributes(
                    name=file_name,
                    parent=UploadFileAttributesParentField(id=folder_id),
                ),
                file_stream,
            )
            return files.entries[0]
        except BoxAPIError as err:
            if err.response_info.code != "item_name_in_use":
                raise
            file_id = err.response_info.context_info["conflicts"]["id"]
            file_stream.seek(0)
            files = client.uploads.upload_file_version(
                file_id,
                UploadFileVersionAttributes(name=file_name),
                file_stream,
            )
            return files.entries[0]
```

Calling `upload_file` on a folder creates a new file. Calling
`upload_file_version` on an existing file uploads a new version.

## Chunked upload

Use <Link href="/guides/uploads/chunked">chunked upload</Link> for files that are
**20 MB or larger**. Every chunked upload works through an
<Link href="/guides/uploads/chunked/create-session">upload session</Link>: you
create a session,
<Link href="/guides/uploads/chunked/upload-part">upload the file in parts</Link>,
and <Link href="/guides/uploads/chunked/commit-session">commit the session</Link>
to finalize the file. You have two options:

* **Convenience method**: `upload_big_file` runs all three steps for you.
* **Manual upload session**: create the session, upload each part, and commit it
  yourself when you need full control.

### Convenience method

The `upload_big_file` method uploads the file in parts automatically. Run a
preflight check first so that you can handle name conflicts before you start the
upload. When a file with the same name already exists, `upload_chunked_file`
creates a session for the existing file and uploads a new version with the
`upload_file_via_session` helper shown in the next section.

```python Python v10 theme={null}
import os

from box_sdk_gen import BoxAPIError, PreflightFileUploadCheckParent


def upload_chunked_file(client, file_path, folder_id):
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)
    parent = PreflightFileUploadCheckParent(id=folder_id)

    try:
        client.uploads.preflight_file_upload_check(
            name=file_name,
            size=file_size,
            parent=parent,
        )
        with open(file_path, "rb") as file_stream:
            return client.chunked_uploads.upload_big_file(
                file_stream, file_name, file_size, folder_id
            )

    except BoxAPIError as err:
        if err.response_info.code != "item_name_in_use":
            raise

        file_id = err.response_info.context_info["conflicts"]["id"]
        upload_session = (
            client.chunked_uploads.create_file_upload_session_for_existing_file(
                file_id, file_size, file_name
            )
        )
        return upload_file_via_session(
            client, file_path, file_size, upload_session
        )
```

### Manual upload session

For full control over the upload, manage the session yourself. The
`upload_file_via_session` helper uploads every part and commits the session for
a session you pass in:

```python Python v10 theme={null}
import base64
import hashlib
from io import BytesIO

from box_sdk_gen import UploadPart


def upload_file_via_session(client, file_path, file_size, upload_session):
    file_sha1 = hashlib.sha1()
    parts: list[UploadPart] = []

    upload_part_url = upload_session.session_endpoints.upload_part
    commit_url = upload_session.session_endpoints.commit

    with open(file_path, "rb") as file_stream:
        part_size = upload_session.part_size
        for part_num in range(upload_session.total_parts):
            offset = part_num * part_size
            remaining = file_size - offset
            chunk_size = min(part_size, remaining)
            chunk = file_stream.read(chunk_size)

            part_sha1 = hashlib.sha1(chunk).digest()
            digest = f"sha={base64.b64encode(part_sha1).decode()}"
            content_range = (
                f"bytes {offset}-{offset + len(chunk) - 1}/{file_size}"
            )

            uploaded_part = client.chunked_uploads.upload_file_part_by_url(
                upload_part_url,
                BytesIO(chunk),
                digest,
                content_range,
            )
            parts.append(uploaded_part.part)
            file_sha1.update(chunk)

    content_sha1 = file_sha1.digest()
    digest = f"sha={base64.b64encode(content_sha1).decode()}"
    files = client.chunked_uploads.create_file_upload_session_commit_by_url(
        commit_url, parts, digest
    )
    return files.entries[0]
```

Create the session before calling the helper. Run a preflight check first, then
use `create_file_upload_session` for a new file. When a file with the same name
already exists, `upload_file_manual` falls back to
`create_file_upload_session_for_existing_file` to upload a new version:

```python Python v10 theme={null}
import os

from box_sdk_gen import BoxAPIError, PreflightFileUploadCheckParent


def upload_file_manual(client, file_path, folder_id):
    file_size = os.path.getsize(file_path)
    file_name = os.path.basename(file_path)
    parent = PreflightFileUploadCheckParent(id=folder_id)

    try:
        client.uploads.preflight_file_upload_check(
            name=file_name,
            size=file_size,
            parent=parent,
        )
        upload_session = client.chunked_uploads.create_file_upload_session(
            folder_id, file_size, file_name
        )
    except BoxAPIError as err:
        if err.response_info.code != "item_name_in_use":
            raise

        file_id = err.response_info.context_info["conflicts"]["id"]
        upload_session = (
            client.chunked_uploads.create_file_upload_session_for_existing_file(
                file_id, file_size, file_name
            )
        )

    return upload_file_via_session(
        client, file_path, file_size, upload_session
    )
```

## Resources

* <Link href="https://github.com/box-community/box-python-gen-workshop/blob/main/workshops/files/files.md">Box Python SDK workshop: files and uploads</Link>
* <Link href="https://github.com/box/box-python-sdk/blob/main/docs/uploads.md">Box Python SDK: Uploads</Link>
* <Link href="https://github.com/box/box-python-sdk/blob/main/docs/chunked_uploads.md">Box Python SDK: Chunked uploads</Link>

<RelatedLinks title="RELATED GUIDES" />


# Create Web Link
Source: https://developer.box.com/guides/web-links/create



To create a web link in Box, you will need to provide our API with a folder
`id` and the `url` you want the web link to be linked to. The `url` must start
with `http://` or `https://`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/web_links" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "name": "Cloud Content Management",
         "url": "https://box.com",
         "parent": {
           "id": "0"
         }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.webLinks.createWebLink({
    url: 'https://www.box.com',
    parent: { id: parent.id } satisfies CreateWebLinkRequestBodyParentField,
    name: getUuid(),
    description: 'Weblink description',
  } satisfies CreateWebLinkRequestBody);
  ```

  ```python Python v10 theme={null}
  client.web_links.create_web_link(
      "https://www.box.com",
      CreateWebLinkParent(id=parent.id),
      name=get_uuid(),
      description="Weblink description",
  )
  ```

  ```cs .NET v10 theme={null}
  await client.WebLinks.CreateWebLinkAsync(requestBody: new CreateWebLinkRequestBody(url: "https://www.box.com", parent: new CreateWebLinkRequestBodyParentField(id: parent.Id)) { Name = Utils.GetUUID(), Description = "Weblink description" });
  ```

  ```swift Swift v10 theme={null}
  try await client.webLinks.createWebLink(requestBody: CreateWebLinkRequestBody(url: "https://www.box.com", parent: CreateWebLinkRequestBodyParentField(id: parent.id), name: Utils.getUUID(), description: "Weblink description"))
  ```

  ```java Java v10 theme={null}
  client.getWebLinks().createWebLink(new CreateWebLinkRequestBody.Builder(url, new CreateWebLinkRequestBodyParentField(parent.getId())).name(name).description(description).build())
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, id);
  URL url = new URL("https://www.example.com");
  folder.createWebLink("Link to Example", url, "This goes to an example page");
  ```

  ```python Python v4 theme={null}
  web_link = client.folder(folder_id='12345').create_web_link('https://example.com', 'Example Link', 'This is the description')
  print(f'Web Link url is {web_link.url} and its description is {web_link.description}')
  ```

  ```cs .NET v6 theme={null}
  var weblinkParams = new BoxWebLinkRequest()
  {
      Url = new Uri("http://www.example.com"),
      Parent = new BoxRequestEntity()
      {
          Id = "22222"
      }
  };
  BoxWebLink link = await client.WebLinksManager.CreateWebLinkAsync(weblinkParams);
  ```

  ```javascript Node v4 theme={null}
  client.weblinks.create(
  	'https://www.box.com',
  	'22222',
  	{
  		name: 'Box Website!',
  		description: 'Cloud Content Management'
  	})
  	.then(weblink => {
  		/* weblink -> {
  			type: 'web_link',
  			id: '11111',
  			sequence_id: '0',
  			etag: '0',
  			name: 'Box Website!',
  			url: 'https://www.box.com',
  			created_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			created_at: '2015-05-07T15:00:01-07:00',
  			modified_at: '2015-05-07T15:00:01-07:00',
  			parent: 
  			{ type: 'folder',
  				id: '22222',
  				sequence_id: '1',
  				etag: '1',
  				name: 'Bookmarks' },
  			description: 'Enterprise Cloud Content Management',
  			item_status: 'active',
  			trashed_at: null,
  			purged_at: null,
  			shared_link: null,
  			path_collection: 
  			{ total_count: 2,
  				entries: 
  				[ { type: 'folder',
  					id: '0',
  					sequence_id: null,
  					etag: null,
  					name: 'All Files' },
  					{ type: 'folder',
  					id: '22222',
  					sequence_id: '1',
  					etag: '1',
  					name: 'Bookmarks' } ] },
  			modified_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			owned_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' } }
  		*/
  	});
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete Web Link
Source: https://developer.box.com/guides/web-links/delete



<RelatedLinks title="REQUIRED GUIDES" />

To remove a web link in Box you will need to provide our API with the ID of
the web link.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/web_links/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.webLinks.deleteWebLinkById(webLinkId);
  ```

  ```python Python v10 theme={null}
  client.web_links.delete_web_link_by_id(web_link_id)
  ```

  ```cs .NET v10 theme={null}
  await client.WebLinks.DeleteWebLinkByIdAsync(webLinkId: webLinkId);
  ```

  ```swift Swift v10 theme={null}
  try await client.webLinks.deleteWebLinkById(webLinkId: webLinkId)
  ```

  ```java Java v10 theme={null}
  client.getWebLinks().deleteWebLinkById(weblink.getId())
  ```

  ```java Java v5 theme={null}
  BoxWebLink webLink = new BoxWebLink(api, id);
  webLink.delete();
  ```

  ```python Python v4 theme={null}
  client.web_link('12345').delete()
  print('The web link was deleted!')
  ```

  ```cs .NET v6 theme={null}
  await client.WebLinksManager.DeleteWebLinkAsync("11111");
  ```

  ```javascript Node v4 theme={null}
  client.weblinks.delete('11111')
  	.then(() => {
  		// deletion succeeded — no value returned
  	});
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Web Links
Source: https://developer.box.com/guides/web-links/index



Web links are objects that point to URLs. These objects are also known as
bookmarks within the Box web application.

Web Links are treated similarly to file objects, which means that they have the
same support for creating shared links, allow for copying, permanent deletion,
and restoration.


# Convert Markdown to Box Note
Source: https://developer.box.com/guides/box-notes/convert-markdown

Detailed guide for converting Markdown content to a Box Note using the POST /notes/convert endpoint.

The `POST /2.0/notes/convert` endpoint converts Markdown content to a
Box Note (`.boxnote`) and uploads it to a specified folder in one
atomic operation. The note is either fully created or an error is
returned.

## Prerequisites

Before you start, make sure you have:

* A valid access token with file upload permissions for the target
  folder.
* The `box-version: 2026.0` header included in your request.
* The folder ID of the target parent folder in Box.

For setup instructions, see the
<Link href="/guides/box-notes/get-started">getting started</Link>
guide.

## Request

```http theme={null}
POST https://api.box.com/2.0/notes/convert
```

### Headers

| Header | Required | Value |
| - | - | - |
| `Authorization` | Yes | `Bearer <ACCESS_TOKEN>` |
| `Content-Type` | Yes | `application/json` |
| `box-version` | Yes | `2026.0` |

### Request body

All fields are required.

| Field | Type | Constraints | Description |
| - | - | - | - |
| `content` | `string` | Max 1 MB | The Markdown content to convert into a Box Note. |
| `content_format` | `string` | Must be `"markdown"` | The format of the input content. |
| `parent` | `object` | Must contain `type` and `id` | The destination folder in Box. |
| `parent.type` | `string` | Must be `"folder"` | The type of the destination resource. |
| `parent.id` | `string` | Valid Box folder ID | The ID of the target parent folder. |
| `name` | `string` | — | The filename for the resulting `.boxnote` file. |

### Example request

```sh theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/notes/convert' \
     -H 'box-version: 2026.0' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{
       "content": "# Meeting Notes\n\nAction items:\n- Follow up with team\n- Review proposal\n\n## Decisions\n\nWe agreed to proceed with **Option A**.",
       "content_format": "markdown",
       "parent": {
         "type": "folder",
         "id": "123456789"
       },
       "name": "Q2 Meeting Notes"
     }'
```

## Response

### Success (`201 Created`)

A successful response contains the file type and the Box file ID of
the newly created `.boxnote` file.

```json theme={null}
{
  "type": "file",
  "id": "1234567890"
}
```

The response is intentionally minimal. To retrieve full file metadata
(owner, timestamps, size, and more), make a follow-up call to the
<Link href="/reference/get-files-id">Get file</Link> endpoint:

```sh theme={null}
curl -L 'https://api.box.com/2.0/files/1234567890' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### Errors

The API uses standard HTTP error codes. All errors follow the Box
`HttpError` model.

| HTTP status | Description | Common cause |
| - | - | - |
| `400 Bad Request` | Malformed request body | Missing required fields, invalid `content_format`, or malformed JSON. |
| `403 Forbidden` | Insufficient permissions | The authenticated user does not have upload permissions for the target folder. |
| `404 Not Found` | Folder not found | The `parent.id` does not correspond to an existing folder. |
| `409 Conflict` | Name collision | A file with the same name already exists in the target folder. |
| `422 Unprocessable Entity` | Validation failure | The request is syntactically valid but cannot be processed. For example, the user's storage quota is exceeded. |
| `5xx Server Error` | Internal error | An error occurred during conversion or upload. Retry after a brief delay. |

<Note>
  Conversion warnings, such as unsupported Markdown elements that are
  dropped or simplified during conversion, are logged server-side and
  are not returned in the API response.
</Note>

## Markdown support

The API converts standard Markdown syntax into Box Notes format.
Supported elements include:

* **Headings** (`#`, `##`, `###`, etc.)
* **Bold** (`**text**`) and *italic* (`*text*`)
* **Unordered lists** (`-` or `*`)
* **Ordered lists** (`1.`, `2.`, etc.)
* **Links** (`[text](url)`)
* **Code blocks** (fenced with triple backticks)
* **Inline code** (backticks)
* **Blockquotes** (`>`)
* **Horizontal rules** (`---`)

<Tip>
  If your Markdown contains elements that are not supported in Box
  Notes format, those elements may be simplified or omitted during
  conversion. The conversion still succeeds. Warnings are logged
  server-side only.
</Tip>

## Code examples

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST 'https://api.box.com/2.0/notes/convert' \
       -H 'box-version: 2026.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>' \
       -H 'Content-Type: application/json' \
       -d '{
         "content": "# Project Update\n\n## Summary\n\nSprint completed on schedule.\n\n## Tasks\n\n- [x] Design review\n- [x] Backend implementation\n- [ ] QA sign-off\n\n> Next sprint starts Monday.",
         "content_format": "markdown",
         "parent": {
           "type": "folder",
           "id": "987654321"
         },
         "name": "Sprint 14 Update"
       }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.box.com/2.0/notes/convert"

  headers = {
      "box-version": "2026.0",
      "Authorization": "Bearer <ACCESS_TOKEN>",
      "Content-Type": "application/json",
  }

  payload = {
      "content": (
          "# Project Update\n\n"
          "## Summary\n\n"
          "Sprint completed on schedule.\n\n"
          "## Tasks\n\n"
          "- [x] Design review\n"
          "- [x] Backend implementation\n"
          "- [ ] QA sign-off\n\n"
          "> Next sprint starts Monday."
      ),
      "content_format": "markdown",
      "parent": {"type": "folder", "id": "987654321"},
      "name": "Sprint 14 Update",
  }

  response = requests.post(url, json=payload, headers=headers)

  if response.status_code == 201:
      note = response.json()
      print(f"Note created with file ID: {note['id']}")
  else:
      print(f"Error {response.status_code}: {response.json()}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.box.com/2.0/notes/convert", {
    method: "POST",
    headers: {
      "box-version": "2026.0",
      Authorization: "Bearer <ACCESS_TOKEN>",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      content: [
        "# Project Update",
        "",
        "## Summary",
        "",
        "Sprint completed on schedule.",
        "",
        "## Tasks",
        "",
        "- [x] Design review",
        "- [x] Backend implementation",
        "- [ ] QA sign-off",
        "",
        "> Next sprint starts Monday.",
      ].join("\n"),
      content_format: "markdown",
      parent: { type: "folder", id: "987654321" },
      name: "Sprint 14 Update",
    }),
  });

  if (response.status === 201) {
    const note = await response.json();
    console.log(`Note created with file ID: ${note.id}`);
  } else {
    const error = await response.json();
    console.error(`Error ${response.status}:`, error);
  }
  ```
</CodeGroup>

## Handling errors

### Name conflicts (409)

If a file with the same name already exists in the target folder,
the API returns a `409 Conflict` error. To resolve this:

* Choose a different `name` for the note.
* Specify a different `parent.id` (target folder).
* Delete or rename the existing file before retrying.

### Storage quota exceeded (422)

If the user's storage quota has been reached, the API returns a
`422 Unprocessable Entity` error. Free up space in the Box account
or contact an admin to increase the storage allocation.

### Permission errors (403)

Verify that the authenticated user has **Editor** or **Co-Owner**
access to the target folder. **Viewer** and **Previewer** roles do
not have upload permissions.

## Best practices

<AccordionGroup>
  <Accordion title="Keep content within size limits">
    The maximum `content` size is 1 MB. For larger documents,
    consider splitting content across multiple notes or trimming
    unnecessary sections before conversion.
  </Accordion>

  <Accordion title="Use meaningful names">
    Choose descriptive note names that make the content easy to find
    in Box. Avoid generic names like "Note 1" or "Untitled".
  </Accordion>

  <Accordion title="Handle the conversion time">
    Conversion can take up to 30 seconds for large or complex
    Markdown content. Configure your HTTP client timeout accordingly
    and implement retry logic for transient `5xx` errors.
  </Accordion>

  <Accordion title="Retrieve metadata after creation">
    The create response only includes `type` and `id`. If you need
    additional file metadata (timestamps, size, owner), make a
    follow-up `GET /2.0/files/{file_id}` call.
  </Accordion>
</AccordionGroup>

<RelatedLinks title="RELATED GUIDES" />


# Box Notes API use cases
Source: https://developer.box.com/guides/box-notes/use-cases

Common scenarios and patterns for creating Box Notes programmatically from Markdown content.

The Box Notes API enables developers to programmatically create Box
Notes from Markdown content. This page outlines common use cases and
provides implementation patterns to help you get started.

## AI-generated note creation

AI assistants and LLM-powered applications often generate output in
Markdown format. The Box Notes API lets you save that output directly
as a collaborative Box Note without any intermediate format handling.

**Example workflow:**

<Steps>
  <Step title="Generate Markdown content">
    Your AI assistant generates a meeting summary, research brief, or
    document draft in Markdown.
  </Step>

  <Step title="Call the Notes API">
    Pass the generated Markdown to `POST /2.0/notes/convert` with
    the target folder and a descriptive file name.
  </Step>

  <Step title="Share the result">
    Use the returned file ID with the
    <Link href="/reference/post-collaborations">Collaborations API</Link>
    to share the note with the relevant team, or use the
    <Link href="/reference/put-files-id--add-shared-link">Shared Links API</Link>
    to generate a link.
  </Step>
</Steps>

```sh theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/notes/convert' \
     -H 'box-version: 2026.0' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -H 'Content-Type: application/json' \
     -d '{
       "content": "# Meeting Summary — May 2026\n\n## Key Decisions\n\n- Approved Q3 budget\n- Launch date set for August 15\n\n## Action Items\n\n- **Alice**: Finalize vendor contracts by June 1\n- **Bob**: Prepare onboarding materials\n- **Carol**: Schedule stakeholder review",
       "content_format": "markdown",
       "parent": {
         "type": "folder",
         "id": "555555555"
       },
       "name": "Meeting Summary — May 2026"
     }'
```

## Automated report generation

Workflow automation tools can convert system-generated reports into
Box Notes on a schedule. This is useful for dashboards, weekly
digests, and operational summaries that your team needs to review
collaboratively.

**Pattern:** Build a scheduled job (cron, AWS Lambda, Azure Function,
or any automation platform) that:

1. Gathers data from your internal systems.
2. Formats the data as Markdown (tables, lists, headings).
3. Calls the Box Notes API to create a note in a shared team folder.
4. Optionally notifies the team using Slack, email, or another channel
   with the Box file link.

## Third-party content import

External applications that store content as Markdown, such as wikis, knowledge
bases, project management tools, or CMS platforms, can import that
content into Box Notes for centralized collaboration and governance.

**Common sources:**

* **Git-based wikis**: Convert repository documentation or
  `README.md` files into Box Notes for non-technical stakeholders.
* **Notion or Confluence exports**: Export pages as Markdown and
  batch-import them into a Box folder structure.
* **CMS content**: Publish approved content as Box Notes for
  review and sign-off workflows.

<Tip>
  When importing multiple files, use a unique `name` for each note to
  avoid `409 Conflict` errors. Consider appending a timestamp or
  identifier to the file name.
</Tip>

## Developer tooling and CLI workflows

Developers can integrate the Box Notes API into scripts, CI/CD
pipelines, or command-line tools to automate note creation as part of
their development workflow.

**Examples:**

* **Post-deployment notes**: After a successful deployment,
  automatically create a Box Note with the release changelog.
* **Incident retrospectives**: A script gathers incident timeline
  data and creates a structured Box Note for the team to
  collaboratively edit.
* **Documentation sync**: Convert local Markdown documentation into
  Box Notes to maintain a synchronized copy in Box for broader team
  access.

## Combining with other Box APIs

The Box Notes API creates the note. You can combine it with other Box
APIs to build complete workflows:

| Goal | Box API | Details |
| - | - | - |
| Share the note with collaborators | <Link href="/reference/post-collaborations">Collaborations</Link> | Add editors, viewers, or co-owners to the new file. |
| Generate a shared link | <Link href="/reference/put-files-id--add-shared-link">Shared Links</Link> | Create a public or company-scoped link to the note. |
| Retrieve full file metadata | <Link href="/reference/get-files-id">Get file</Link> | Fetch timestamps, owner, size, and other metadata. |
| Apply metadata to the note | <Link href="/reference/post-files-id-metadata-id-id">Create metadata</Link> | Tag the note with custom metadata for search and classification. |
| Move or copy the note | <Link href="/reference/put-files-id">Update file</Link> | Move the note to a different folder after creation. |
| Delete the note | <Link href="/reference/delete-files-id">Delete file</Link> | Remove notes that are no longer needed. |

<RelatedLinks title="RELATED GUIDES" />


# Get Enterprise Events
Source: https://developer.box.com/guides/events/enterprise-events/for-enterprise



To get an enterprise's events, make
a call to the <Link href="/reference/get-events">`GET /events`</Link> API with the `stream_type` set to
`admin_logs` or `admin_logs_streaming`.

<Info>
  This API requires the user to be an enterprise admin or co-admin with the
  permission to **Run new reports and access existing reports**.
</Info>

## Stream Types

| Stream Type | |
| - | - |
| `admin_logs` | Enables querying historical events up to one year |
| `admin_logs_streaming` | Enables subscribing to live events in near real time |

## Live Monitoring

To monitor recent events that have been generated within Box across the
enterprise, set the `stream_type` to `admin_logs_streaming`. This is also known
as the Enterprise Event Stream API.

The emphasis for this feed is on low latency rather than chronological
accuracy, which means that Box may return events more than once and out of
chronological order. Events are returned via the API in near real time after
they are processed by Box. A small delay/buffer ensures that new events are not
written after your cursor position. Only two weeks of events are available via
this `stream_type`.

## Historical Querying

To query historical events across the enterprise up to one year old, set the
`stream_type` to `admin_logs`. This is also known as the Enterprise Event
History API.

The emphasis for this feed is on completeness over latency, which means that
Box will deliver admin events in chronological order and without duplicates,
but with higher latency than the user or `admin_logs_streaming` feed. Consuming
events in near real time may lead to missed events as events can arrive later
than your filtering window.

## Anonymous Users

In some cases, the event feed might list a user with an ID of `2`. This is Box's
internal identifier for anonymous users.

An anonymous user is a user that is not logged in. This can happen any time a
user interacts with content and they aren't asked to log in first. An example
would be when a user downloads a file through an open shared link.

## Limitations

The enterprise event feed does not support long polling.

Box does not store events indefinitely. Two weeks of enterprise events are
available when `stream_type` is set to `admin_logs_streaming`. One year of
enterprise events are available when `stream_type` is set to `admin_logs`.
Seven years of enterprise events are available via the Box Admin Console’s
[exported reports][reports].

The emphasis of the `admin_logs_streaming` feed is to return the complete
results quickly, which means that Box may return events more than once and out
of order. Duplicate events can be identified by their event IDs.

## Filter by Event Type

The enterprise event feed supports filtering by event type.

A full list of event types can be found below.

## Event Types

The following events can be triggered for an enterprise. This list is not
exhaustive, so it is possible events appear that are not listed.

| Event name | Description |
| - | - |
| `ACCESS_GRANTED` | A user has granted Box support access to their account |
| `ACCESS_REVOKED` | A user has revoked Box support access to their account |
| `ADD_DEVICE_ASSOCIATION` | Added device association |
| `ADD_LOGIN_ACTIVITY_DEVICE` | A user is logging in from a device we have not seen before |
| `ADMIN_LOGIN` | Admin console used to log in to a managed user's account |
| `ADVANCED_FOLDER_SETTINGS_UPDATE` | Advanced settings of a folder are updated |
| `AI_SECURITY_DETECTION` | Box AI detected a potential security risk, such as a prompt injection attempt. See <Link href="/guides/events/event-triggers/ai-security-detection-events">AI security detection events</Link> for more information. |
| `ANNOTATIONV2_CREATE` | An annotation is created |
| `ANNOTATIONV2_DELETE` | An annotation is deleted |
| `ANNOTATIONV2_EDIT` | An annotation is edited |
| `APPLICATION_CREATED` | A new application is created in the Box Developer Console |
| `APPLICATION_PUBLIC_KEY_ADDED` | An application public key is added. |
| `APPLICATION_PUBLIC_KEY_DELETED` | An application public key is deleted. |
| `BOX_AI_USER_REQUEST` | User asks Box AI a question or makes a request |
| `BOX_AI_USER_FAILED_REQUEST` | The question or request returns an error |
| `CHANGE_ADMIN_ROLE` | When an admin role changes for a user |
| `CHANGE_FOLDER_PERMISSION` | Edit the permissions on a folder |
| `COLLABORATION_ACCEPT` | Accepted invites |
| `COLLABORATION_EXPIRATION` | Set collaborator expiration |
| `COLLABORATION_INVITE` | Invited |
| `COLLABORATION_REMOVE` | Removed collaborators |
| `COLLABORATION_ROLE_CHANGE` | Changed user roles |
| `COLLECTION_CREATE` | A collection is created |
| `COLLECTION_DELETE` | A collection is deleted |
| `COLLECTION_UPDATE` | A collection is updated |
| `COLLECTION_ITEM_CREATE` | An item is added to a collection |
| `COLLECTION_ITEM_DELETE` | An item is removed from a collection |
| `COLLECTION_ITEM_UPDATE` | An item in a collection is updated |
| `COMMENT_CREATE` | A comment is created on a file |
| `COMMENT_DELETE` | A comment is deleted on a file |
| `COMMENT_EDIT` | A comment is edited on a file |
| `CONTENT_ACCESS` | A file is accessed by an authorized end user or programmatically by a Box application |
| `CONTENT_RECOVERY_REPORT_CREATE` | A Content Recovery report is created |
| `CONTENT_RECOVERY_REPORT_DELETE` | A Content Recovery report is deleted  |
| `CONTENT_RECOVERY_REPORT_INITIATE` | A Content Recovery report is initiated |
| `CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY` | A policy set in the Admin console is triggered |
| `CONTENT_WORKFLOW_AUTOMATION_ADD` | An automation is added |
| `CONTENT_WORKFLOW_AUTOMATION_DELETE` | An automation is deleted |
| `CONTENT_WORKFLOW_POLICY_ADD` | A content policy is added |
| `CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION` | There is a sharing policy violation. |
| `CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION` | A collaborator violated an admin-set upload policy |
| `COPY` | Copied |
| `DATA_RETENTION_CREATE_RETENTION` | Retention is created |
| `DATA_RETENTION_REMOVE_RETENTION` | Retention is removed |
| `DELETE` | Deleted |
| `DELETE_USER` | Deleted user |
| `DEVICE_TRUST_CHECK_FAILED` | Device Trust check failed |
| `DISABLE_MULTI_FACTOR_AUTH` | When multifactor authentication has been disabled |
| `DOWNLOAD` | Downloaded |
| `EDIT` | Edited |
| `EDIT_USER` | Edited user |
| `EDR_CROWDSTRIKE_DEVICE_DETECTED` | Device detected by the CrowdStrike Falcon platform |
| `EDR_CROWDSTRIKE_NO_BOX_TOOLS` | Box Tools package not detected on device with CrowdStrike Falcon platform support |
| `EDR_CROWDSTRIKE_BOX_TOOLS_OUTDATED` | Box Tools package outdated on device with CrowdStrike Falcon platform support |
| `EDR_CROWDSTRIKE_DRIVE_OUTDATED` | Box Drive application outdated on device with CrowdStrike Falcon platform support |
| `EDR_CROWDSTRIKE_ACCESS_ALLOWED_NO_CROWDSTRIKE_DEVICE` | Access allowed to a device not identified by the CrowdStrike Falcon platform |
| `EDR_CROWDSTRIKE_ACCESS_REVOKED` | Access revoked to a device identified by the CrowdStrike Falcon platform |
| `EMAIL_ALIAS_CONFIRM` | A user email alias is confirmed |
| `EMAIL_ALIAS_PRIMARY` | An email alias is set as the primary login for a user |
| `EMAIL_ALIAS_REMOVE` | A user email alias is removed |
| `EMAIL_UPLOAD_DISABLED` | Email uploads to a folder are disabled |
| `EMAIL_UPLOAD_ENABLED` | Email uploads to a folder are enabled |
| `ENABLE_MULTI_FACTOR_AUTH` | When multifactor authentication has been enabled |
| `ENTERPRISE_APP_AUTHORIZATION_UPDATE` | When a JWT application has been authorized or reauthorized |
| `EXTERNAL_COLLAB_SECURITY_SETTINGS` | Changes in external collaboration security settings |
| `FAILED_LOGIN` | Failed login |
| `FAVORITE` | An item is added to favorites |
| `FILE_MARKED_MALICIOUS` | Virus found on a file. Event is only received by enterprises that have opted in to be notified. |
| `FILE_REQUEST_CREATE` | A file request is created |
| `FILE_REQUEST_DELETE` | A file request is deleted |
| `FILE_REQUEST_UPDATE` | A file request is updated |
| `FILE_VERSION_RESTORE` | A previous version of a file is restored |
| `FILE_WATERMARKED_DOWNLOAD` | A watermarked file is downloaded |
| `GROUP_ADD_ITEM` | An item is added to a group |
| `GROUP_ADD_USER` | Added user to group |
| `GROUP_ADMIN_CREATED` | Group admin is created |
| `GROUP_ADMIN_DELETED` | Group admin is deleted |
| `GROUP_ADMIN_PERMISSIONS_UPDATED` | Group admin permissions are updated |
| `GROUP_CREATION` | Created new group |
| `GROUP_DELETION` | Deleted group |
| `GROUP_EDITED` | Edited group |
| `GROUP_REMOVE_ITEM` | Folders were removed from a group in the Admin console |
| `GROUP_REMOVE_USER` | Removed user from group |
| `ILLEGAL_ITEM_OWNERSHIP_TRANSFER_BY_USER` | A user attempted an ownership transfer that violated enterprise item transfer policy (blocked before completion) |
| `ITEM_ASSOCIATION_CREATED` | An app item association is created |
| `ITEM_ASSOCIATION_DELETED` | An app item association is deleted |
| `ITEM_ASSOCIATION_UPDATED` | An app item association is updated |
| `ITEM_EMAIL_SEND` | An email is sent to a collaborator on an item |
| `ITEM_MODIFY` | Item is modified |
| `ITEM_OPEN` | Item is opened |
| `ITEM_SHARED_UPDATE` | Share links settings updated |
| `ITEM_SYNC` | Synced folder |
| `ITEM_UNSYNC` | Unmarked folder for synced |
| `LEGAL_HOLD_ASSIGNMENT_CREATE` | A legal hold assignment is created |
| `LEGAL_HOLD_ASSIGNMENT_DELETE` | A legal hold assignment is deleted |
| `LEGAL_HOLD_POLICY_CREATE` | A legal hold policy is created |
| `LEGAL_HOLD_POLICY_DELETE` | A legal hold policy is deleted |
| `LEGAL_HOLD_POLICY_UPDATE` | A legal hold policy is updated |
| `LOCK` | Locked |
| `LOGIN` | Login |
| `METADATA_CASCADE_POLICY_APPLY` | A metadata cascade policy is applied to a folder |
| `METADATA_CASCADE_POLICY_CREATE` | A metadata cascade policy is created |
| `METADATA_INSTANCE_COPY` | A metadata instance is copied to another item |
| `METADATA_INSTANCE_CREATE` | Creation of metadata instance |
| `METADATA_INSTANCE_DELETE` | Deletion of metadata instance |
| `METADATA_INSTANCE_UPDATE` | Update of metadata instance |
| `METADATA_TEMPLATE_CREATE` | Creation of metadata template |
| `METADATA_TEMPLATE_UPDATE` | Update of metadata template |
| `METADATA_TEMPLATE_DELETE` | Deletion of metadata template |
| `MOVE` | Moved |
| `NEW_USER` | Created user |
| `OAUTH2_ACCESS_TOKEN_REVOKE` | An OAuth 2.0 access token has been revoked |
| `OAUTH2_REFRESH_TOKEN_REVOKE` | An OAuth 2.0 refresh token has been revoked |
| `PREVIEW` | Previewed |
| `REMOVE_DEVICE_ASSOCIATION` | Removed device association |
| `REMOVE_LOGIN_ACTIVITY_DEVICE` | We invalidated a user session associated with an app |
| `RENAME` | A file or folder name or description is changed |
| `RETENTION_POLICY_ASSIGNMENT_ADD` | A retention policy assignment is added |
| `SHARE` | Enabled shared links |
| `SHARE_EXPIRATION` | Set shared link expiration |
| `SHARED_LINK_SEND` | An email is sent with a shared link and an optional message |
| `SHARED_LINK_REDIRECT_OUT_OF_SHARED_CONTEXT` | Shared link causes a redirect |
| `SHIELD_ACCESS_POLICY_CREATED` | A Shield access policy was created |
| `SHIELD_ACCESS_POLICY_UPDATED` | A Shield access policy was updated |
| `SHIELD_ACCESS_POLICY_DELETED` | A Shield access policy was deleted |
| `SHIELD_ALERT` | Shield detected an anomalous download, session, location, or malicious content based on enterprise Shield rules. See <Link href="/guides/events/event-triggers/shield-alert-events">shield alert events</Link> for more information. |
| `SHIELD_DOWNLOAD_BLOCKED` | End user blocked from downloading a file based on a shield access policy |
| `SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED` | Access to an external collaboration is blocked |
| `SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION` | Access to an external collaboration is blocked due to missing a justification |
| `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED` | An invite to externally collaborate is blocked |
| `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION` | An invite to externally collaborate is blocked due to missing a justification |
| `SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED` | An invite to externally collaborate is justified |
| `SHIELD_JUSTIFICATION_APPROVAL` | A Shield justification is approved |
| `SHIELD_PREVIEW_BLOCKED` | An integration is blocked from previewing a file based on a shield access policy |
| `SHIELD_SHARED_LINK_ACCESS_BLOCKED` | Access to a shared link is blocked |
| `SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE` | A shared link is created and access to the content is restricted |
| `SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE` | A shared link is updated and access to the content is restricted |
| `SHIELD_INFORMATION_BARRIER_ENABLED` | A Shield information barrier is enabled |
| `SHIELD_INFORMATION_BARRIER_DISABLED` | A Shield information barrier is deactivated |
| `SHIELD_INFORMATION_BARRIER_PENDING` | A Shield information barrier is not yet active |
| `SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED` | Adding user blocked due to information barrier restrictions |
| `SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED` | Creating collaborations for users blocked due to information barrier restrictions |
| `SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED` | Access to shared items blocked for users due to information barrier restrictions |
| `SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED` | Moving items blocked due to information barrier restrictions |
| `SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED` | Copying items blocked due to information barrier restrictions |
| `SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED` | Transferring items blocked due to information barrier restrictions |
| `SIGN_DOCUMENT_ASSIGNED` | A sign request was sent to a signer |
| `SIGN_DOCUMENT_CANCELLED` | A sign request was cancelled via API or UI |
| `SIGN_DOCUMENT_COMPLETED` | A sign request was signed by all signers |
| `SIGN_DOCUMENT_CONVERTED` | A sign request was converted to a `.pdf` for signing |
| `SIGN_DOCUMENT_CREATED` | A sign request was created via API or UI. The document is not yet sent to signers |
| `SIGN_DOCUMENT_DECLINED` | A sign request was declined by a signer |
| `SIGN_DOCUMENT_EXPIRED` | A sign request expired with incomplete signatures |
| `SIGN_DOCUMENT_SIGNED` | A sign request was signed by a signer |
| `SIGN_DOCUMENT_VIEWED_BY_SIGNER` | A signer clicked on **Review Document** in the signer email or visited the signing URL |
| `SIGNER_DOWNLOADED` | A signer downloaded the signing document |
| `SIGNER_FORWARDED` | A signer forwarded the signing document |
| `STORAGE_EXPIRATION` | Set file auto-delete |
| `TASK_ASSIGNMENT_UPDATE` | Update of a task assignment |
| `TASK_ASSIGNMENT_CREATE` | A task assignment is created |
| `TASK_ASSIGNMENT_DELETE` | A task assignment is deleted |
| `TASK_CREATE` | A task is created. |
| `TASK_UPDATE` | A task's comment is edited |
| `TERMS_OF_SERVICE_ACCEPT` | Accepted terms |
| `TERMS_OF_SERVICE_REJECT` | Rejected terms |
| `UNDELETE` | Restored |
| `UNFAVORITE` | An item is removed from favorites |
| `UNLOCK` | Unlocked |
| `UNSHARE` | Shared link removed |
| `UPDATE_COLLABORATION_EXPIRATION` | Extend collaborator expiration |
| `UPDATE_SHARE_EXPIRATION` | Extend shared link expiration |
| `UPLOAD` | Uploaded |
| `USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE` | An OAuth 2.0 access token has been created |
| `WATERMARK_LABEL_CREATE` | A watermark is added to a file |
| `WATERMARK_LABEL_DELETE` | A watermark is removed from a file |
| `WORKFLOW_AUTOMATION_CREATE` | A Box Relay workflow automation is created |
| `WORKFLOW_AUTOMATION_DELETE` | A Box Relay workflow automation is deleted |
| `WORKFLOW_AUTOMATION_UPDATE` | A Box Relay workflow automation is updated |

[reports]: https://docs.box.com/en/box-admin-tools/reporting-and-insights/running-reports

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Enterprise Events
Source: https://developer.box.com/guides/events/enterprise-events/index



Enterprise events provide an event feed for all users and content in an
enterprise Box instance. Depending upon the `stream_type` your application can
either subscribe to live events or query historical events. Access to these
stream types is limited to users with admin permissions
to **Run new reports and access existing reports**.


# Migrating From History To Stream
Source: https://developer.box.com/guides/events/enterprise-events/migrate-to-stream



Box recommends that applications subscribing to live events through
`admin_logs` migrate to `admin_logs_streaming`. `admin_logs_streaming` provides
lower and more consistent latency, as well as ensures that late arriving
events are not missed. Events can be deduplicated between `admin_logs` and
`admin_logs_streaming` by their event IDs.

## Enterprise `stream_type` comparison

### Benefits of `admin_logs_streaming`

* Ensures late arriving events are not missed by your subscribing application
* Provides 80% lower latency (during normal operations)
* Has much more consistent latency (during normal operations)
* Recovers much more gracefully from a fault, because your service no longer has to manage backfilling late events

### Differences between `admin_logs` and `admin_logs_streaming`

* Provides two weeks of event history (i.e. retention)
* Does not support the `created_after` and `created_before` filter parameters
* May contain duplicates (provides an 'at least once' guarantee)
* No longer returns events in chronological order (events are returned in roughly the order they are processed)

### Similarities between `admin_logs` and `admin_logs_streaming`

* Shares the same <Link href="/reference/resources/events">`GET /events`</Link> API endpoint
* Returns the same events payload (events can be deduplicated across the two stream types by event ID)
* Enables filtering by `event_type`
* Allows paginating through events via a `stream_position`

## How to migrate from `admin_logs` to `admin_logs_streaming`

### 1. Existing requests will look something like the below

```sh theme={null}
curl https://api.box.com/2.0/events?stream_type=admin_logs&stream_position=1632893855 \
    -H "authorization: Bearer <ACCESS_TOKEN>"
```

### 2. Begin overlapping existing requests with `admin_logs_streaming`

* Start two weeks ago and backfill:

  ```sh theme={null}
  curl https://api.box.com/2.0/events?stream_type=admin_logs_streaming&stream_position=0 \
      -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

or

* Start now and run in parallel:

  ```sh theme={null}
  curl https://api.box.com/2.0/events?stream_type=admin_logs_streaming&stream_position=now \
      -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

### 3. Paginate through results until now and deduplicate with `admin_logs` events

```sh theme={null}
curl https://api.box.com/2.0/events?stream_type=admin_logs_streaming&stream_position=1632893855 \
    -H "authorization: Bearer <ACCESS_TOKEN>"
```

### 4. Continue to overlap until confident

### 5. Turn off old `admin_logs` requests

<Frame>
  <img alt="Stream Migration Flow" />
</Frame>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# AI Security Detection Events
Source: https://developer.box.com/guides/events/event-triggers/ai-security-detection-events



The `AI_SECURITY_DETECTION` event is generated when Box AI performs a security scan on input or retrieved content and detects a potential security risk, such as a prompt injection attempt. These events allow you to monitor and audit AI security detections across agent sessions and AI-powered workflows.

<Warning>
  AI security detection events are generated only for Box Agents. Legacy agents are not scanned. Box Shield Pro agents, including the <Link href="https://support.box.com/hc/en-us/articles/44263764561171-AI-Classification">AI Classification Agent</Link> and the <Link href="https://support.box.com/hc/en-us/articles/48430758923027-AI-Threat-Analysis">AI Threat Analysis Agent</Link>, are also not scanned.
</Warning>

All AI security detection events are produced within the <Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream. These events follow the standard <Link href="/reference/resources/event">event</Link> object schema, with `event_type` set to `AI_SECURITY_DETECTION` and detection-specific details nested inside `additional_details`.

```json theme={null}
{
  "created_by": {
    "type": "user",
    "id": "1234"
  },
  "created_at": "2026-01-01T00:00:00-08:00",
  "event_type": "AI_SECURITY_DETECTION",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "ai_security_detection_event": {
      "agent_id": "box-ai-agent",
      "items": null,
      "detector_type": "PROMPT_INJECTION",
      "scan_source_type": "PROMPT",
      "confidence_level": "MEDIUM",
      "action": "ALLOW"
    }
  }
}
```

# `additional_details` fields

| Field | Description |
| - | - |
| `agent_id` | The ID of the Box AI agent that processed the request. |
| `items` | Always returns `null`. |
| `detector_type` | Indicates what triggered the detection. See [Detector types](#detector-types). |
| `scan_source_type` | Indicates that the user's input to the agent was scanned. |
| `confidence_level` | Confidence level of the detection: `LOW`, `MEDIUM`, `HIGH`. |
| `action` | The action taken after the detection. See [Actions](#actions). |

## Detector types

The `detector_type` field indicates what triggered the detection. Additional detector types may be added in the future.

| Detector type | Description |
| - | - |
| `PROMPT_INJECTION` | Box AI detected an attempt to manipulate or override agent instructions through malicious or adversarial input during an agent interaction or AI-powered workflow. |

# Actions

The `action` field indicates what Box AI did in response to the detection. All detections, including those with a `LOW` confidence level, are recorded in the enterprise event stream.

| Action | Description |
| - | - |
| `LOG_ONLY` | The detection was recorded. The request was permitted to proceed. |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Event Source
Source: https://developer.box.com/guides/events/event-triggers/event-source



If a user or item triggers an event, the response of the
<Link href="/reference/get-events">`GET /events`</Link> endpoint contains an event source object.

## User Source Object

If a user triggers an event, the source object will be the standard
representation of the <Link href="/reference/resources/user">user resource</Link>.

```json theme={null}
{
  "source": {
    "id": 11446498,
    "type": "user",
    "address": "900 Jefferson Ave, Redwood City, CA 94063",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "created_at": "2012-12-12T10:53:43-08:00",
    "job_title": "CEO",
    "language": "en",
    "login": "ceo@example.com",
    "max_upload_size": 2147483648,
    "modified_at": "2012-12-12T10:53:43-08:00",
    "name": "Aaron Levie",
    "notification_email": {
      "email": "notifications@example.com",
      "is_confirmed": true
    },
    "phone": 6509241374,
    "space_amount": 11345156112,
    "space_used": 1237009912,
    "status": "active",
    "timezone": "Africa/Bujumbura"
  }
}
```

## Item Source Object

If an item triggers an event, the source object will be the
<Link href="/reference/resources/event-source">event source resource</Link>.

<Note>
  The below example contains a `classification` object. This does not appear if
  the item does not have a classification set. Also, it does not appear for
  every event type.
</Note>

```json theme={null}
{
  "source": {
    "item_type": "file",
    "item_id": "8903212345",
    "item_name": "example.docx",
    "parent": {
      "type": "folder",
      "name": "All Files",
      "id": "0"
    },
    "owned_by": {
      "type": "user",
      "id": "11446498",
      "name": "Aaron Levie",
      "login": "notifications@example.com"
    },
    "classification": {
      "name": "Top Secret"
    }
  }
}
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Event Triggers
Source: https://developer.box.com/guides/events/event-triggers/index



Events appear in the event stream based upon actions committed by users,
items, or other resources. The response of the <Link href="/reference/get-events">`GET /events`</Link>
endpoint changes based upon the event that triggered the event.

## User Source Object

If a user triggers an event, the source object will be the standard
representation of the <Link href="/reference/resources/user">user resource</Link>.

```json theme={null}
{
  "source": {
    "id": 11446498,
    "type": "user",
    "address": "900 Jefferson Ave, Redwood City, CA 94063",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "created_at": "2012-12-12T10:53:43-08:00",
    "job_title": "CEO",
    "language": "en",
    "login": "ceo@example.com",
    "max_upload_size": 2147483648,
    "modified_at": "2012-12-12T10:53:43-08:00",
    "name": "Aaron Levie",
    "notification_email": {
      "email": "notifications@example.com",
      "is_confirmed": true
    },
    "phone": 6509241374,
    "space_amount": 11345156112,
    "space_used": 1237009912,
    "status": "active",
    "timezone": "Africa/Bujumbura"
  }
}
```

## Item Source Object

If an item triggers an event, the source object will be the
<Link href="/reference/resources/event-source">event source resource</Link>.

<Note>
  The below example contains a `classification` object. This does not appear if
  the item does not have a classification set. Also, it does not appear for
  every event type.
</Note>

```json theme={null}
{
  "source": {
    "item_type": "file",
    "item_id": "8903212345",
    "item_name": "example.docx",
    "parent": {
      "type": "folder",
      "name": "All Files",
      "id": "0"
    },
    "owned_by": {
      "type": "user",
      "id": "11446498",
      "name": "Aaron Levie",
      "login": "notifications@example.com"
    },
    "classification": {
      "name": "Top Secret"
    }
  }
}
```


# Shield Alert Events
Source: https://developer.box.com/guides/events/event-triggers/shield-alert-events



[Box Shield][box-shield] must be purchased and enabled on a
Box enterprise to take advantage of the advanced security
offerings outlined below.

## Threat detection alerts

Shield [threat detection][threatdetect] delivers context-rich alerts on
potential threats, such as compromised accounts and data theft, based on
anomalous user behavior.

The possible alerts produced by Shield are for:

1. Suspicious locations
2. Suspicious sessions
3. Anomalous downloads
4. Malicious content
5. Ransomware activity (part of Shield Pro)

All Shield threat detection alert events are produced within the
<Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream. These events follow the
standard event object schema and the `event_type` value is set to
`SHIELD_ALERT`.

```json theme={null}
{
  "source": null,
  "created_by": {
    "type": "user",
    "id": "2",
    "name": "Unknown User",
    "login": ""
  },
  "action_by": null,
  "created_at": "2019-12-20T11:38:56-08:00",
  "event_id": "97f1b31f-f143-4777-81f8-1b557b39ca33",
  "event_type": "SHIELD_ALERT",
  "ip_address": "10.1.2.3",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "..."
  }
}
```

The `additional_details` object provides information
about the specific type of shield alert that triggered the event.

### Suspicious locations alert

A suspicious locations alert is produced when Shield detects a user
accessing content from an unusual, excluded geographic location, or 'host' IP
address. It can be identified by the `Suspicious Locations` value
within `additional_details.shield_alert.rule_category`.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Suspicious Locations",
    "rule_id": 123,
    "rule_name": "Suspicious Location",
    "rule_response_action": {
      "restrict_user": true
        },
    "risk_score": 60,
    "alert_summary": {
      "alert_activities": [
        {
          "occurred_at": "2019-12-20T11:37:05-08:00",
          "event_type": "Download",
          "item_name": "xyz.txt",
          "item_type": "file",
          "item_id": "127",
          "item_path": "ABC/DEF",
          "ip_info": {
            "ip": "1.2.3.4",
            "latitude": "37.5555",
            "longitude": "-120.6789",
            "registrant": "Microsoft Corporation",
            "country_code": "US",
            "city_name": "San Jose",
            "region_name": "California"
          },
          "service_name": "Box Excel Online Previewer"
        }
      ]
    },
    "alert_id": 2398,
    "priority": "medium",
    "user": {
      "id": 2320,
      "name": "Some name",
      "email": "some@email.com"
    },
    "link": "https://app.box.com/master/shield/alerts/2398",
    "created_at": "2019-12-20T11:37:15-08:00"
  }
}
```

### Suspicious sessions alert

A suspicious sessions alert is produced when Shield detects a user accessing
content in a session characterized by unusual user-agent strings, unusual IDs,
uncommon types of applications, new IP addresses, and an improbably rapid change
in the person's log-in location. It can be identified by the `Suspicious
Sessions` value within `additional_details.shield_alert.rule_category`.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Suspicious Sessions",
    "rule_id": 123,
    "rule_name": "Suspicious Session",
    "rule_response_action": null,
    "risk_score": 77,
    "alert_summary": {
      "description": "First time in prior month user connected from ip 2.3.4.5 First time user agent Some User Agent (Some UA 4.5.6) appeared for user within prior month Apparent distance 9580.0 km between events 59 seconds apart is faster than possible",
      "sessions": [
        {
          "session_type": "suspicious",
          "activities": [
            {
              "occurred_at": "2019-12-19T11:37:00-08:00",
              "event_type": "Set shared link expiration",
              "item_name": "xyz.txt",
              "item_type": "file",
              "item_id": "123456",
              "item_path": "ABC/DEF",
              "ip_info": {
                "ip": "2.3.4.5",
                "latitude": "37.5555",
                "longitude": "-120.6789",
                "registrant": "Microsoft Corporation",
                "country_code": "US",
                "city_name": "San Jose",
                "region_name": "California"
              },
              "service_name": "ServiceName"
            }
          ]
        },
        {
          "session_type": "typical",
          "activities": [
            {
              "occurred_at": "2019-12-19T11:37:59-08:00",
              "event_type": "Item Modified",
              "item_name": "abc.boxnote",
              "item_type": "file",
              "item_id": "123123",
              "item_path": "folder/sub folder",
              "ip_info": {
                "ip": "4.5.6.7",
                "latitude": "37.5555",
                "longitude": "-20.6789",
                "country_code": "US",
                "city_name": "Some City",
                "region_name": "XYZ"
              },
              "service_name": "Box Notes"
            }
          ]
        }
      ]
    },
    "alert_id": 500,
    "priority": "medium",
    "user": {
      "id": 50500,
      "name": "A b c",
      "email": "a@b.c"
    },
    "link": "https://cloud.app.box.com/master/shield/alerts/500",
    "created_at": "2019-12-20T11:38:16-08:00"
  }
}
```

### Anomalous download alert

An anomalous download alert is produced when Shield detects an account holder
who may be stealing sensitive content. It can be identified by the
`Anomalous Download` value within
`additional_details.shield_alert.rule_category`.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Anomalous Download",
    "rule_id": 123,
    "rule_name": "Anomalous Download Rule",
    "rule_response_action": null,
    "risk_score": 77,
    "alert_summary": {
      "description": "Significant increase in download content week over week, 9200% (25.04 MB) more than last week 12 additional files downloaded week over week)",
      "download_delta_size": "25 Mb",
      "download_delta_percent": 9200,
      "historical_period": {
        "date_range": {
          "start_date": "2019-12-01T01:01:00-08:00",
          "end_date": "2019-12-08T01:01:00-08:00"
        },
        "download_size": "0 Mb",
        "downloaded_files_count": 1
      },
      "anomaly_period": {
        "date_range": {
          "start_date": "2019-12-08T01:01:00-08:00",
          "end_date": "2019-12-15T01:01:00-08:00"
        },
        "download_size": "25 Mb",
        "downloaded_files_count": 13
      },
      "download_ips": [
        {
          "ip": "1.2.3.4"
        }
      ]
    },
    "alert_id": 444,
    "priority": "medium",
    "user": {
      "id": 567,
      "name": "Some user",
      "email": "some@user.com"
    },
    "link": "https://cloud.app.box.com/master/shield/alerts/444",
    "created_at": "2019-12-20T11:38:16-08:00"
  }
}
```

### Malicious content alert

A malicious content alert is produced when Shield detects potential malware
in content uploading to an account. It can be identified by the
`Malicious Content` value within
`additional_details.shield_alert.rule_category`.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Malicious Content",
    "rule_id": 123,
    "rule_name": "Viruses and stuff",
    "rule_response_action": null,
    "risk_score": 100,
    "alert_summary": {
      "upload_activity": {
        "occurred_at": "2019-12-20T11:37:05-08:00",
        "event_type": "Upload",
        "item_name": "virus.exe",
        "item_type": "file",
        "item_id": "127",
        "item_path": "ABC/DEF",
        "sha1_hash": "",
        "ip_info": {
          "ip": "1.2.3.4",
          "latitude": "37.5555",
          "longitude": "-120.6789",
          "registrant": "Microsoft Corporation",
          "country_code": "US",
          "city_name": "San Jose",
          "region_name": "California"
        },
        "service_name": "Service name"
      }
    },
    "malware_info": {
       "file_id": 127,
       "file_name": "malware.exe",
       "file_version": 4239023,
       "file_created": "2019-12-20T11:37:05-08:00",
       "file_created_by": {
         "id": 1010,
         "name": "Bob",
         "email": "bob@enterprise.com"
      },
      "file_hash": "d869db7fe62fb07c25a0403ecaea55031744b5fb",
      "file_hash_type": "SHA-1",
      "file_size_bytes": 51345,
      "file_version_uploaded": "2019-12-20T11:37:05-08:00",
      "file_version_uploaded_by": {
        "id": 1011,
        "name": "Jane",
        "email": "jane@enterprise.com"
      },
      "status": "Malicious",
      "categories": [
        "Adware",
        "SpyWare"
      ],
      "tags": [
        "FILE_MALICIOUS_EXECUTION",
        "FILE_OTHER_TAG"
      ],
      "description": "This is a really bad file",
      "detail_link": "https://some.link/xyz",
      "malware_name": "BadMalware",
      "first_seen": "2019-12-19T11:37:05-08:00",
      "last_seen": "2019-12-20T11:37:05-08:00",
      "family": "MalwareBot4000"
    },
    "alert_id": 2398,
    "priority": "medium",
    "user": {
      "id": 2320,
      "name": "Some Name",
      "email": "some@email.com"
    },
    "link": "https://app.box.com/master/shield/alerts/2398",
    "created_at": "2019-12-20T11:37:15-08:00"
  }
}
```

### Ransomware activity alert

A ransomware activity alert is produced when Box Shield identifies suspicious file extensions that may be indicative of a ransomware attack. It can be identified by the Ransomware Activity value within `additional_details.shield_alert.rule_category`.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_alert": {
    "rule_category": "Ransomware Activity",
    "rule_id": "1234",
    "rule_name": "Ransomware Detection",
    "rule_response_action": {
      "terminate_sessions": true
    },
    "risk_score": 100,
    "alert_summary": {
      "total_files_affected": 42,
      "ip_details": [
        {
          "ip": "1.2.3.4",
          "registrant": "Microsoft Corporation",
          "latitude": "37.5555",
          "longitude": "-120.6789",
          "city_name": "San Jose",
          "region_name": "California",
          "country_code": "US"
        }
      ],
      "suspicious_file_extensions": [
        "lockbit"
      ],
      "anomaly_period": {
        "date_range": {
          "start_date": "2009-02-13T23:31:30Z",
          "end_date": "2009-02-13T23:31:30Z"
        }
      }
    },
    "alert_id": 1234,
    "priority": "medium",
    "user": {
      "id": 8167630149,
      "name": "Some user",
      "email": "Some@user.com"
    },
    "link": "https://app.box.com/master/shield/alerts/1234",
    "created_at": "2025-08-19T10:44:26-07:00"
  }
}
```

For the Ransomware Activity alert, the `rule_response_action` object reflects
the automated response action taken by Box Shield when the alert was created.
The `terminate_sessions` field indicates whether Box Shield initiated a request to terminate all active sessions of a managed user:

* `true` — the **Terminate Target User Sessions** rule setting was enabled, so Box
  Shield initiated a request to terminate all active sessions of a managed user when the
  alert was created.
* `false` — the **Terminate Target User Sessions** rule setting was disabled, so no
  automated session termination was taken.

The value of `terminate_sessions` depends on the **Terminate Target User Sessions**
setting in the rule configuration, which is off by default.

[box-shield]: https://www.box.com/shield

[threatdetect]: https://support.box.com/hc/en-us/articles/360044196113-Using-Threat-Detection

[smartaccess]: https://docs.box.com/en/box-shield/shield-smart-access-policies/about-smart-access

[monitoringmode]: https://docs.box.com/en/box-shield/shield-smart-access-policies/about-smart-access

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Shield Information Barrier Events
Source: https://developer.box.com/guides/events/event-triggers/shield-information-barrier-events



Information barrier prevents exchanges or
communication that could lead to conflicts of interest
or potential legal issues.
For example, admins can use information barrier
to separate teams based on projects to prevent collaboration on
content restricted to specific groups.

## Events triggered when information barrier is configured

Configuring information barrier produces
events in the <Link href="/guides/events/enterprise-events/for-enterprise/">enterprise event</Link> stream. For example,
activating or deactivating the barrier triggers an event.

These events follow
the standard event object schema with the `event_type` value
set to one of the following:

* `SHIELD_INFORMATION_BARRIER_ENABLED`
* `SHIELD_INFORMATION_BARRIER_PENDING`
* `SHIELD_INFORMATION_BARRIER_DISABLED`

### Shield information barrier enabled

A `SHIELD_INFORMATION_BARRIER_ENABLED` event is triggered when
the information barrier is enabled for a file or folder.
For example:

```json theme={null}
{
  "chunk_size": 1,
  "next_stream_position": "1152923169537420243",
  "entries": [
    {
      "source": {
        "barrier_id": 123456,
        "barrier_status": "ENABLED",
        "barrier_segments": [
          {
            "name": "8",
            "member_count": 1
          },
          {
            "name": "9",
            "member_count": 1
          }
      ]
      },
      "created_by": {
        "type": "user",
        "id": "12345667",
        "name": "Unknown User",
        "login": "user@email.com"
      },
      "action_by": null,
      "created_at": "2022-10-04T17:42:53-07:00",
      "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
      "event_type": "SHIELD_INFORMATION_BARRIER_ENABLED",
      "ip_address": "Unknown IP",
      "type": "event",
      "session_id": null,
      "additional_details": null
    }
  ]
}
```

### Shield information barrier pending

A `SHIELD_INFORMATION_BARRIER_PENDING` event is triggered
when the information barrier is not yet enabled
for a particular file or folder. The activation process
was triggered, but the information barrier is not yet
in place.
For example:

```json theme={null}
{
  "chunk_size": 1,
  "next_stream_position": "1152923169531664551",
  "entries": [
    {
      "source": {
        "barrier_id": 123456,
        "barrier_status": "PENDING",
        "barrier_segments": [
          {
            "name": "8",
            "member_count": 1
          },
          {
            "name": "9",
            "member_count": 1
          }
        ]
      },
      "created_by": {
        "type": "user",
        "id": "12345667",
        "name": "Unknown User",
        "login": "user@email.com"
      },
      "action_by": null,
      "created_at": "2022-10-04T16:06:57-07:00",
      "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
      "event_type": "SHIELD_INFORMATION_BARRIER_PENDING",
      "ip_address": "Unknown IP",
      "type": "event",
      "session_id": null,
      "additional_details": null
    }
  ]
}
```

### Shield information barrier deactivated

A `SHIELD_INFORMATION_BARRIER_DISABLED` event is triggered when
the information barrier is deactivated
for a particular file or folder.
For example:

```json theme={null}
{
  "chunk_size": 1,
  "next_stream_position": "1152923169767928414",
  "entries": [
    {
      "source": {
        "barrier_id": 1234567,
        "barrier_status": "DISABLED",
        "barrier_segments": [
          {
            "name": "8",
            "member_count": 1
          },
          {
            "name": "9",
            "member_count": 1
          }
        ]
      },
      "created_by": {
        "type": "user",
        "id": "123435567",
        "name": "Unknown User",
        "login": "user@email.com"
      },
      "action_by": null,
      "created_at": "2022-10-07T09:44:41-07:00",
      "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
      "event_type": "SHIELD_INFORMATION_BARRIER_DISABLED",
      "ip_address": "Unknown IP",
      "type": "event",
      "session_id": null,
      "additional_details": null
    }
  ]
}
```

## Events triggered by restricted actions

When the information barrier is set up,
each user attempt to perform restricted actions
or access restricted data
also results in events. These events follow
the standard event object schema with the `event_type` value
set to one of the following:

* `SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED`
* `SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED`
* `SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED`
* `SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED`
* `SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED`
* `SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED`

### Adding user blocked

A `SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED` event is
triggered when the information barrier prohibits
adding a user to a specific group.

The `additional_details` payload provides details of the
restricted groups.

```json theme={null}
{
  "source": {
    "type": "user",
    "id": "123456677",
    "name": "Unknown User",
    "login": "user@email.com"
  },
  "created_by": {
    "type": "user",
    "id": "12345666",
    "name": "Unknown User",
    "login": "user@email.com"
  },
  "action_by": null,
  "created_at": "2022-10-07T09:26:50-07:00",
  "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
  "event_type": "SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED",
  "ip_address": "10.1.2.3",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "group_id": "12345678",
    "group_name": "Support"
  }
}
```

### Collaboration blocked

A `SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED` event is triggered
when the information barrier prohibits adding
collaborations for users that have restricted access
to a file or folder.

The `additional_details` payload provides details of the restricted
collaboration.

```json theme={null}
{
  "source": {
    "folder_id": "12334556",
    "folder_name": "Contracts",
    "user_id": "1234567",
    "user_name": "Unknown User",
    "parent": {
      "type": "folder",
      "name": "All Files",
      "id": "0"
    },
    "owned_by": {
      "type": "user",
      "id": "12345678",
      "name": "Unknown User",
      "login": "user@email.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "16335351460",
    "name": "Unknown User",
    "login": "user@email.com"
  },
  "action_by": null,
  "created_at": "2022-10-05T14:15:14-07:00",
  "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
  "event_type": "SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED",
  "ip_address": "Unknown IP",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "type": "box://event/additional_details/collaboration",
    "collab_id": "0",
    "is_performed_by_admin": false
  }
}
```

### Shared item access blocked

A `SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED` event is triggered when the information barrier prohibits accessing a file or folder using the shared link.

The `additional_details` payload provides details of the shared link and additional security information.

```json theme={null}
{
  "source": {
    "item_type": "folder",
    "item_id": "123456789",
    "item_name": "Contracts",
    "parent": {
      "type": "folder",
      "name": "All Files",
      "id": "0"
    },
    "owned_by": {
      "type": "user",
      "id": "123456789",
      "name": "Unknown User",
      "login": "user@email.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "123456789",
    "name": "Unknown User",
    "login": "user@email.com"
  },
  "action_by": null,
  "created_at": "2022-10-06T13:27:58-07:00",
  "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
  "event_type": "SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED",
  "ip_address": "Unknown IP",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "shared_link_id": "abcdefghijklm",
    "security_information": {
      "accessFromSharedObject": {
        "sharedId": 123456789,
        "sharedName": "abcdefghijklmnop",
        "passwordSet": false,
        "accessLevel": "open",
        "createdAt": "2022-10-06T13:27:21-07:00"
      }
    }
  }
}
```

### Moving item blocked

A `SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED` event is triggered when the
information barrier prohibits moving an item (a file or a folder) to
a folder the user has no access to.

The `additional_details` payload provides details of the folder.

```json theme={null}
{
  "source": {
    "item_type": "folder",
    "item_id": "123456789",
    "item_name": "Contracts",
    "parent": {
      "type": "folder",
      "name": "All Files",
      "id": "0"
    },
    "owned_by": {
      "type": "user",
      "id": "123456789",
      "name": "Unknown User",
      "login": "user@email.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "123456789",
    "name": "Unknown User",
    "login": "user@email.com"
  },
  "action_by": null,
  "created_at": "2022-10-06T13:26:58-07:00",
  "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
  "event_type": "SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED",
  "ip_address": "Unknown IP",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "destination_folder": {
      "item_type": "folder",
      "item_id": "123456789",
      "item_name": "Contracts Signed"
    }
  }
}
```

### Copying item blocked

A `SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED` event is triggered when the
information barrier prohibits copying an item (a file or a folder) to
a folder the user has no access to.

The `additional_details` payload provides details of the destination
folder.

```json theme={null}
{
  "source": {
    "item_type": "folder",
    "item_id": "123456789",
    "item_name": "Contracts",
    "parent": {
      "type": "folder",
      "name": "All Files",
      "id": "0"
    },
    "owned_by": {
      "type": "user",
      "id": "123456789",
      "name": "Unknown User",
      "login": "user@email.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "123456789",
    "name": "Unknown User",
    "login": "user@email.com"
  },
  "action_by": null,
  "created_at": "2022-10-05T14:25:15-07:00",
  "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
  "event_type": "SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED",
  "ip_address": "Unknown IP",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "destination_folder": {
      "item_type": "folder",
      "item_id": "123456789",
      "item_name": "Contracts Signed"
    }
  }
}
```

### Item transfer ownership blocked

A `SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED` event is triggered
when the information barrier prohibits transferring the item ownership to a
user that is subject to restrictions.

The `additional_details` payload provides details of the user that cannot
be set as the new owner.

```json theme={null}
{
  "source": {
    "item_type": "folder",
    "item_id": "",
    "item_name": "All Files",
    "parent": {
      "type": "folder",
      "name": "",
      "id": ""
    },
    "owned_by": {
      "type": "user",
      "id": "123456789",
      "name": "Unknown User",
      "login": "user@email.com"
    }
  },
  "created_by": {
    "type": "user",
    "id": "123456789",
    "name": "Unknown User",
    "login": "user@email.com"
  },
  "action_by": null,
  "created_at": "2022-10-07T09:29:20-07:00",
  "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
  "event_type": "SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED",
  "ip_address": "10.1.2.3",
  "type": "event",
  "session_id": null,
  "additional_details": {
    "restricted_user": {
      "type": "user",
      "id": "123456789",
      "name": "Unknown User",
      "login": "user@email.com"
    },
    "service_id": "123456789",
    "service_name": "App"
  }
}
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Shield Smart Access Events
Source: https://developer.box.com/guides/events/event-triggers/shield-smart-access-events



[Smart Access][smartaccess] enables Box Admins to define and enforce
classification-based access policies to control access and prevent the
unintentional leakage of sensitive content.

Smart Access policies can be configured in
[enforced or monitoring mode][monitoringmode]. In all event types,
a field named `controlMode` appears to say whether the policy is in `enforced`
or `monitoring` mode.

## Download and Print Restriction

If an admin creates a Shield access policy that enforces download or print
restriction and an end user is blocked from downloading or printing a file, an
event is
produced within the <Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream. If the access policy is
set to monitor potential download and print violations,
events will also be generated
when a user is viewing a folder with a file restricted from download or print,
viewing a file in preview that is restricted from download or print, and when a
user requests to download a file through the API that is restricted from
download or print. These events follow the standard event object schema and the
`event_type` value set to `SHIELD_DOWNLOAD_BLOCKED`.

If downloading is blocked, the `additional-details` payload of the
`SHIELD_DOWNLOAD_BLOCKED` event will provide the below details.

For the Box Web App, the `additional_details` payload will
provide the following details:

```json theme={null}
"additional_details": {
  "shield_download_enforcement": {
    "item": {
      "type": "file",
      "id": 987654321,
      "name": "testFile.docx",
      "file_version_id": 38495726173,
      "size": 370,
      "sha1": "db0a61e73b5e6985d190134e0a4b9982c716afeb"
    },
    "access_user": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "service": null,
    "additional_info": "",
    "created_at": "2022-02-22T10:35:08-08:00",
    "classification": "Confidential",
    "controlMode": "enforced"
  }
}
```

For the Box Desktop App, the `additional_details` payload will
provide the following details:

```json theme={null}
"additional_details": {
  "shield_download_enforcement": {
    "item": {
      "type": "file",
      "id": 123456789,
      "name": "testFile.docx",
      "file_version_id": 987654321,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "access_user": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "service": {
      "service": 254429,
      "name": "Box Drive"
    },
    "additional_info": "",
    "created_at": "2022-02-22T10:38:58-08:00",
    "classification": "Confidential",
    "controlMode": "enforced"
  },
  "service_id": "254429",
  "service_name": "Box Drive"
}
```

For Box Mobile apps, the `additional_details` payload will
provide the following details:

```json theme={null}
"additional_details": {
  "shield_download_enforcement": {
    "item": {
      "type": "file",
      "id": 987654321,
      "name": "testFile.docx",
      "file_version_id": 38495726173,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "access_user": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "service": {
      "service": 4715,
      "name": "Box for Android"
    },
    "additional_info": "",
    "created_at": "2022-01-18T14:51:37-08:00",
    "classification": "Confidential",
    "controlMode": "monitoring"
  },
  "service_id": "4715",
  "service_name": "Box for Android"
}
```

## External collaboration restriction

If an external collaboration invitation is restricted, an event is produced
within the <Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream. These events follow
the standard event object schema, with the `event_type` value set
to: `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION`,
`SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED`,
`SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED`,
`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION`, or
`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED`.

If an external collaboration invitation is blocked, the `additional-details`
payload of the `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED` or
`SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION` event will provide
the following details:

```json theme={null}
"additional_details": {
  "shield_external_collab_enforcement": {
    "item": {
      "type": "file",
      "id": 987654321,
      "name": "testFile.docx",
      "file_version_id": 987654321,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "inviter": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "invitee": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "accessUser": null,
    "service": null,
    "additionalInfo": "",
    "createdAt": null,
    "justification": null,
    "classification": "Confidential",
    "controlMode": "enforced"
  }
}
```

If an external collaboration invitation is justified, the `additional_details`
payload of the `SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED` event will provide the
following details:

```json theme={null}
"additional_details": {
  "shield_external_collab_enforcement": {
    "item": {
      "type": "file",
      "id": 123456789,
      "name": "testFile.docx",
      "file_version_id": 123456789,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "inviter": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "invitee": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "accessUser": null,
    "service": null,
    "additionalInfo": "",
    "createdAt": null,
    "justification": {
      "justification_id": "17786127",
      "request_at": 1644874023,
      "requested_by": {
        "type": "user",
        "id": 123456789,
        "name": "Some Name",
        "login": "somename@box.com"
      },
      "request_type": "EXTERNAL_COLLAB",
      "item": {
        "type": "file",
        "id": 987654321,
        "name": "testFile.docx",
        "file_version_id": 941051265322,
        "size": 11640,
        "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
      },
      "user": {
        "type": "user",
        "id": 123456789,
        "name": "Some Name",
        "login": "somename@box.com"
      },
      "title": "Approved",
      "description": "",
      "additional_info": null,
      "approved_by": {
        "type": "user",
        "id": 123456789,
        "name": "Some Name",
        "login": "somename@box.com"
      },
      "action": "APPROVED",
      "action_at": 1644874023,
      "details": null
    },
    "classification": "Confidential",
    "controlMode": "enforced"
  }
}
```

If external collaboration access is blocked, the `additional_details`
payload of the `SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED` or
`SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION` event will provide
the following details:

```json theme={null}
"additional_details": {
  "shield_external_collab_enforcement": {
    "item": {
      "type": "file",
      "id": 987654321,
      "name": "testFile.docx",
      "file_version_id": 987654321,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "inviter": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "invitee": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "accessUser": null,
    "service": null,
    "additionalInfo": "",
    "createdAt": null,
    "justification": null,
    "classification": "Confidential",
    "controlMode": "enforced"
  }
}
```

If a Shield justification is approved, an event is produced within the
<Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream. These events follow the
standard event object schema and the `event_type` value set
to `SHIELD_JUSTIFICATION_APPROVAL`.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_justification": {
    "justification_id": "18428718",
    "request_at": 1645556286,
    "requested_by": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "request_type": "EXTERNAL_COLLAB",
    "item": {
      "type": "file",
      "id": 987654321,
      "name": "testFile.docx",
      "file_version_id": 987654321,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "user": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "title": "Partner Project",
    "description": "",
    "additional_info": null,
    "approved_by": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "action": "APPROVED",
    "action_at": 1645556286,
    "details": null
  }
}
```

<Info>
  Admins, please note that you may see two enterprise events instead of one when
  a justification is chosen from the share modal. For example, one
  `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION` event and one
  `SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED` event.
</Info>

## Integration Restriction

If a 3rd-party application, including published platform applications with which
your organization is integrated, is restricted from downloading a file or a
folder, an event is produced within the <Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream.
These events follow the standard event object schema, with the `event_type`
value set to `SHIELD_DOWNLOAD_BLOCKED`.

For 3rd-party applications, the `additional_details` payload will provide the
following details:

```json theme={null}
"additional_details": {
  "shield_download_enforcement": {
    "item": {
      "type": "file",
      "id": 875644956551,
      "name": "blaha.docx",
      "file_version_id": 941051265322,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "access_user": {
      "type": "user",
      "id": 11754686560,
      "name": "Ming Feng",
      "login": "mfeng+demo@boxdemo.com"
    },
  "service": "docusign",
  "additional_info": "",
  "created_at": "2022-01-18T14:53:53-08:00",
  "classification": "Confidential",
  "controlMode": "enforced"
}
```

For platform applications, the `additional_details` payload will provide the
following details:

```json theme={null}
"additional_details": {
  "shield_download_enforcement": {
    "item": {
      "type": "file",
      "id": 123456789,
      "name": "testFile.docx",
      "file_version_id": 987654321,
      "size": 11640,
      "sha1": "368acd076a89ce82e62cac004fa27ea9ce3019d7"
    },
    "access_user": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "service": {
      "service": 123456,
      "name": "CustomApp"
    },
    "additional_info": "",
    "created_at": "2022-01-18T13:31:25-08:00",
    "classification": "Confidential",
    "controlMode": "enforced"
  },
  "service_id": "123456",
  "service_name": "CustomApp"
}
```

## FTP Restriction

If download of a file or folder is restricted via the FTP protocol, an event is
produced within the <Link href="/guides/events/enterprise-events/for-enterprise">enterprise event</Link> stream. These events follow the
standard event object schema, with the `event_type` value
set to `SHIELD_DOWNLOAD_BLOCKED`.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "shield_download_enforcement": {
    "item": {
      "type": "file",
      "id": 123456789,
      "name": "textFile.txt",
      "file_version_id": 987654321,
      "size": 3606,
      "sha1": "ab7a79ff8e2a6b576e1c62d850290a09312fb387"
    },
    "access_user": {
      "type": "user",
      "id": 123456789,
      "name": "Some Name",
      "login": "somename@box.com"
    },
    "service": {
      "service": 4082,
      "name": "Box FTP Server"
    },
    "additional_info": "",
    "created_at": "2022-01-18T14:19:51-08:00",
    "classification": null,
    "controlMode": "enforced"
  },
  "service_id": "4082",
  "service_name": "Box FTP Server"
}
```

[smartaccess]: https://docs.box.com/en/box-shield/shield-smart-access-policies/about-smart-access

[monitoringmode]: https://support.box.com/hc/en-us/articles/14596333776403-Shield-Access-Policy-Settings

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Sign Events
Source: https://developer.box.com/guides/events/event-triggers/sign-events



Audit Box Sign events using the enterprise events stream. To learn more about
Box Sign, visit our <Link href="/guides/box-sign">guide</Link>.

<Warning>
  The status provided below in each `additional_details` payload may differ
  from the example based on the specific sign request details. For example,
  if the requester is the only signer, the status of the `SIGN_DOCUMENT_CREATED`
  event will immediately be `viewed`.
</Warning>

## Document Events

### Created

A `SIGN_DOCUMENT_CREATED` `event_type` is produced when a sign request is
created via API or UI. At this stage the sign request is not sent to signers
yet.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "sent",
    "signer_ip_address": null,
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": null,
    "template": {
      "id": "987abC5423",
      "template_type": "Signing",
      "name": "Work Contact"
    },
    "batch_send": {
      "id": "W23YVL46"
    },
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "sender_message": {
      "subject": "Can you please sign this document?",
      "message": "This document shows the terms agreed to on the phone."
    },
    "forward": null
  }
}
```

### Converted

A `SIGN_DOCUMENT_CONVERTED` `event_type` is produced when a sign request is
converted to a `.pdf` for signing.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "created",
    "signer_ip_address": null,
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": null,
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": null
  }
}
```

### Completed

A `SIGN_DOCUMENT_COMPLETED` `event_type` is produced when all signers have
successfully signed the document.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "signed",
    "signer_ip_address": null,
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": null,
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": null
  }
}
```

### Cancelled

A `SIGN_DOCUMENT_CANCELLED` `event_type` is produced when a sign request is
cancelled by the requester via API or UI.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "cancelled",
    "signer_ip_address": null,
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": null,
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": null
  }
}
```

### Expired

A `SIGN_DOCUMENT_EXPIRED` `event_type` is produced when a sign request expired
with incomplete signatures.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "expired",
    "signer_ip_address": null,
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": null,
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": null
  }
}
```

## Signer Events

### Assigned

A `SIGN_DOCUMENT_ASSIGNED` `event_type` is produced when a sign request is
successfully sent to a signer.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "sent",
    "signer_ip_address": "",
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": {
      "id": "246813579",
      "type": "user",
      "name": "Jane Doe",
      "login": "janedoe@example.com"
    },
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "ready_sign_link": {
      "id": "aaae45bb-e89b-12d3-a456-426614174000"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": null
  }
}
```

### Viewed by Signer

A `SIGN_DOCUMENT_VIEWED_BY_SIGNER` `event_type` is produced when a sign request
signer clicks on **Review Document** in the signing email or visits the signing
URL.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "viewed",
    "signer_ip_address": "",
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": {
      "id": "246813579",
      "type": "user",
      "name": "Jane Doe",
      "login": "janedoe@example.com"
    },
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "ready_sign_link": {
      "id": "aaae45bb-e89b-12d3-a456-426614174000"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": null
  }
}
```

### Downloaded

A `SIGNER_DOWNLOADED` `event_type` is produced when a signer downloads the
signing document.

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "viewed",
    "signer_ip_address": "",
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": {
      "id": "246813579",
      "type": "user",
      "name": "Jane Doe",
      "login": "janedoe@example.com"
    },
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "ready_sign_link": {
      "id": "aaae45bb-e89b-12d3-a456-426614174000"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": {
      "forwarded_to_email": "janedoe@box.com",
      "forwarded_reason": "Please sign",
      "forwarded_at": "2022-03-03T12:04:20-10:00"
    }
  }
}
```

### Forwarded

A `SIGNER_FORWARDED` `event_type` is produced when a signer forwards the
signing document.

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "viewed",
    "signer_ip_address": "",
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": {
      "id": "246813579",
      "type": "user",
      "name": "Jane Doe",
      "login": "janedoe@example.com"
    },
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "ready_sign_link": {
      "id": "aaae45bb-e89b-12d3-a456-426614174000"
    },
    "sender_message": {
      "subject": "Can you please sign this document?",
      "message": "This document shows the terms agreed to on the phone."
    },
    "forward": {
      "forwarded_to_email": "somename@box.com",
      "forwarded_reason": "I need to forward to my business partner.",
      "forwarded_at": "2022-02-03T10:04:52-08:00",
    },
  }
}
```

### Signed

A `SIGN_DOCUMENT_SIGNED` `event_type` is produced when a signer completes the
sign request.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "signed",
    "signer_ip_address": "",
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": {
      "id": "246813579",
      "type": "user",
      "name": "Jane Doe",
      "login": "janedoe@example.com"
    },
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "ready_sign_link": {
      "id": "aaae45bb-e89b-12d3-a456-426614174000"
    },
    "sender_message": {
      "subject": "Can you please sign this document?",
      "message": "This document shows the terms agreed to on the phone."
    },
    "forward": null
  }
}
```

### Declined

A `SIGN_DOCUMENT_DECLINED` `event_type` is produced when a sign request signer
declines the request.

The `additional_details` payload will provide the following details:

```json theme={null}
"additional_details": {
  "sign_request": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "sign_request_short_id": "426614174000",
    "status": "declined",
    "signer_ip_address": "",
    "requestor_ip_address": "",
    "files": [
      {
        "id": "1234567890",
        "type": "file",
        "name": "example_doc.pdf",
        "parent": {
          "id": "987654321",
          "type": "folder"
        }
      }
    ],
    "expires": null,
    "requestor": {
      "id": "13579246",
      "type": "user",
      "name": "John Doe",
      "login": "johndoe@box.com"
    },
    "signer": {
      "id": "246813579",
      "type": "user",
      "name": "Jane Doe",
      "login": "janedoe@example.com"
    },
    "template": null,
    "batch_send": null,
    "redirection": {
      "redirect_url": "https://www.google.com",
      "declined_redirect_url": "https://www.googledecline.com"
    },
    "ready_sign_link": {
      "id": "aaae45bb-e89b-12d3-a456-426614174000"
    },
    "sender_message": {
      "subject": "",
      "message": ""
    },
    "forward": null
  }
}
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Events overview
Source: https://developer.box.com/guides/events/index

Subscribe to user or enterprise events in Box, compare stream types, and monitor actions in real time or query historical records.

The event feed provides a way for an application to subscribe to any actions
performed by any user, users, or service in an enterprise.

## User vs Enterprise events

Depending upon the `stream_type`, the <Link href="/reference/get-events">`GET /events`</Link> API
enables subscribing to live events across the enterprise or for a particular
user, or querying historical events across the enterprise.

### User events

User events provide a low latency stream of events relevant to the currently
authenticated user. This event stream is how Box keeps [Box Drive][drive] up to
date, but is also made available for developer use.

The emphasis of this feed is to return the complete results quickly, which means
that Box may return events more than once or out of chronological order.
Duplicate events can be identified by their event IDs.

Unlike the enterprise events streams, the user events stream does not support
filtering for specific events. The three user events stream\_types return
slightly different subsets of the user events dataset for different purposes.

| Stream Type | |
| - | - |
| `all` | Returns everything for a user (default) |
| `changes` | Returns events that may cause file tree changes such as file updates or collaborations |
| `sync` | Is similar to changes but only applies to synced folders |

### Enterprise events

Enterprise events provide an event feed for all users and content in an
enterprise Box instance. Depending upon the `stream_type` your application can
either subscribe to live events or query historical events. Access to these
stream types is limited to users with admin permissions to
**Run new reports and access existing reports**.

Unlike the user events stream, the enterprise events stream supports filtering
based on event type but does not support long polling. Across the two
stream types the dataset is exactly the same. Events can be deduplicated across
the two stream types using their event IDs.

| Stream Type | |
| - | - |
| `admin_logs` | Enables querying historical events up to one year |
| `admin_logs_streaming` | Enables subscribing to live events in near real time |

#### Live Monitoring

To monitor recent events that have been generated within Box across the
enterprise, set the `stream_type` to `admin_logs_streaming`. This is also known
as the Enterprise Event Stream API.

The emphasis for this feed is on low latency rather than chronological
accuracy, which means that Box may return events more than once and out of
chronological order. Events are returned via the API in near real time after
they are processed by Box. A small delay/buffer ensures that new events are not
written after your cursor position. Only two weeks of events are available via
this `stream_type`.

#### Quick example

List the most recent user events:

```bash theme={null}
curl https://api.box.com/2.0/events?stream_type=all \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

#### Historical Querying

To query historical events across the enterprise up to one year old, set the
`stream_type` to `admin_logs`. This is also known as the Enterprise Event
History API.

The emphasis for this feed is on completeness over latency, which means that
Box will deliver admin events in chronological order and without duplicates,
but with higher latency than the user or `admin_logs_streaming` feed. Consuming
events in near real time may lead to missed events as events can arrive later
than your filtering window.

[drive]: https://www.box.com/drive


# Stream Position Pagination
Source: https://developer.box.com/guides/events/parameters/pagination



Paginating the event stream works through the use of the `stream_position`
parameter.

First, send a request to the <Link href="/reference/get-events">`GET /events`</Link> API without a
`stream_position` query parameter.

```sh theme={null}
curl https://api.box.com/2.0/events \
    -H "authorization: Bearer ACCESS_TOKEN"
```

The API will return all available events beginning with the oldest. The response
will also include a `next_stream_position` value that can be used to make the
next API call for the next place in the stream.

```sh theme={null}
curl https://api.box.com/2.0/events?stream_position=388720462721 \
    -H "authorization: Bearer ACCESS_TOKEN"
```

The `stream_position` can also be set to `now` to return the most recent stream
position.

```sh theme={null}
curl https://api.box.com/2.0/events?stream_position=now \
    -H "authorization: Bearer ACCESS_TOKEN"
```

In this case, the API returns an empty list and a `next_stream_position` that
can be used for the next call.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Stream Types
Source: https://developer.box.com/guides/events/parameters/stream-types



| Stream Types | Scope | Purpose | Description | Retention | Access Pattern |
| - | - | - | - | - | - |
| `admin_logs` | A single enterprise (for authorized admins) | Historical Queries | Enables querying historical events up to one year | 365 Days | Filter by time frame, then paginate through the response by `stream_position` |
| `admin_logs_streaming` | A single enterprise (for authorized admins) | Near real time subscriptions | Enables subscribing to live events in near real time | 14 Days | Poll using the `stream_position` |
| `all` (default) | A single user (for any user) | Near real time subscriptions | Returns everything for a user | 21 Days | Poll or long-poll using the `stream_position` |
| `changes` | A single user (for any user) | Near real time subscriptions | Returns events that may cause file tree changes such as file updates or collaborations | 21 Days | Poll or long-poll using the `stream_position` |
| `sync` | A single user (for any user) | Near real time subscriptions | Is similar to `changes` but only applies to synced folders | 31 Days | Poll or long-poll using the `stream_position` |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get User Events
Source: https://developer.box.com/guides/events/user-events/for-user



To get a user's events, authenticate as any user and make a call to the
<Link href="/reference/get-events">`GET /events`</Link> API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/events" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.events.getEvents();
  ```

  ```python Python v10 theme={null}
  client.events.get_events()
  ```

  ```csharp .NET v10 theme={null}
  await client.Events.GetEventsAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.events.getEvents()
  ```

  ```java Java v10 theme={null}
  client.getEvents().getEvents()
  ```

  ```java Java v5 theme={null}
  EventStream stream = new EventStream(api);
  stream.addListener(new EventListener() {
    public void onEvent(BoxEvent event) {
        // Handle the event.
      }
  });
  stream.start();
  ```

  ```py Python v4 theme={null}
  stream_position = 0
  events = client.events().get_events(stream_position=stream_position)
  stream_position = events['next_stream_position']
  for event in events['entries']:
      print(f'Got {event.event_type} event that occurred at {event.created_at}')
  ```

  ```csharp .NET v6 theme={null}
  BoxEventCollection<BoxEnterpriseEvent> events = await client.EventsManager.UserEventsAsync();
  ```

  ```js Node v4 theme={null}
  client.events.get({stream_position: '1408838928446360'}, callback);
  ```
</CodeGroup>

<Info>
  The events returned will only be for the user whose access token the API was
  made with. To get the event feed for a different user either use the `as-user`
  header or an actual access token for that user.
</Info>

## Stream Types

The user event stream supports 3 types of stream.

| Stream Type | |
| - | - |
| `all` | Returns everything for a user (default) |
| `changes` | Returns events that may cause file tree changes such as file updates or collaborations. |
| `sync` | Is similar to changes but only applies to synced folders |

## Anonymous Users

In some cases, the event feed might list a user with an ID of `2`. This is Box's
internal identifier for anonymous users.

An anonymous user is a user that is not logged in. This can happen any time a
user interacts with content and they aren't asked to log in first. An example
would be when a user downloads a file through an open shared link.

## Limitations

Box does not store events indefinitely.

User events are stored for between two weeks and two months, after which the
user events are removed. Enterprise events are accessible for one year via the
API and seven years via exported reports in the Box Admin Console.

The emphasis of this feed is to return the complete results quickly, which means
that Box may return events more than once or out of order. Duplicate events can
be identified by their event IDs.

## Long Polling

The user event stream supports long-polling
<Link href="/guides/events/user-events/polling">through the `OPTIONS /events` API</Link>.

## Event Types

The following events can be triggered for a user. This list is not exhaustive,
so it is possible events appear that are not listed.

The following events are available in all feeds.

| Event name | Description |
| - | - |
| `ITEM_CREATE` | A folder or File was created |
| `ITEM_UPLOAD` | A folder or File was uploaded |
| `ITEM_MOVE` | A file or folder was moved |
| `ITEM_COPY` | A file or folder was copied |
| `LOCK_CREATE` | A file was locked |
| `LOCK_DESTROY` | A file was unlocked. If a locked file is deleted, the source file will be null. |
| `ITEM_TRASH` | A file or folder was marked as deleted |
| `ITEM_UNDELETE_VIA_TRASH` | A file or folder was recovered out of the trash |
| `COLLAB_ADD_COLLABORATOR` | A collaborator was added to a folder |
| `COLLAB_ROLE_CHANGE` | A collaborator had their role changed |
| `COLLAB_INVITE_COLLABORATOR` | A collaborator was invited on a folder |
| `COLLAB_REMOVE_COLLABORATOR` | A collaborator was removed from a folder |
| `ITEM_SYNC` | A folder was marked for sync |
| `ITEM_UNSYNC` | A folder was unmarked for sync |
| `ITEM_RENAME` | A file or folder was renamed |
| `ITEM_MAKE_CURRENT_VERSION` | A previous version of a file was promoted to the current version |
| `GROUP_ADD_USER` | Added user to group |
| `GROUP_REMOVE_USER` | Removed user from group |

The following events are only available in the `all` feed.

| Event name | Description |
| - | - |
| `COMMENT_CREATE` | A comment was created on a folder, file, or other comment |
| `COMMENT_DELETE` | A comment was deleted on folder, file, or other comment |
| `ITEM_DOWNLOAD` | A file or folder was downloaded |
| `ITEM_PREVIEW` | A file was previewed |
| `TASK_ASSIGNMENT_CREATE` | A task was assigned |
| `TASK_CREATE` | A task was created |
| `ITEM_SHARED_CREATE` | A file or folder was enabled for sharing |
| `ITEM_SHARED_UNSHARE` | A file or folder was disabled for sharing |
| `ITEM_SHARED` | A folder was shared |
| `TAG_ITEM_CREATE` | A Tag was added to a file or folder |
| `ENABLE_TWO_FACTOR_AUTH` | 2 factor authentication enabled by user |
| `MASTER_INVITE_ACCEPT` | Free user accepts invitation to become a managed user |
| `MASTER_INVITE_REJECT` | Free user rejects invitation to become a managed user |
| `ACCESS_GRANTED` | Granted Box access to account |
| `ACCESS_REVOKED` | Revoke Box access to account |

## Event notifications

To reduce the noise of the event stream and optimize event consumption, the event types listed in the table trigger a limited number of notifications.

| Event type | Notification behavior |
| - | - |
| `COLLAB_ADD_COLLABORATOR`, `COLLAB_REMOVE_COLLABORATOR`, `COLLAB_INVITE_COLLABORATOR`, `COLLAB_ROLE_CHANGE` | When these events take place, the content owner on the `changes` event stream is notified. Collaborators see an additional event that matches what they see on the `all` stream. |
| `ITEM_DOWNLOAD` | When an item is downloaded, only the content owner gets the notification. Collaborators are not notified. |
| `ITEM_PREVIEW` | When an item is previewed, only the content owner gets the notification. Collaborators are not notified. |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# User Events
Source: https://developer.box.com/guides/events/user-events/index



User Events provide a low latency stream of events relevant to the currently
authenticated user. This event stream is how Box keeps Box Drive up to date,
but is also made available for developer use.


# Long-Poll Events
Source: https://developer.box.com/guides/events/user-events/polling



To get real-time notification of activity in a Box account you can use the long
poll feature of the <Link href="/reference/options-events">`OPTIONS /events`</Link> API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X OPTIONS "https://api.box.com/2.0/events" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.events.getEventsWithLongPolling();
  ```

  ```python Python v10 theme={null}
  client.events.get_events_with_long_polling()
  ```

  ```cs .NET v10 theme={null}
  await client.Events.GetEventsWithLongPollingAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.events.getEventsWithLongPolling()
  ```

  ```java Java v10 theme={null}
  client.getEvents().getEventsWithLongPolling()
  ```

  ```python Python v4 theme={null}
  events = client.events().generate_events_with_long_polling()
  for event in events:
      print(f'Got {event.event_type} event')
  ```

  ```javascript Node v4 theme={null}
  client.events.getEventStream(function(err, stream) {
    if (err) {
      // handle error
    }
    stream.on('data', function(event) {
      // handle the event
    });
  });
  ```
</CodeGroup>

<Warning>
  Long polling is only available for user events. Enterprise events do not
  support long polling.
</Warning>

## Long Polling

Long polling involves opening an HTTP request and keeping it open until the
server sends a response, then repeating the process over and over to receive
updated responses.

<Info>
  The SDKs have built-in support for turning the event feeds into an event
  stream by long polling for new events.
</Info>

### Long Poll URL

To use long polling, first send a request to the
<Link href="/reference/options-events">`OPTIONS /events`</Link> API to retrieve the long poll URL.

```sh theme={null}
curl -X OPTIONS https://api.box.com/2.0/events \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
{
  "chunk_size": 1,
  "entries": [
    {
      "type": "realtime_server",
      "url": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all",
      "ttl": 10,
      "max_retries": 10,
      "retry_timeout": 610
    }
  ]
}
```

### Real-Time Servers

Next, make a `GET` request to the provided URL to begin listening for events. If
an event occurs in an account that is being monitored the application will
receive a response with the value `new_change`. The response contains no other
details.

This single response serves as a prompt to take further action such as
sending a request to the `GET /events` endpoint with the last known
`stream_position`.

### Disconnect & Reconnect

After the server sends this response it closes the connection. The application
must now repeat the long poll process to begin listening for events again.

If no events occur for a while after the application connects to the real-time
server the connection will close with a `reconnect` value. When this happens the
application should make a new call to `OPTIONS /events` to restart the process.

### Timeouts & Retries

If the application receives no events in `retry_timeout` seconds then the
application can reconnect to the real-time server. This might be necessary
due to network errors.

If the application receives a `max_retries` error when making a `GET` request to
the real-time server then it must restart the process by making an `OPTIONS` call
to the `/events` API.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Turn an enterprise document repository into an access-controlled AI knowledge base
Source: https://developer.box.com/guides/hubs-api/access-controlled-knowledge-base

Build an access-controlled AI knowledge base with Box Hubs and Box AI Ask. Answers inherit Box permissions. No vector database needed.

Curate approved content into a <Link href="/guides/hubs-api">Box Hub</Link> and query it with <Link href="/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub">Box AI Ask</Link>. Box indexes hub items and checks the requesting user's permissions on every request. Answers only reference content the caller can already open in Box. No vector database needed.

## Why this pattern

A shared knowledge base must answer four questions a personal folder does not:

* Who can read a given file, and who can change it?
* Which version is current?
* Which content is approved for AI, and which is draft or stale?
* Can an answer cite the source document?

Box already stores versions, collaborations, and audit history. A hub is a curated view over that content. Box AI Ask searches the hub's index and returns answers with citations, filtered by the caller's permissions.

## Build the knowledge base

<Steps>
  <Step title="Keep the repository in Box">
    Store the source files in Box folders. Do not grant an AI system access to the entire enterprise by default. Start with the smallest set of folders that supports the use case.
  </Step>

  <Step title="Separate staging from approved content">
    New or updated files land in a staging area. Only reviewed content moves into the folders you add to the hub. Metadata such as owner, domain, and approval status tracks review state. See <Link href="/guides/metadata">metadata</Link> and, when values live inside the document, <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured">Box AI Extract</Link>.
  </Step>

  <Step title="Publish approved files to a hub">
    Create a hub with the <Link href="/guides/hubs-api/hubs/create-hub">Hubs API</Link>, then add the approved folders or files as <Link href="/guides/hubs-api/hubs-items/hub-items">hub items</Link>. Invite people or groups with <Link href="/guides/hubs-api/hubs-collaborations/hub-collaborations">hub collaborations</Link>. Hub access does not replace file permissions. A collaborator still cannot see a file they are not allowed to open.
  </Step>

  <Step title="Query the hub with Box AI Ask">
    Enable AI on the hub (`is_ai_enabled`). See <Link href="/guides/hubs-api/hubs/update-hub">Update a hub</Link>. Then call <Link href="/reference/post-ai-ask">`POST /2.0/ai/ask`</Link> and pass the hub as an item with `"type": "hubs"`. Box searches the hub index and returns answers grounded in documents the requesting identity can access. Enable citations so the response points back to source files. See <Link href="/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub">Ask questions about a hub</Link>.
  </Step>
</Steps>

## Permissions

Box Hubs and Box AI do not have their own permission system. They inherit waterfall permissions, collaborations, and scopes from the authenticated user or application.

* Connecting an agent or calling Ask does not expose every file in the enterprise.
* If a user has no access to a file in Box, Box AI does not include that file in their answer.
* Use a dedicated service account only when that account is an intentional, audited identity with collaborations on the approved content. Do not use a service account to bypass user permissions.

For agent connections, see <Link href="/guides/box-mcp/permission-aware-access">secure, permission-aware agent access</Link>.

## When to use a vector database instead

Use hubs + Ask when the content is already in Box and you need permission-aware answers.

Build your own RAG pipeline only when you need a retrieval engine Box AI does not provide, an index that mixes Box with other sources, or custom chunking and ranking. If you export content, your pipeline must enforce Box permissions and stay current as files, versions, and collaborations change. See <Link href="/ai/rag">Build RAG over enterprise documents stored in Box</Link>.

## Worked examples

<CardGroup>
  <Card title="Build your company brain" href={localizeLink("/tutorials/company-brain")} icon="brain">
    A shared knowledge layer for people and agents. Includes folders, Box AI review, governance metadata, hubs, and Ask.
  </Card>

  <Card title="Sales RFP answer bank" href={localizeLink("/tutorials/sales-rfp-answer-bank")} icon="magnifying-glass">
    Provision a hub, add curated RFP content, embed the hub, and answer sales questions with Box AI.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Manage hub collaborations
Source: https://developer.box.com/guides/hubs-api/hubs-collaborations/hub-collaborations



Box Hub collaborations control who can access a hub and at what role. You can invite users or groups by user ID, group ID, or email (for users). Roles are `editor`, `viewer`, and `co-owner`. You can only invite users who have a Box account (any plan) to collaborate on a hub.

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## Create a hub collaboration

To add a user or group to a hub, call the <Link href="/reference/v2025.0/post-hub-collaborations">`POST /2.0/hub_collaborations`</Link> endpoint and provide:

* The hub reference (`HUB_ID`)
* The collaborator's ID and type in the `accessible_by` field
* The level of access granted to a hub in the `role` field

### Create by user ID

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:collaborations:create HUB_ID --role viewer --user-id USER_ID
  ```

  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/hub_collaborations" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "hub": {
           "type": "hubs",
           "id": "HUB_ID"
         },
         "accessible_by": {
           "type": "user",
           "id": "USER_ID"
         },
         "role": "viewer"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubCollaborations.createHubCollaborationV2025R0({
    hub: new HubCollaborationCreateRequestV2025R0HubField({ id: hub.id }),
    accessibleBy: {
      type: 'user',
      id: user.id,
    } satisfies HubCollaborationCreateRequestV2025R0AccessibleByField,
    role: 'viewer',
  } satisfies HubCollaborationCreateRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.hub_collaborations.create_hub_collaboration_v2025_r0(
      CreateHubCollaborationV2025R0Hub(id=hub.id),
      CreateHubCollaborationV2025R0AccessibleBy(type="user", id=user.id),
      "viewer",
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.HubCollaborations.CreateHubCollaborationV2025R0Async(requestBody: new HubCollaborationCreateRequestV2025R0(hub: new HubCollaborationCreateRequestV2025R0HubField(id: hub.Id), accessibleBy: new HubCollaborationCreateRequestV2025R0AccessibleByField(type: "user") { Id = user.Id }, role: "viewer"));
  ```

  ```swift Swift v10 theme={null}
  try await client.hubCollaborations.createHubCollaborationV2025R0(requestBody: HubCollaborationCreateRequestV2025R0(hub: HubCollaborationCreateRequestV2025R0HubField(id: hub.id), accessibleBy: HubCollaborationCreateRequestV2025R0AccessibleByField(type: "user", id: user.id), role: "viewer"))
  ```

  ```java Java v10 theme={null}
  client.getHubCollaborations().createHubCollaborationV2025R0(new HubCollaborationCreateRequestV2025R0(new HubCollaborationCreateRequestV2025R0HubField(hub.getId()), new HubCollaborationCreateRequestV2025R0AccessibleByField.Builder("user").id(user.getId()).build(), "viewer"));
  ```
</CodeGroup>

### Create by user email (login)

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:collaborations:create HUB_ID --role editor --login john@example.com
  ```

  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/hub_collaborations" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "hub": {
           "type": "hubs",
           "id": "HUB_ID"
         },
         "accessible_by": {
           "type": "user",
           "login": "john@example.com"
         },
         "role": "editor"
       }'
  ```

  ```python Python v10 theme={null}
  client.hub_collaborations.create_hub_collaboration_v2025_r0(
      CreateHubCollaborationV2025R0Hub(id=hub.id),
      CreateHubCollaborationV2025R0AccessibleBy(type="user", login="john@example.com"),
      "editor",
  )
  ```
</CodeGroup>

Replace `HUB_ID`, `USER_ID`, and the email with real values. Valid `role` values are `editor`, `viewer`, and `co-owner`. A successful response returns the new <Link href="/reference/v2025.0/resources/hub-collaboration">Hub collaboration</Link> object.

## List hub collaborations

To list all collaborations for a hub, call the <Link href="/reference/v2025.0/get-hub-collaborations">`GET /2.0/hub_collaborations`</Link> endpoint with the hub ID.

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:collaborations HUB_ID
  ```

  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/hub_collaborations?hub_id=HUB_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubCollaborations.getHubCollaborationsV2025R0({
    hubId: hub.id,
  } satisfies GetHubCollaborationsV2025R0QueryParams);
  ```

  ```python Python v10 theme={null}
  client.hub_collaborations.get_hub_collaborations_v2025_r0(hub.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.HubCollaborations.GetHubCollaborationsV2025R0Async(queryParams: new GetHubCollaborationsV2025R0QueryParams(hubId: hub.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.hubCollaborations.getHubCollaborationsV2025R0(queryParams: GetHubCollaborationsV2025R0QueryParams(hubId: hub.id))
  ```

  ```java Java v10 theme={null}
  client.getHubCollaborations().getHubCollaborationsV2025R0(new GetHubCollaborationsV2025R0QueryParams(hub.getId()));
  ```
</CodeGroup>

Optional query parameters: `marker` and `limit`. For details, see [Marker-based pagination](/guides/api-calls/pagination/marker-based).

## Get a hub collaboration by ID

To retrieve a single hub collaboration, call the <Link href="/reference/v2025.0/get-hub-collaborations-id">`GET /2.0/hub_collaborations/{hub_collaboration_id}`</Link> endpoint with the collaboration ID.

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:collaborations:get HUB_COLLABORATION_ID
  ```

  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/hub_collaborations/HUB_COLLABORATION_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubCollaborations.getHubCollaborationByIdV2025R0(hubCollaborationId);
  ```

  ```python Python v10 theme={null}
  client.hub_collaborations.get_hub_collaboration_by_id_v2025_r0(hub_collaboration_id)
  ```

  ```csharp .NET v10 theme={null}
  await client.HubCollaborations.GetHubCollaborationByIdV2025R0Async(hubCollaborationId: hubCollaborationId);
  ```

  ```java Java v10 theme={null}
  client.getHubCollaborations().getHubCollaborationByIdV2025R0(hubCollaborationId);
  ```
</CodeGroup>

## Update a hub collaboration

To change a collaborator's role, call the <Link href="/reference/v2025.0/put-hub-collaborations-id">`PUT /2.0/hub_collaborations/{hub_collaboration_id}`</Link> endpoint with the hub collaboration ID and the new `role`.

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:collaborations:update HUB_COLLABORATION_ID --role editor
  ```

  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/hub_collaborations/HUB_COLLABORATION_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "role": "editor"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubCollaborations.updateHubCollaborationByIdV2025R0(hubCollaborationId, {
    role: 'editor',
  } satisfies HubCollaborationUpdateRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.hub_collaborations.update_hub_collaboration_by_id_v2025_r0(hub_collaboration_id, role="editor")
  ```

  ```csharp .NET v10 theme={null}
  await client.HubCollaborations.UpdateHubCollaborationByIdV2025R0Async(hubCollaborationId: hubCollaborationId, requestBody: new HubCollaborationUpdateRequestV2025R0() { Role = "editor" });
  ```

  ```java Java v10 theme={null}
  client.getHubCollaborations().updateHubCollaborationByIdV2025R0(hubCollaborationId, new HubCollaborationUpdateRequestV2025R0.Builder().role("editor").build());
  ```
</CodeGroup>

## Delete a hub collaboration

To remove a collaborator from a hub, call the <Link href="/reference/v2025.0/delete-hub-collaborations-id">`DELETE /2.0/hub_collaborations/{hub_collaboration_id}`</Link> endpoint with the hub collaboration ID.

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:collaborations:delete HUB_COLLABORATION_ID
  ```

  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/hub_collaborations/HUB_COLLABORATION_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubCollaborations.deleteHubCollaborationByIdV2025R0(hubCollaborationId);
  ```

  ```python Python v10 theme={null}
  client.hub_collaborations.delete_hub_collaboration_by_id_v2025_r0(hub_collaboration_id)
  ```

  ```csharp .NET v10 theme={null}
  await client.HubCollaborations.DeleteHubCollaborationByIdV2025R0Async(hubCollaborationId: hubCollaborationId);
  ```

  ```java Java v10 theme={null}
  client.getHubCollaborations().deleteHubCollaborationByIdV2025R0(hubCollaborationId);
  ```
</CodeGroup>

A successful delete returns no body (HTTP 204).

## Use cases

* **Onboarding automation:** When a new hire is added to your HRIS, create a "Welcome Hub" and add them as a collaborator with the appropriate role.
* **Group-based access:** Use the <Link href="/reference/get-groups">Box Groups API</Link> to find the right group, then add the group as a collaborator so all members get access.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Manage hub items
Source: https://developer.box.com/guides/hubs-api/hubs-items/hub-items



The Box Hub items API allows you to:

* [List all items in a hub](#list-hub-items).
* [Add or remove files, folders, and web links from a hub](#add-or-remove-hub-items).

<Note>
  At this stage, the API supports managing files, folders, and web links only. Elements such as callouts, dividers, paragraphs, or sections must be added in the Box Hubs web interface. Content added through the API is placed in the first content block.
</Note>

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

<Note>
  The <Link href="/reference/v2025.0/get-hub-items">`GET /2.0/hub_items`</Link> returns HTTP `207` (Multi-Status). The response body includes the status of each operation (add or remove). Follow the API reference for full response and error handling.
</Note>

## List hub items

To retrieve all items in a Box Hub, call the <Link href="/reference/v2025.0/get-hub-items">`GET /2.0/hub_items`</Link> endpoint with the hub ID.

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:items 12345
  ```

  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/hub_items?hub_id=HUB_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubItems.getHubItemsV2025R0({
    hubId: createdHub.id,
  } satisfies GetHubItemsV2025R0QueryParams);
  ```

  ```python Python v10 theme={null}
  client.hub_items.get_hub_items_v2025_r0(created_hub.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.HubItems.GetHubItemsV2025R0Async(queryParams: new GetHubItemsV2025R0QueryParams(hubId: createdHub.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.hubItems.getHubItemsV2025R0(queryParams: GetHubItemsV2025R0QueryParams(hubId: createdHub.id))
  ```

  ```java Java v10 theme={null}
  client.getHubItems().getHubItemsV2025R0(new GetHubItemsV2025R0QueryParams(createdHub.getId()));
  ```
</CodeGroup>

Replace `HUB_ID` with your hub ID. You can use optional query parameters `marker` and `limit` for pagination. The response includes an `entries` array of hub items (each with `id`, `type`, `name`).

## Add or remove hub items

To add or remove items in a hub, call the <Link href="/reference/v2025.0/post-hubs-id-manage-items">`POST /2.0/hubs/{hub_id}/manage_items`</Link> endpoint with the hub ID and a list of operations. Each operation has an `action` (`add` or `remove`) and an `item` reference (`type` and `id`).

### Add a file to a hub

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:items:manage 12345 --add id=11111,type=file
  ```

  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/hubs/HUB_ID/manage_items" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "operations": [
           {
             "action": "add",
             "item": {
               "type": "file",
               "id": "FILE_ID"
             }
           }
         ]
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubItems.manageHubItemsV2025R0(createdHub.id, {
    operations: [
      {
        action: 'add' as HubItemOperationV2025R0ActionField,
        item: new FileReferenceV2025R0({ id: file.id }),
      } satisfies HubItemOperationV2025R0,
    ],
  } satisfies HubItemsManageRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.hub_items.manage_hub_items_v2025_r0(
      created_hub.id,
      operations=[
          HubItemOperationV2025R0(
              action=HubItemOperationV2025R0ActionField.ADD,
              item=FileReferenceV2025R0(id=file.id),
          )
      ],
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.HubItems.ManageHubItemsV2025R0Async(hubId: createdHub.Id, requestBody: new HubItemsManageRequestV2025R0() { Operations = Array.AsReadOnly(new [] { new HubItemOperationV2025R0(action: HubItemOperationV2025R0ActionField.Add, item: new FileReferenceV2025R0(id: file.Id)) }) });
  ```

  ```java Java v10 theme={null}
  client.getHubItems().manageHubItemsV2025R0(createdHub.getId(), new HubItemsManageRequestV2025R0.Builder().operations(Arrays.asList(new HubItemOperationV2025R0(HubItemOperationV2025R0ActionField.ADD, new FileReferenceV2025R0(file.getId())))).build());
  ```
</CodeGroup>

### Add a folder to a hub

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:items:manage 12345 --add id=67890,type=folder
  ```

  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/hubs/HUB_ID/manage_items" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "operations": [
           {
             "action": "add",
             "item": {
               "type": "folder",
               "id": "FOLDER_ID"
             }
           }
         ]
       }'
  ```

  ```python Python v10 theme={null}
  client.hub_items.manage_hub_items_v2025_r0(
      created_hub.id,
      operations=[
          HubItemOperationV2025R0(
              action=HubItemOperationV2025R0ActionField.ADD,
              item=FolderReferenceV2025R0(id=folder.id),
          )
      ],
  )
  ```
</CodeGroup>

### Remove an item from a hub

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:items:manage 12345 --remove id=11111,type=file
  ```

  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/hubs/HUB_ID/manage_items" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "operations": [
           {
             "action": "remove",
             "item": {
               "type": "file",
               "id": "FILE_ID"
             }
           }
         ]
       }'
  ```

  ```python Python v10 theme={null}
  client.hub_items.manage_hub_items_v2025_r0(
      created_hub.id,
      operations=[
          HubItemOperationV2025R0(
              action=HubItemOperationV2025R0ActionField.REMOVE,
              item=FileReferenceV2025R0(id=file.id),
          )
      ],
  )
  ```
</CodeGroup>

Replace `HUB_ID`, `FILE_ID`, and `FOLDER_ID` with actual IDs. For web links, use `"type": "web_link"` and the web link ID. You can combine multiple add and remove operations in a single request.

## Use cases

* **Automate hub creation:** Use the <Link href="/reference/get-search">Box Search API</Link> or metadata queries to find content matching criteria, then add the filtered results to a hub with the manage hub items endpoint.
* **Event-driven updates:** Use <Link href="/guides/webhooks">webhooks</Link> to react to events (for example, a new file in a folder) and add that content to a hub automatically.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Copy a hub
Source: https://developer.box.com/guides/hubs-api/hubs/copy-hub



To create a copy of an existing Box Hub, call the <Link href="/reference/v2025.0/post-hubs-id-copy">`POST /2.0/hubs/{hub_id}/copy`</Link> endpoint with the source hub ID and optional new title and description. The original hub is not modified.

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## Copy hub

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:copy 12345 --title "HR Hub (Copy)" --description "Copy of the HR hub for a new region."
  ```

  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/hubs/HUB_ID/copy" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "title": "HR Hub (Copy)",
         "description": "Copy of the HR hub for a new region."
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubs.copyHubV2025R0(createdHub.id, {
    title: copiedHubTitle,
    description: copiedHubDescription,
  } satisfies HubCopyRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.hubs.copy_hub_v2025_r0(created_hub.id, title=copied_hub_title, description=copied_hub_description)
  ```

  ```csharp .NET v10 theme={null}
  await client.Hubs.CopyHubV2025R0Async(hubId: createdHub.Id, requestBody: new HubCopyRequestV2025R0() { Title = copiedHubTitle, Description = copiedHubDescription });
  ```

  ```swift Swift v10 theme={null}
  try await client.hubs.copyHubV2025R0(hubId: createdHub.id, requestBody: HubCopyRequestV2025R0(title: copiedHubTitle, description: copiedHubDescription))
  ```

  ```java Java v10 theme={null}
  client.getHubs().copyHubV2025R0(createdHub.getId(), new HubCopyRequestV2025R0.Builder().title(copiedHubTitle).description(copiedHubDescription).build());
  ```
</CodeGroup>

Replace `HUB_ID` with the source hub ID. Request body fields are optional. If you omit the `title` parameter, the API uses a default one. A successful response returns the new <Link href="/reference/v2025.0/resources/hub">Hub</Link> object.

## Request body fields

| Field | Type | Required | Description |
| - | - | - | - |
| `title` | string | No | Title for the new hub. Maximum length is 50 characters. |
| `description` | string | No | Description for the new hub. |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create a hub
Source: https://developer.box.com/guides/hubs-api/hubs/create-hub



To create a new Box Hub, call the <Link href="/reference/v2025.0/post-hubs">`POST /2.0/hubs`</Link> endpoint with a `title` (required). You can optionally provide a `description`. The hub is created with default settings.
To customize styling and other options, you can later use the API or Box web app.

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## Create hub

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:create "HR Hub" --description "Central hub for HR policies and onboarding materials."
  ```

  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/hubs" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "title": "HR Hub",
         "description": "Central hub for HR policies and onboarding materials."
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubs.createHubV2025R0({
    title: hubTitle,
    description: hubDescription,
  } satisfies HubCreateRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.hubs.create_hub_v2025_r0("HR Hub", description="Central hub for HR policies and onboarding materials.")
  ```

  ```csharp .NET v10 theme={null}
  await client.Hubs.CreateHubV2025R0Async(requestBody: new HubCreateRequestV2025R0(title: hubTitle) { Description = hubDescription });
  ```

  ```swift Swift v10 theme={null}
  try await client.hubs.createHubV2025R0(requestBody: HubCreateRequestV2025R0(title: hubTitle, description: hubDescription))
  ```

  ```java Java v10 theme={null}
  client.getHubs().createHubV2025R0(new HubCreateRequestV2025R0.Builder(hubTitle).description(hubDescription).build());
  ```
</CodeGroup>

## Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `title` | string | Yes | Title of the hub. Must not exceed 50 characters. |
| `description` | string | No | Description of the hub. |

A successful response returns the new <Link href="/reference/v2025.0/resources/hub">Hub</Link> object. After creating the hub, you can see it in the Box Hubs web interface and manage its items and collaborations through the API.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete a hub
Source: https://developer.box.com/guides/hubs-api/hubs/delete-hub



To delete a Box Hub, call the <Link href="/reference/v2025.0/delete-hubs-id">`DELETE /2.0/hubs/{hub_id}`</Link> endpoint with the hub ID.

<Note>
  The hub and its association with content are removed. The underlying files and folders in Box are not deleted.
</Note>

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## Delete hub

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:delete 12345
  ```

  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/hubs/HUB_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubs.deleteHubByIdV2025R0(hubId);
  ```

  ```python Python v10 theme={null}
  client.hubs.delete_hub_by_id_v2025_r0(hub_id)
  ```

  ```csharp .NET v10 theme={null}
  await client.Hubs.DeleteHubByIdV2025R0Async(hubId: hubId);
  ```

  ```swift Swift v10 theme={null}
  try await client.hubs.deleteHubByIdV2025R0(hubId: hubId)
  ```

  ```java Java v10 theme={null}
  client.getHubs().deleteHubByIdV2025R0(hubId);
  ```
</CodeGroup>

Replace `HUB_ID` with the actual hub ID. A successful response has no response body (HTTP 204). The caller must have permission to delete the hub.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get a hub
Source: https://developer.box.com/guides/hubs-api/hubs/get-hub



To retrieve details for a single Box Hub, call the <Link href="/reference/v2025.0/get-hubs-id">`GET /2.0/hubs/{hub_id}`</Link> endpoint with the hub's ID. You can find the hub ID in the Box Hubs web interface URL (for example, `https://*.app.box.com/hubs/12345` has hub ID `12345`).

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## Get hub by ID

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:get 12345
  ```

  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/hubs/HUB_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubs.getHubByIdV2025R0(hubId);
  ```

  ```python Python v10 theme={null}
  client.hubs.get_hub_by_id_v2025_r0(hub_id)
  ```

  ```csharp .NET v10 theme={null}
  await client.Hubs.GetHubByIdV2025R0Async(hubId: hubId);
  ```

  ```swift Swift v10 theme={null}
  try await client.hubs.getHubByIdV2025R0(hubId: hubId)
  ```

  ```java Java v10 theme={null}
  client.getHubs().getHubByIdV2025R0(hubId);
  ```
</CodeGroup>

Replace `HUB_ID` (or `hubId` / `hub_id`) with the actual hub ID. A successful response returns the <Link href="/reference/v2025.0/resources/hub">Hub</Link> object.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# List hubs
Source: https://developer.box.com/guides/hubs-api/hubs/list-hubs



You can list Box Hubs in two ways:

* [All hubs for the requesting user](#list-hubs-for-the-requesting-user)
* [All hubs for the enterprise](#list-hubs-for-the-enterprise)

Use query parameters to search, filter by scope, and sort results.

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## List hubs for the requesting user

To retrieve all Box Hubs accessible to the authenticated user, call the <Link href="/reference/v2025.0/get-hubs">`GET /2.0/hubs`</Link> endpoint.

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs --scope all --sort name --direction ASC
  ```

  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/hubs?scope=all&sort=name&direction=ASC" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubs.getHubsV2025R0({
    scope: 'all',
    sort: 'name',
    direction: 'ASC' as GetHubsV2025R0QueryParamsDirectionField,
  } satisfies GetHubsV2025R0QueryParams);
  ```

  ```python Python v10 theme={null}
  client.hubs.get_hubs_v2025_r0(scope="all", sort="name", direction=GetHubsV2025R0Direction.ASC)
  ```

  ```csharp .NET v10 theme={null}
  await client.Hubs.GetHubsV2025R0Async(queryParams: new GetHubsV2025R0QueryParams() { Scope = "all", Sort = "name", Direction = GetHubsV2025R0QueryParamsDirectionField.Asc });
  ```

  ```swift Swift v10 theme={null}
  try await client.hubs.getHubsV2025R0(queryParams: GetHubsV2025R0QueryParams(scope: "all", sort: "name", direction: GetHubsV2025R0QueryParamsDirectionField.asc))
  ```

  ```java Java v10 theme={null}
  client.getHubs().getHubsV2025R0(new GetHubsV2025R0QueryParams.Builder().scope("all").sort("name").direction(GetHubsV2025R0QueryParamsDirectionField.ASC).build());
  ```
</CodeGroup>

### Query parameters (list hubs for user)

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | string | No | Search string for Box Hubs. |
| `scope` | string | No | `editable`, `view_only`, or `all`. Default is `all`. |
| `sort` | string | No | Sort by `name`, `updated_at`, `last_accessed_at`, `view_count`, or `relevance`. Default is `relevance`. |
| `direction` | string | No | `ASC` or `DESC`. |
| `marker` | string | No | Marker for marker-based pagination. |
| `limit` | integer | No | Maximum items per page (must not exceed 1000). |

## List hubs for the enterprise

Admins or Hub Co-admins of an enterprise with <Link href="/guides/api-calls/permissions-and-errors/scopes/#global-content-manager-gcm">Global Content Manager (GCM)</Link> scope can list all Box Hubs for the enterprise using the <Link href="/reference/v2025.0/get-enterprise-hubs">`GET /2.0/enterprise_hubs`</Link> endpoint.

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:enterprise --sort name --direction ASC
  ```

  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/enterprise_hubs?scope=all&sort=name&direction=ASC" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubs.getEnterpriseHubsV2025R0({
    scope: 'all',
    sort: 'name',
    direction: 'ASC' as GetEnterpriseHubsV2025R0QueryParamsDirectionField,
  } satisfies GetEnterpriseHubsV2025R0QueryParams);
  ```

  ```python Python v10 theme={null}
  client.hubs.get_enterprise_hubs_v2025_r0(scope="all", sort="name", direction=GetEnterpriseHubsV2025R0Direction.ASC)
  ```

  ```csharp .NET v10 theme={null}
  await client.Hubs.GetEnterpriseHubsV2025R0Async(queryParams: new GetEnterpriseHubsV2025R0QueryParams() { Scope = "all", Sort = "name", Direction = GetEnterpriseHubsV2025R0QueryParamsDirectionField.Asc });
  ```

  ```swift Swift v10 theme={null}
  try await client.hubs.getEnterpriseHubsV2025R0(queryParams: GetEnterpriseHubsV2025R0QueryParams(scope: "all", sort: "name", direction: GetEnterpriseHubsV2025R0QueryParamsDirectionField.asc))
  ```

  ```java Java v10 theme={null}
  client.getHubs().getEnterpriseHubsV2025R0(new GetEnterpriseHubsV2025R0QueryParams.Builder().scope("all").sort("name").direction(GetEnterpriseHubsV2025R0QueryParamsDirectionField.ASC).build());
  ```
</CodeGroup>

Both endpoints return a list of hubs with pagination fields (`limit`, `next_marker`). Use the API reference for full parameter descriptions and limitations.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Update a hub
Source: https://developer.box.com/guides/hubs-api/hubs/update-hub



To update an existing Box Hub, call the <Link href="/reference/v2025.0/put-hubs-id">`PUT /2.0/hubs/{hub_id}`</Link> endpoint with the hub ID and the fields you want to change. You can update the title, description, AI settings, and collaboration restrictions.

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## Update hub

<CodeGroup>
  ```sh Box CLI theme={null}
  box hubs:update 12345 --title "HR Hub" --description "Updated description for HR policies and onboarding." --ai-enabled
  ```

  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/hubs/HUB_ID" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "box-version: 2025.0" \
       -H "Content-Type: application/json" \
       -d '{
         "title": "HR Hub",
         "description": "Updated description for HR policies and onboarding.",
         "is_ai_enabled": true
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.hubs.updateHubByIdV2025R0(hubId, {
    title: newHubTitle,
    description: newHubDescription,
  } satisfies HubUpdateRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.hubs.update_hub_by_id_v2025_r0(hub_id, title=new_hub_title, description=new_hub_description)
  ```

  ```csharp .NET v10 theme={null}
  await client.Hubs.UpdateHubByIdV2025R0Async(hubId: hubId, requestBody: new HubUpdateRequestV2025R0() { Title = newHubTitle, Description = newHubDescription });
  ```

  ```swift Swift v10 theme={null}
  try await client.hubs.updateHubByIdV2025R0(hubId: hubId, requestBody: HubUpdateRequestV2025R0(title: newHubTitle, description: newHubDescription))
  ```

  ```java Java v10 theme={null}
  client.getHubs().updateHubByIdV2025R0(hubId, new HubUpdateRequestV2025R0.Builder().title(newHubTitle).description(newHubDescription).build());
  ```
</CodeGroup>

Replace `HUB_ID` with the actual hub ID. Request body fields are optional. Include only the fields you want to update.

## Request body fields

| Field | Type | Required | Description |
| - | - | - | - |
| `title` | string | No | Title of the Box Hub. Maximum length is 50 characters. |
| `description` | string | No | Description of the Box Hub. |
| `is_ai_enabled` | boolean | No | Whether AI features are enabled for the hub. |
| `is_collaboration_restricted_to_enterprise` | boolean | No | Whether collaboration is restricted to the enterprise. |

A successful response returns the updated <Link href="/reference/v2025.0/resources/hub">Hub</Link> object.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box Hubs overview
Source: https://developer.box.com/guides/hubs-api/index

Organize files and folders into Box Hubs and query curated, permission-aware content with the Hubs API and Box AI Ask.

Box Hubs provide a centralized way to organize content for specific teams, departments, or projects within your organization. They serve as content portals that bring together files, folders, and web links in a structured, easily accessible manner. Box Hubs are integrated with Box AI, allowing for more accurate responses thanks to a narrowed context window. You can ask natural language questions across a hub's content with the <Link href="/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub">Box AI Ask API</Link> by passing the hub as a `hubs` item.

The Box Hubs API lets you programmatically manage Box Hubs, their content, and collaborations. There are three groups of endpoints:

* **Box Hubs:** Create, get, list, update, delete, and copy hubs.
* **Box Hub items:** List items in a hub and add or remove files, folders, and web links.
* **Box Hub collaborations:** Create, list, get, update, and delete hub collaborations to control who can access a hub and at what level.

<Warning>Box Hubs endpoints require the `box-version: 2025.0` header. If you omit this header, the API returns a 400 error with the message `Missing required box-version header. Supported API versions: [2025.0].` For more information, see [Box API versioning strategy](/guides/api-calls/api-versioning-strategy/).</Warning>

## Enable Box Hubs

To enable Box Hubs (including the API) for your enterprise, follow the [Configuring Box Hubs](https://support.box.com/hc/en-us/articles/25822332454547-Configuring-Box-Hubs) product guide.

## Prerequisites

* A Box account with Box Hubs enabled for your enterprise.
* An access token with the appropriate [scopes](/guides/api-calls/permissions-and-errors/scopes) for the operations you need (for example, for listing enterprise hubs, [Global Content Manager (GCM)](/guides/api-calls/permissions-and-errors/scopes/#global-content-manager-gcm) for admins or Hub Co-admins).

## Tutorial

<CardGroup>
  <Card title="Turn a repository into an access-controlled AI knowledge base" icon="book" href={localizeLink("/guides/hubs-api/access-controlled-knowledge-base")}>
    Curate an enterprise document repository into a Box Hub and query it with Box AI Ask. Answers inherit Box permissions.
  </Card>

  <Card title="Build a sales RFP answer bank with Box Hubs and AI" icon="magnifying-glass" href={localizeLink("/tutorials/sales-rfp-answer-bank")}>
    End-to-end walkthrough: provision a Sales Hub, populate it with approved content, embed it in a CRM, and query it with Box AI.
  </Card>
</CardGroup>

## Next steps

* [Create a hub](/guides/hubs-api/hubs/create-hub) — Create a new Box Hub through the API.
* [Get a hub](/guides/hubs-api/hubs/get-hub) — Retrieve a hub by ID.
* [List hubs](/guides/hubs-api/hubs/list-hubs) — List hubs for a user or for the enterprise.
* [Update a hub](/guides/hubs-api/hubs/update-hub) — Change a hub's title, description, or settings.
* [Delete a hub](/guides/hubs-api/hubs/delete-hub) — Delete a single hub.
* [Copy a hub](/guides/hubs-api/hubs/copy-hub) — Create a copy of an existing hub.
* [Manage hub items](/guides/hubs-api/hubs-items/hub-items) — List, add, and remove items in a hub.
* [Manage hub collaborations](/guides/hubs-api/hubs-collaborations/hub-collaborations) — Invite users or groups and manage their access to a hub.


# Hubs APIs use cases
Source: https://developer.box.com/guides/hubs-api/use-cases

Use the Box Hubs API to automate content portals, inherit source-file permissions, and query curated knowledge with Box AI.

Managing content portals at scale can be challenging due to the need for manual curation, complex permission management, and inconsistent user experiences across teams.

The Box Hubs API provides the programmatic control for automating the creation, management, and governance of content portals. It handles the complexity—orchestration, security inheritance, and content indexing, so you can build scalable knowledge bases and embed them directly into your applications.

The Box Hubs API empowers developers to:

* **Scale faster:** Automate Hub creation and management using APIs to replace tedious manual configuration with event-driven workflows.
* **Minimize maintenance:** Programmatically inherit Box's enterprise-grade governance, ensuring sensitive data stays protected without building custom security frameworks.
* **Reduce complexity:** Seamlessly embed AI-powered content portals into existing internal portals or third-party tools instead of building custom interfaces from scratch.

<AccordionGroup>
  <Accordion title="Industry-Specific Solutions">
    Leverage the Hubs API to build tailored solutions for specific vertical needs.

    <AccordionGroup>
      <Accordion title="Financial Services">
        * **Client Portals:** Programmatically generate secure portals for high-net-worth clients to access their specific tax documents, contract updates, and market trend reports.
        * **Deal Rooms:** Automatically spin up "Deal Hubs" for M\&A activities, populating them with necessary due diligence documents while strictly controlling external access permissions.
      </Accordion>

      <Accordion title="Life Sciences">
        * **Clinical Trial Portals:** Create standardized hubs for each trial site to centralize protocols, investigator brochures, and patient enrollment forms.
        * **SOP Guidelines:** Maintain a single source of truth Hub for Standard Operating Procedures that automatically updates when the underlying files in Box are modified.
      </Accordion>

      <Accordion title="Public Sector">
        * **Citizen Information Portals:** Build public-facing or inter-agency hubs for grant documentation, policy procurement, and court judgments.
        * **Case Management:** Automate the creation of hubs for specific legal cases or public records requests, gathering all relevant files into one navigable view for review.
      </Accordion>

      <Accordion title="Retail">
        * **Store Operations:** Distinct hubs for every franchise location containing the latest merchandising guidelines, campaign assets, and safety policies.
        * **Franchisee Resources:** Automate the distribution of new season playbooks to thousands of partner portals simultaneously.
      </Accordion>
    </AccordionGroup>
  </Accordion>

  <Accordion title="Line of Business Solutions">
    Streamline knowledge sharing across departments by integrating Hubs into your end users' daily workflows.

    <AccordionGroup>
      <Accordion title="Sales">
        * **Sales Enablement:** Embed a "Sales Hub" into your CRM that surfaces the latest pitch decks, competitive intelligence, and pricing sheets so reps can close deals faster.
        * **Request for Proposal (RFP) Libraries:** Create a curated RFP library where teams can use Box AI to instantly find answers to technical questions from past proposals.
      </Accordion>

      <Accordion title="HR / People Ops">
        * **Onboarding Portals:** Automatically generate a personalized "Welcome Hub" for new hires containing their specific benefits info, handbook, and training videos triggered by their start date in the Human Resource Information System (HRIS).
        * **Employee Resources:** Surface training and benefit resources to employees across the globe in a centralized, easily navigable Hub.
      </Accordion>

      <Accordion title="Marketing">
        * **Brand Asset Libraries:** Create a central, read-only Hub for external agencies to access approved logos and campaign assets without giving them access to the raw working files.
        * **Campaign Management:** Find, repurpose, and align on campaigns faster with AI-powered insights and a centralized project Hub.
      </Accordion>

      <Accordion title="Legal">
        * **Contract Repositories:** Build a "Legal Hub" that aggregates approved contract templates and policy libraries, allowing users to ask questions against the content using Box AI.
        * **Compliance Portals:** Effortlessly manage and organize compliance documentation to ensure teams have access to the latest regulations.
      </Accordion>

      <Accordion title="Operations">
        * **Standard Operating Procedure (SOP) Libraries:** Streamline and manage content for standardized procedures and documentation, ensuring operational consistency across teams.
        * **Product Documentation:** Create self-serve product knowledge hubs that reduce the burden on subject matter experts to answer repetitive questions.
      </Accordion>

      <Accordion title="IT">
        * **Service Desk Hubs:** Reduce ticket volume by providing a self-service IT documentation and policy hub where users can find their own answers.
        * **Security Policies:** Distribute up-to-date security and access policies through a governed portal that ensures version control.
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

## Try it yourself

<Card title="Tutorial: Build a sales RFP answer bank with Box Hubs and AI" icon="magnifying-glass" href={localizeLink("/tutorials/sales-rfp-answer-bank")}>
  Follow a step-by-step walkthrough that provisions a Sales Hub, populates it with curated content, embeds it in a CRM, and lets reps query past proposals using Box AI.
</Card>

## Core Benefits of using the Box Hubs API

* **Security & Compliance:** All content within a Hub inherits the permissions of the underlying source files. The Hubs API respects Box's enterprise-grade security framework, eliminating the need for developers to build custom authentication or encryption layers.
* **AI-Ready Infrastructure:** Hubs are pre-indexed for Box AI. By using the Hubs API, you are tapping into your company's knowledge base, without the complexity of building and maintaining custom RAG systems or storing content in a vector database. Query a hub's content directly with the [Box AI Ask API](/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub) by passing the hub as a `hubs` item.
* **Model-Neutral Flexibility:** Box AI in Hubs allows you to leverage the latest, most powerful LLMs to query your curated content without being locked into a single AI provider.

## Next steps

Get started with the Box Hubs API with the following developer guides:

<RelatedLinks title="RELATED APIS" />


# Create a metadata cascade policy
Source: https://developer.box.com/guides/metadata/cascades/create



When a metadata template has been applied to a folder, a metadata cascade policy
can be created by calling the <Link href="/reference/post-metadata-cascade-policies">`POST /metadata_cascade_policies`</Link> API
endpoint with the `folder_id` of the folder to apply the policy to, and the
`scope` and `templateKey` of metadata template to.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/metadata_cascade_policies" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "folder_id": "12321",
         "scope": "enterprise_27335",
         "templateKey": "productInfo"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataCascadePolicies.createMetadataCascadePolicy({
    folderId: folder.id,
    scope: 'enterprise' as CreateMetadataCascadePolicyRequestBodyScopeField,
    templateKey: templateKey,
  } satisfies CreateMetadataCascadePolicyRequestBody);
  ```

  ```python Python v10 theme={null}
  client.metadata_cascade_policies.create_metadata_cascade_policy(
      folder.id, CreateMetadataCascadePolicyScope.ENTERPRISE, template_key
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataCascadePolicies.CreateMetadataCascadePolicyAsync(requestBody: new CreateMetadataCascadePolicyRequestBody(folderId: folder.Id, scope: CreateMetadataCascadePolicyRequestBodyScopeField.Enterprise, templateKey: templateKey));
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataCascadePolicies.createMetadataCascadePolicy(requestBody: CreateMetadataCascadePolicyRequestBody(folderId: folder.id, scope: CreateMetadataCascadePolicyRequestBodyScopeField.enterprise, templateKey: templateKey))
  ```

  ```java Java v10 theme={null}
  client.getMetadataCascadePolicies().createMetadataCascadePolicy(new CreateMetadataCascadePolicyRequestBody(folder.getId(), CreateMetadataCascadePolicyRequestBodyScopeField.ENTERPRISE, templateKey))
  ```

  ```py Python v4 theme={null}
  folder = client.folder(folder_id='22222')
  metadata_template = client.metadata_template('enterprise', 'securityClassiciation')

  cascade_policy = folder.cascade_metadata(metadata_template)
  print(f'Folder {cascade_policy.parent.id} has a metadata cascade policy for {cascade_policy.scope} template "{cascade_policy.templateKey}"')
  ```

  ```csharp .NET v6 theme={null}
  BoxMetadataCascadePolicy metadataCascadePolicy = await client.MetadataCascadePolicyManager
      .CreateCascadePolicyAsync("22222", "enterprise_11111", "templateKey");
  ```

  ```js Node v4 theme={null}
  var folderID = '22222';
  client.metadata.createCascadePolicy('enterprise', 'testTemplate', folderID)
   .then(cascadePolicy => {
    /* cascadePolicy -> {
     id: '84113349-794d-445c-b93c-d8481b223434',
     type: 'metadata_cascade_policy',
     owner_enterprise: {
      type: 'enterprise',
      id: '11111'
     },
     parent: {
      type: 'folder',
      id: '22222'
     },
     scope: 'enterprise_11111',
     templateKey: 'testTemplate'
    }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `scope` and `templateKey` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link>, or
  <Link href="/guides/metadata/instances/list">list all instances on a file</Link>.
</Info>

<Warning>
  A cascade policy can only be created if a metadata instance has already been
  applied to the folder with the given `scope` and `templateKey`.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete a metadata cascade policy
Source: https://developer.box.com/guides/metadata/cascades/delete



A metadata cascade policy can be deleted by calling the
<Link href="/reference/delete-metadata-cascade-policies-id">`DELETE /metadata_cascade_policies/:id`</Link> API endpoint with the
`id` of the policy to remove.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/metadata_cascade_policies/324324" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataCascadePolicies.deleteMetadataCascadePolicyById(
    cascadePolicyId,
  );
  ```

  ```python Python v10 theme={null}
  client.metadata_cascade_policies.delete_metadata_cascade_policy_by_id(cascade_policy_id)
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataCascadePolicies.DeleteMetadataCascadePolicyByIdAsync(metadataCascadePolicyId: cascadePolicyId);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataCascadePolicies.deleteMetadataCascadePolicyById(metadataCascadePolicyId: cascadePolicyId)
  ```

  ```java Java v10 theme={null}
  client.getMetadataCascadePolicies().deleteMetadataCascadePolicyById(cascadePolicyId)
  ```

  ```java Java v5 theme={null}
  String cascadePolicyID = "e4392a41-7de5-4232-bdf7-15e0d6bba067";
  BoxMetadataCascadePolicy policyToDelete = new BoxMetadataCascadePolicy(api, cascadePolicyID);
  policyToDelete.delete();
  ```

  ```py Python v4 theme={null}
  client.metadata_cascade_policy(policy_id='84113349-794d-445c-b93c-d8481b223434').delete()
  print('Cascade policy successfully removed')
  ```

  ```js Node v4 theme={null}
  var policyID = '84113349-794d-445c-b93c-d8481b223434';
  client.metadata.deleteCascadePolicy(policyID)
   .then(() => {
    // deletion succeeded — no value returned
   });
  ```
</CodeGroup>

<Info>
  To get the `id` of the policy,
  <Link href="/guides/metadata/cascades/list">list all policies</Link> for the folder.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Force-apply metadata to all items in a folder
Source: https://developer.box.com/guides/metadata/cascades/force-apply



When a metadata cascade policy already exists on a folder, the metadata instance
can be force-applied to all items in a folder by calling the
<Link href="/reference/post-metadata-cascade-policies-id-apply">`POST /metadata_cascade_policies/:id/apply`</Link> API endpoint with the
`id` of the metadata cascade policy.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/metadata_cascade_policies/21312/apply" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "conflict_resolution": "overwrite"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataCascadePolicies.applyMetadataCascadePolicy(
    cascadePolicyId,
    {
      conflictResolution:
        'overwrite' as ApplyMetadataCascadePolicyRequestBodyConflictResolutionField,
    } satisfies ApplyMetadataCascadePolicyRequestBody,
  );
  ```

  ```python Python v10 theme={null}
  client.metadata_cascade_policies.apply_metadata_cascade_policy(
      cascade_policy_id, ApplyMetadataCascadePolicyConflictResolution.OVERWRITE
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataCascadePolicies.ApplyMetadataCascadePolicyAsync(metadataCascadePolicyId: cascadePolicyId, requestBody: new ApplyMetadataCascadePolicyRequestBody(conflictResolution: ApplyMetadataCascadePolicyRequestBodyConflictResolutionField.Overwrite));
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataCascadePolicies.applyMetadataCascadePolicy(metadataCascadePolicyId: cascadePolicyId, requestBody: ApplyMetadataCascadePolicyRequestBody(conflictResolution: ApplyMetadataCascadePolicyRequestBodyConflictResolutionField.overwrite))
  ```

  ```java Java v10 theme={null}
  client.getMetadataCascadePolicies().applyMetadataCascadePolicy(cascadePolicyId, new ApplyMetadataCascadePolicyRequestBody(ApplyMetadataCascadePolicyRequestBodyConflictResolutionField.OVERWRITE))
  ```

  ```java Java v5 theme={null}
  String cascadePolicyID = "e4392a41-7de5-4232-bdf7-15e0d6bba067";
  BoxMetadataCascadePolicy policy = new BoxMetadataCascadePolicy(api, cascadePolicyID);
  policy.forceApply("none");
  ```

  ```py Python v4 theme={null}
  from boxsdk.object.metadata_cascade_policy import CascadePolicyConflictResolution

  cascade_policy = client.metadata_cascade_policy(policy_id='84113349-794d-445c-b93c-d8481b223434')
  cascade_policy.force_apply(CascadePolicyConflictResolution.PRESERVE_EXISTING)
  print('Cascade policy was force applied!')
  ```

  ```csharp .NET v6 theme={null}
  string policyId = "11111";
  string conflictResolution = Constants.ConflictResolution.Overwrite
  BoxMetadataCascadePolicy newCascadePolicy = client.MetadataCascadePolicyManager
      .ForceApplyCascadePolicyAsync(policyId, conflictResolution);
  ```

  ```js Node v4 theme={null}
  var policyID = '84113349-794d-445c-b93c-d8481b223434';
  client.metadata.forceApplyCascadePolicy(policyID, client.metadata.cascadeResolution.PRESERVE_EXISTING)
   .then(() => {
    // application started — no value returned
   });
  ```
</CodeGroup>

<Info>
  To get the `id` of the policy,
  <Link href="/guides/metadata/cascades/list">list all policies</Link> for the folder.
</Info>

<Warning>
  The metadata cascade operation will be started off asynchronously. The API
  call will return directly with the `202 Accepted` HTTP status code before
  the cascade operation is complete. There is currently no way to check for when
  this operation is finished.
</Warning>

## Conflict resolution

An additional `conflict_resolution` parameter can be passed to this API to
define how to deal with any existing instances of the template on any of the
items in the folder.

By default, without setting any value for `conflict_resolution` this API will
preserve the existing value on any items. When the value is set to `overwrite`,
it will force-apply the value of the template attached to the cascade policy
over any existing value.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get a metadata cascade policy
Source: https://developer.box.com/guides/metadata/cascades/get



Information for a metadata cascade policy can be retrieved by calling the
<Link href="/reference/get-metadata-cascade-policies-id">`GET /metadata_cascade_policies/:id`</Link> API endpoint with the
`id` of the policy.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_cascade_policies/324324" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataCascadePolicies.getMetadataCascadePolicyById(
    cascadePolicyId,
  );
  ```

  ```python Python v10 theme={null}
  client.metadata_cascade_policies.get_metadata_cascade_policy_by_id(cascade_policy_id)
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataCascadePolicies.GetMetadataCascadePolicyByIdAsync(metadataCascadePolicyId: cascadePolicyId);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataCascadePolicies.getMetadataCascadePolicyById(metadataCascadePolicyId: cascadePolicyId)
  ```

  ```java Java v10 theme={null}
  client.getMetadataCascadePolicies().getMetadataCascadePolicyById(cascadePolicyId)
  ```

  ```java Java v5 theme={null}
  String cascadePolicyID = "1234";
  BoxMetadataCascadePolicy metadataCascadePolicy = new BoxMetadataCascadePolicy(api, cascadePolicyID);
  BoxMetadataCascadePolicy.Info metadataCascadePolicyInfo = metadataCascadePolicy.getInfo();
  ```

  ```py Python v4 theme={null}
  cascade_policy = client.metadata_cascade_policy('84113349-794d-445c-b93c-d8481b223434').get()
  print(f'Cascade policy applies to a template owned by enterprise {cascade_policy.owner_enterprise.id}')
  ```

  ```csharp .NET v6 theme={null}
  BoxMetadataCascadePolicy retrievedCascadePolicy = await client.MetadataCascadePolicyManager
      .GetCascadePolicyAsync("12345", IEnumerable<string> fields = null);
  ```

  ```js Node v4 theme={null}
  var policyID = '84113349-794d-445c-b93c-d8481b223434';
  client.metadata.getCascadePolicy(policyID)
   .then(cascadePolicy => {
    /* cascadePolicy -> {
     id: '84113349-794d-445c-b93c-d8481b223434',
     type: 'metadata_cascade_policy',
     owner_enterprise: {
      type: 'enterprise',
      id: '11111'
     },
     parent: {
      type: 'folder',
      id: '22222'
     },
     scope: 'enterprise_11111',
     templateKey: 'testTemplate'
    }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `id` of the policy,
  <Link href="/guides/metadata/cascades/list">list all policies</Link> for the folder.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Metadata cascade policies overview
Source: https://developer.box.com/guides/metadata/cascades/index



A metadata cascade policy describes how <Link href="/guides/metadata/instances">metadata
instances</Link> applied to a folder should be applied to any item
within that folder. For example, a user might assign the same `invoiceData`
metadata template to a project folder allowing it to automatically apply to all
the files and folders within that project folder.

Every policy specifies exactly one metadata template instance and one folder.

## Activation and permissions

To use metadata cascade policies, an enterprise admin needs to enable them for
the entire enterprise. In the **Admin Console**, select **Enterprise Settings**,
**Content & Sharing**, **Cascading Folder Level Metadata**. Click the **Edit
configuration** button and pick who can apply cascade policies to folders.

Any user with edit permissions on a folder and the ability to create cascade
policies can create metadata cascade policies for that given folder.

## Limitations

There is some delay from file upload to the metadata being applied. This very
much depends on the number of items in a folder. Metadata cascade operations
are performed asynchronously and there is currently no way to check when all
metadata has been cascaded to all files.


# List metadata cascade policies
Source: https://developer.box.com/guides/metadata/cascades/list



Metadata cascade policies can be listed for a folder by calling the
<Link href="/reference/get-metadata-cascade-policies">`GET /metadata_cascade_policies`</Link> API endpoint with a `folder_id`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_cascade_policies?folder_id=31232" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataCascadePolicies.getMetadataCascadePolicies({
    folderId: folder.id,
  } satisfies GetMetadataCascadePoliciesQueryParams);
  ```

  ```python Python v10 theme={null}
  client.metadata_cascade_policies.get_metadata_cascade_policies(folder.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataCascadePolicies.GetMetadataCascadePoliciesAsync(queryParams: new GetMetadataCascadePoliciesQueryParams(folderId: folder.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataCascadePolicies.getMetadataCascadePolicies(queryParams: GetMetadataCascadePoliciesQueryParams(folderId: folder.id))
  ```

  ```java Java v10 theme={null}
  client.getMetadataCascadePolicies().getMetadataCascadePolicies(new GetMetadataCascadePoliciesQueryParams(folder.getId()))
  ```

  ```java Java v5 theme={null}
  String folderID = "2222";
  BoxFolder folder = new BoxFolder(api, folderID);
  Iterable<BoxMetadataCascadePolicy.Info> metadataCascadePolicies = folder.getMetadataCascadePolicies();
  for (BoxMetadataCascadePolicy.Info policyInfo : metadataCascadePolicies) {
      // take action on policy here
  }
  ```

  ```py Python v4 theme={null}
  cascade_policies = client.folder(folder_id='22222').get_metadata_cascade_policies()
  for policy in cascade_policies:
      print(f'Metadata template {policy.templateKey} is cascaded')
  ```

  ```csharp .NET v6 theme={null}
  BoxCollectionMarkerBased<BoxMetadataCascadePolicy> metadataCascadePolicies = await client.MetadataCascadePolicyManager.GetAllMetadataCascadePoliciesAsync("12345");
  ```

  ```js Node v4 theme={null}
  var folderID = '22222';
  client.metadata.getCascadePolicies(folderID)
   .then(cascadePolicies => {
    /* cascadePolicies -> {
     limit: 100,
     entries: [
      {
       id: '84113349-794d-445c-b93c-d8481b223434',
       type: 'metadata_cascade_policy',
       owner_enterprise: {
        type: 'enterprise',
        id: '11111'
       },
       parent: {
        type: 'folder',
        id: '22222'
       },
       scope: 'enterprise_11111',
       templateKey: 'testTemplate'
      }
     ],
     next_marker: null,
     prev_marker: null
    }
    */
   });
  ```
</CodeGroup>

## Pagination

This API uses <Link href="/guides/api-calls/pagination/marker-based">marker-based pagination</Link> and can return a
`next_marker` value in the response body to indicate that more templates might
be available.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Classifications
Source: https://developer.box.com/guides/metadata/classifications



Box enables users and applications to apply a security classification label
to files, and cascade a classification label to folders and their contents.
Classifications help protect shared sensitive content from negligent access
through Box's Governance and Shield products.

The Classification API can be used to create new classification labels
and to assign classifications to files and folders.

<Frame>
  <img alt="String field" />
</Frame>

Classifications use the <Link href="/guides/metadata">Metadata APIs</Link> to create classification
labels, and to assign classifications to files and folders. For more details on
metadata templates and instances, please explore our guides
on <Link href="/guides/metadata">Metadata</Link>.

## Classifications & Metadata

Working with classifications requires a developer to work with metadata
templates and instances.

* **The Classification Template:**  to work with classifications, an enterprise needs to have a classification metadata template with at least one classification. This template needs to have a `scope`/`templateKey` of `enterprise.securityClassification-6VMVochwUWo`. This template will hold the possible classification levels, their label names, descriptions, and `colorID` values.
* **Template Instances**: to apply a classification to a file or folder, a developer applies an instance of the `enterprise.securityClassification-6VMVochwUWo` template to the item. When the template is applied, one of the classifications is selected from the list of classifications on the template.

<RelatedLinks title="RELATED APIS" />


# Date metadata field
Source: https://developer.box.com/guides/metadata/fields/date



A metadata field of type `date` is displayed to a user as a date picker.

<Frame>
  <img alt="String field" />
</Frame>

<Note>
  Although dates are presented to users in the Box Web app as date-pickers, the
  actual dates are actually stored in `RFC3339` format, with up to
  millisecond precision. The time part of the date is always set to `T00:00:00.000Z`.
</Note>

## Create a date field

A `date` field can be added to a metadata template either when <Link href="/guides/metadata/templates/create">creating a
metadata template</Link>, or when <Link href="/guides/metadata/templates/update">updating a
template</Link> with the `addField` operation.

The required attributes for a `date` field are a `type`, a `displayName`, and a
`key`.

```json theme={null}
{
  "scope": "enterprise",
  "displayName": "Contract",
  "fields": [
    {
      "type": "date",
      "key": "effective_date",
      "displayName": "Effective Date",
      "description": "The effective date when the contract goes in effect",
      "hidden": false
    }
  ]
}
```

Optionally, a `description` can be provided that is shown to a user in the UI,
and the field can be set to `hidden` to hide it from users in the web and mobile
apps.

## Update a date field

A `date` template field can be updated by <Link href="/guides/metadata/templates/update">updating the
template</Link> it belongs to. Updates to templates happen through
**operations** to ensure that any template that is already assigned to a file or
folder is updated as well.

When updating a `date` metadata field, the only relevant operation is the
`editField` operation, which can be used to change the field's `key`,
`displayName`, `description`, and `hidden` values.

```json theme={null}
[
  {
    "op": "editField",
    "fieldKey": "effective_date",
    "data": {
      "displayName": "Effective Contract Date",
      "description": "The contract's effective date",
      "key": "effective_contract_date",
      "hidden": true
    }
  }
]
```

<Warning>
  This will affect existing instances of this template.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Enum metadata field
Source: https://developer.box.com/guides/metadata/fields/enum



A metadata field of type `enum` is displayed to a user as a dropdown list. The
user can select one item from the list.

<Frame>
  <img alt="String field" />
</Frame>

<Note>
  An `enum` allows a user to select zero or a single value. To allow a user to select
  multiple values, use the <Link href="/guides/metadata/fields/multi-select">`multiSelect`</Link> template field.
</Note>

## Create an `enum` field

An `enum` field can be added to a metadata template either when <Link href="/guides/metadata/templates/create">creating a
metadata template</Link>, or when <Link href="/guides/metadata/templates/update">updating a
template</Link> with the `addField` operation.

The required attributes for an `enum` field are a `type`, a `displayName`, a
`key`, and a list of options.

```json theme={null}
{
  "scope": "enterprise",
  "displayName": "Contract",
  "fields": [
    {
      "type": "enum",
      "key": "customer_state",
      "displayName": "Customer State",
      "description": "The US state where the customer is located",
      "hidden": false,
      "options": [
        {"key": "N/A"},
        {"key": "AL"},
        {"key": "AK"}
      ]
    }
  ]
}
```

Optionally, a `description` can be provided that is shown to a user in the UI,
and the field can be set to `hidden` to hide it from users in the web and mobile
apps.

## Update an `enum` field

An `enum` template field can be updated by <Link href="/guides/metadata/templates/update">updating the
template</Link> it belongs to. Updates to templates happen through
**operations** to ensure that any template that is already assigned to a file or
folder is updated as well.

### Change basic field values

When updating an `enum` metadata field, one of the possible operations is the
`editField` operation, which can be used to change the field's `key`,
`displayName`, `description`, and `hidden` values.

```json theme={null}
[
  {
    "op": "editField",
    "fieldKey": "customer_state",
    "data": {
      "displayName": "Customer State (USA)",
      "key": "customer_state_usa"
    }
  }
]
```

<Info>
  The `fieldKey` here represents the original key of the field to change. The
  `data.key` field is the new key of the field.
</Info>

<Warning>
  This will affect existing instances of this template.
</Warning>

### Add an option

Adding an option to an `enum` field can be achieved through the
`addEnumOption` operation. The operation expects the `fieldKey` to be set to the
key of the `enum` field to change, and a `data` object with the `key` of the new
option to add.

```json theme={null}
[
  {
    "op": "addEnumOption",
    "fieldKey": "customer_state",
    "data": {
      "key": "AR"
    }
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "N/A"},
  {"key": "AL"},
  {"key": "AK"},
  {"key": "AR"}
]
...
```

<Warning>
  This will affect existing instances of this template.
</Warning>

### Reorder options

Reordering the options in an `enum` field can be achieved through the
`reorderEnumOptions` operation. The operation expects the `fieldKey` to be set
to the key of the `enum` field to change, and an `enumOptionKeys` array with the
keys of the options in order.

```json theme={null}
[
  {
    "op": "reorderEnumOptions",
    "fieldKey": "customer_state",
    "enumOptionKeys": [
      "AL",
      "AK",
      "AR",
      "N/A"
    ]
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "AL"},
  {"key": "AK"},
  {"key": "AR"},
  {"key": "N/A"}
]
...
```

<Warning>
  New options can not be added with this operation. This will affect existing
  instances of this template.
</Warning>

### Edit an option

Editing an option of an `enum` field can be achieved through the
`editEnumOption` operation. The operation expects the `fieldKey` to be set
to the key of the `enum` field to change, and an `enumOptionKey` to be set to
the key of the field option. Finally, it expects a `data` object with the new
`key` of the field option.

```json theme={null}
[
  {
    "op": "editEnumOption",
    "fieldKey": "customer_state",
    "enumOptionKey": "N/A",
    "data": {
      "key": "Outside USA"
    }
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "AL"},
  {"key": "AK"},
  {"key": "AR"},
  {"key": "Outside USA"}
]
...
```

<Warning>
  This will affect existing instances of this template.
</Warning>

### Remove an option

Removing an option from an `enum` field can be achieved through the
`removeEnumOption` operation. The operation expects the `fieldKey` to be set to the
key of the `enum` field to change, and an `enumOptionKey` to be set to the key
of the field option to remove.

```json theme={null}
[
  {
    "op": "removeEnumOption",
    "fieldKey": "customer_state",
    "enumOptionKey": "AL"
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "AK"},
  {"key": "AR"},
  {"key": "Outside USA"}
]
...
```

<Warning>
  This will affect existing instances of this template. Any fields that were set
  to this value will have the value reset to `null`.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Float metadata field
Source: https://developer.box.com/guides/metadata/fields/float



A metadata field of type `float` is displayed to a user as a standard text-field
that only accepts numeric input.

<Frame>
  <img alt="String field" />
</Frame>

## Create a float field

A `float` field can be added to a metadata template either when <Link href="/guides/metadata/templates/create">creating a
metadata template</Link>, or when <Link href="/guides/metadata/templates/update">updating a
template</Link> with the `addField` operation.

The required attributes for a `float` field are a `type`, a `displayName`, and a
`key`.

```json theme={null}
{
  "scope": "enterprise",
  "displayName": "Contract",
  "fields": [
    {
      "type": "float",
      "key": "contract_value",
      "displayName": "Contract Value",
      "description": "The contract's total value",
      "hidden": false
    }
  ]
}
```

Optionally, a `description` can be provided that is shown to a user in the UI,
and the field can be set to `hidden` to hide it from users in the web and mobile
apps.

## Update a float field

A `float` template field can be updated by <Link href="/guides/metadata/templates/update">updating the
template</Link> it belongs to. Updates to templates happen through
**operations** to ensure that any template that is already assigned to a file or
folder is updated as well.

When updating a `float` metadata field, the only relevant operation is the
`editField` operation, which can be used to change the field's `key`,
`displayName`, `description`, and `hidden` values.

```json theme={null}
[
  {
    "op": "editField",
    "fieldKey": "contract_value",
    "data": {
      "displayName": "Total Annual Contract Value",
      "description": "The contract's total anual value",
      "key": "contract_tav",
      "hidden": true
    }
  }
]
```

<Warning>
  This will affect existing instances of this template.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Metadata fields
Source: https://developer.box.com/guides/metadata/fields/index



A <Link href="/reference/resources/metadata-template/#param-fields">metadata template field</Link> describes a specific
piece of data within a metadata template. For example, the ID of an invoice
might be represented as an `id` field on an `invoiceData` template.

Every metadata template contains a list of `field` objects, and each field is of
one of the following types:

| | |
| - | - |
| <Link href="/guides/metadata/fields/string">`string`</Link> | A text field |
| <Link href="/guides/metadata/fields/float">`float`</Link> | A numeric input field |
| <Link href="/guides/metadata/fields/date">`date`</Link> | A date picker field |
| <Link href="/guides/metadata/fields/enum">`enum`</Link> | A dropdown list for selecting a single value |
| <Link href="/guides/metadata/fields/multi-select">`multiSelect`</Link> | A dropdown list for selecting multiple values |
| `taxonomy` (single select) | A taxonomy field for selecting a value from a hierarchy of categories |
| `taxonomy` (multi select) | A taxonomy field for selecting multiple values from a hierarchy of categories |
| Box item fields: `type`, `extension`, `owned_by`, `owner_enterprise_id` | Fields for representing Box items |

## Basic field types

The basic field types are a `string` for a text field, `float` for a numeric
field, and `date` for a date-time picker field.

## Lists field types

Additionally, metadata templates support two field types to represent dropdown
lists. An `enum` field represents a list of predefined items that a user can
select, while a `multiSelect` field represents a list of items where the user
can select more than one value.


# Multi Select metadata field
Source: https://developer.box.com/guides/metadata/fields/multi-select



A metadata field of type `multiSelect` is displayed to a user as a dropdown
list. The user can select multiple items from the list.

<Frame>
  <img alt="String field" />
</Frame>

<Note>
  A `multiSelect` field allows a user to select zero, one, or more values. To force
  a user to select only one value at most, use the <Link href="/guides/metadata/fields/enum">`enum`</Link> template
  field.
</Note>

## Create a `multiSelect` field

A `multiSelect` field can be added to a metadata template either when <Link href="/guides/metadata/templates/create">creating
a metadata template</Link>, or when <Link href="/guides/metadata/templates/update">updating a
template</Link> with the `addField` operation.

The required attributes for a `multiSelect` field are a `type`, a `displayName`,
a `key`, and a list of options.

```json theme={null}
{
  "scope": "enterprise",
  "displayName": "Contract",
  "fields": [
    {
      "type": "multiSelect",
      "key": "box_entity",
      "displayName": "Box Entity",
      "description": "The Box entity that this contract belongs to",
      "hidden": false,
      "options": [
        {"key": "Box, Inc"},
        {"key": "Box.com (UK) Ltd."},
        {"key": "KK Box Japan"}
      ]
    }
  ]
}
```

Optionally, a `description` can be provided that is shown to a user in the UI,
and the field can be set to `hidden` to hide it from users in the web and mobile
apps.

## Update a `multiSelect` field

A `multiSelect` template field can be updated by <Link href="/guides/metadata/templates/update">updating the
template</Link> it belongs to. Updates to templates happen through
**operations** to ensure that any template that is already assigned to a file or
folder is updated as well.

### Change basic field values

When updating a `multiSelect` metadata field, one of the possible operations is
the `editField` operation, which can be used to change the field's `key`,
`displayName`, `description`, and `hidden` values.

```json theme={null}
[
  {
    "op": "editField",
    "fieldKey": "box_entity",
    "data": {
      "displayName": "Box Entities",
      "key": "box_entities"
    }
  }
]
```

<Info>
  The `fieldKey` here represents the original key of the field to change. The
  `data.key` field is the new key of the field.
</Info>

<Warning>
  This will affect existing instances of this template.
</Warning>

### Add an option

Adding an option to a `multiSelect` field can be achieved through the
`addMultiSelectOption` operation. The operation expects the `fieldKey` to be set
to the key of the `multiSelect` field to change, and a `data` object with the
`key` of the new option to add.

```json theme={null}
[
  {
    "op": "addMultiSelectOption",
    "fieldKey": "box_entity",
    "data": {
      "key": "Box (NL) BV"
    }
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "Box, Inc"},
  {"key": "Box.com (UK) Ltd."},
  {"key": "KK Box Japan"},
  {"key": "Box (NL) BV"}
]
...
```

<Warning>
  This will affect existing instances of this template.
</Warning>

### Reorder options

Reordering the options in a `multiSelect` field can be achieved through the
`reorderMultiSelectOptions` operation. The operation expects the `fieldKey` to
be set to the key of the `multiSelect` field to change, and a
`multiSelectOptionKeys` array with the keys of the options in order.

```json theme={null}
[
  {
    "op": "reorderMultiSelectOptions",
    "fieldKey": "box_entity",
    "multiSelectOptionKeys": [
      "Box, Inc",
      "Box.com (UK) Ltd.",
      "Box (NL) BV",
      "KK Box Japan"
    ]
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "Box, Inc"},
  {"key": "Box.com (UK) Ltd."},
  {"key": "Box (NL) BV"},
  {"key": "KK Box Japan"}
]
...
```

<Warning>
  New options can not be added with this operation. This will affect existing
  instances of this template.
</Warning>

### Edit an option

Editing an option of a `multiSelect` field can be achieved through the
`editMultiSelectOption` operation. The operation expects the `fieldKey` to be
set to the key of the `multiSelect` field to change, and a
`multiSelectOptionKey` to be set to the key of the field option. Finally, it
expects a `data` object with the new `key` of the field option.

```json theme={null}
[
  {
    "op": "editMultiSelectOption",
    "fieldKey": "box_entity",
    "multiSelectOptionKey": "Box (NL) BV",
    "data": {
      "key": "Box.nl BV"
    }
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "Box, Inc"},
  {"key": "Box.com (UK) Ltd."},
  {"key": "Box.nl BV"},
  {"key": "KK Box Japan"}
]
...
```

<Warning>
  This will affect existing instances of this template.
</Warning>

### Remove an option

Removing an option from a `multiSelect` field can be achieved through the
`removeMultiSelectOption` operation. The operation expects the `fieldKey` to be set
to the key of the `multiSelect` field to change, and a `multiSelectOptionKey`
to be set to the key of the field option to remove.

```json theme={null}
[
  {
    "op": "removeMultiSelectOption",
    "fieldKey": "customer_state",
    "multiSelectOptionKey": "KK Box Japan"
  }
]
```

The list of options should now be as follows.

```json theme={null}
...
"options": [
  {"key": "Box, Inc"},
  {"key": "Box.com (UK) Ltd."},
  {"key": "Box.nl BV"}
]
...
```

<Warning>
  This will affect existing instances of this template. Any fields that were set
  to this value will have the value removed from its list of selected values.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# String metadata field
Source: https://developer.box.com/guides/metadata/fields/string



A metadata field of type `string` is displayed to a user as a standard text-field.

<Frame>
  <img alt="String field" />
</Frame>

## Create a string field

A `string` field can be added to a metadata template either when <Link href="/guides/metadata/templates/create">creating a
metadata template</Link>, or when <Link href="/guides/metadata/templates/update">updating a
template</Link> with the `addField` operation.

The required attributes for a `string` field are a `type`, a `displayName`, and a
`key`.

```json theme={null}
{
  "scope": "enterprise",
  "displayName": "Customer",
  "fields": [
    {
      "type": "string",
      "key": "name",
      "displayName": "Name",
      "description": "The customer's legal name",
      "hidden": false
    }
  ]
}
```

Optionally, a `description` can be provided that is shown to a user in the UI,
and the field can be set to `hidden` to hide it from users in the web and mobile
apps.

## Update a string field

A `string` template field can be updated by <Link href="/guides/metadata/templates/update">updating the
template</Link> it belongs to. Updates to templates happen through
**operations** to ensure that any template that is already assigned to a file or
folder is updated as well.

When updating a `string` metadata field, the only relevant operation is the
`editField` operation, which can be used to change the field's `key`,
`displayName`, `description`, and `hidden` values.

```json theme={null}
[
  {
    "op": "editField",
    "fieldKey": "name",
    "data": {
      "displayName": "Customer Name",
      "description": "The contact name at the customer",
      "key": "customer_name",
      "hidden": true
    }
  }
]
```

<Warning>
  This will affect existing instances of this template.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Metadata
Source: https://developer.box.com/guides/metadata/index

Define and store custom key-value data on files and folders using metadata templates, instances, cascade policies, and queries.

Metadata allows users and applications to define and store custom data
associated with files and folders.

<Frame>
  <img alt="String field" />
</Frame>

Metadata consists of key/value pairs that are assigned to a file or a folder.
For example, an important contract may have the key/value pairs of
`clientNumber: 820183` and `clientName: bioMedicalCorp`.

## Metadata terminology

Working with metadata requires a developer to work with a few
distinct types of resources.

* **Templates:**  A <Link href="/guides/metadata/templates">metadata template</Link> describes a re-usable set of key/value pairs that can be assigned to a file. For example, an `invoiceData` template might hold data about an invoice, having a field for the invoice ID as well as the customer ID.
* **Fields:**  A <Link href="/guides/metadata/fields">metadata template field</Link> describes a specific piece of data within a metadata template. For example, the ID of an invoice might be represented as an `id` field on an `invoiceData` template.
* **Instances:** A <Link href="/guides/metadata/instances">metadata instance</Link> describes the relation between a template and a file or folder, including the values that are assigned for every field. For example, a user might have assigned an `invoiceData` metadata template to a file and provided 2 values, one for the invoice ID and one for the customer ID. You can assign up to 100 templates to a specific file or folder.
* **Cascade Policies**: A <Link href="/guides/metadata/cascades">metadata cascade policy</Link> describes how metadata instances applied to a folder should be applied to any item within that folder. For example, a user might assign the same `invoiceData` metadata template to a project folder (including the 2 values), allowing them to automatically apply to all the files and folders within that project folder.
* **Queries:** A <Link href="/guides/metadata/queries">metadata query</Link> provides a way to find files and folders by searching for the metadata attached to them. For example, to find all the files for an invoice with a certain ID, the query would look for all files and folders with the `invoiceData` template attached to it and a value of `id = :id`, where `:id` would be the value of the invoice.

## The purpose of metadata

Metadata can be used for many purposes. Enterprises may want to have a better
way to organize their digital assets for their marketing teams, or developers
may want to provide advanced content functionality such as facilitating
workflows or approvals.

For example, a `marketingCollateral` template may define where and when specific
marketing content should be used. Users can see a representation of the
template in the Box web application while navigating to a file preview.

## Quick example

Retrieve all metadata instances applied to a file:

```bash theme={null}
curl https://api.box.com/2.0/files/FILE_ID/metadata \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

To learn more, please visit [Box community articles][community].

[community]: https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata


# Apply metadata to an item
Source: https://developer.box.com/guides/metadata/instances/create



<RelatedLinks title="REQUIRED GUIDES" />

A metadata template can be applied to a file or folder using the item's `id`,
the template's `templateKey` and `scope`, and a set of values for each field in
the template.

<Note>
  The API identifies templates by `templateKey` and fields by `key`, not by the
  display names shown in the Box web app. For example, a template displayed as
  **Product Info** can have the `templateKey` `productInfo`. To find these
  values, <Link href="/reference/get-metadata-templates-enterprise">list all metadata templates for your enterprise</Link>.
</Note>

<Info>
  Metadata <Link href="/guides/metadata/scopes">scopes</Link> can be either `global` for templates available to
  all enterprises, `enterprise` for templates available to the current
  enterprise, or the `enterprise_:id` for templates belonging to an enterprise
  whose ID is the `:id` value in the scope name.
</Info>

<Warning>
  You can assign up to 100 templates to a specific file or folder.
</Warning>

## Apply metadata to a file

To apply an instance of a metadata template to a file, call the
<Link href="/reference/post-files-id-metadata-id-id">`POST /files/:file_id/metadata/:scope/:templateKey`</Link> API endpoint
with the file's `file_id`, the template's `scope` and `templateKey`, and an
optional set of values for each <Link href="/guides/metadata/fields">field</Link> in the template.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "audience": "internal",
         "documentType": "Q1 plans",
         "competitiveDocument": "no",
         "status": "active",
         "author": "Jones",
         "currentState": "proposal"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileMetadata.createFileMetadataById(
    file.id,
    'enterprise' as CreateFileMetadataByIdScope,
    templateKey,
    {
      ['name']: 'John',
      ['age']: 23,
      ['birthDate']: '2001-01-03T02:20:50.520Z',
      ['countryCode']: 'US',
      ['sports']: ['basketball', 'tennis'],
    },
  );
  ```

  ```python Python v10 theme={null}
  client.file_metadata.create_file_metadata_by_id(
      file.id,
      CreateFileMetadataByIdScope.ENTERPRISE,
      template_key,
      {
          "name": "John",
          "age": 23,
          "birthDate": "2001-01-03T02:20:50.520Z",
          "countryCode": "US",
          "sports": ["basketball", "tennis"],
      },
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FileMetadata.CreateFileMetadataByIdAsync(fileId: file.Id, scope: CreateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } });
  ```

  ```swift Swift v10 theme={null}
  try await client.fileMetadata.createFileMetadataById(fileId: file.id, scope: CreateFileMetadataByIdScope.global, templateKey: "properties", requestBody: ["abc": "xyz"])
  ```

  ```java Java v10 theme={null}
  client.getFileMetadata().createFileMetadataById(file.getId(), CreateFileMetadataByIdScope.ENTERPRISE, templateKey, mapOf(entryOf("name", "John"), entryOf("age", 23), entryOf("birthDate", "2001-01-03T02:20:50.520Z"), entryOf("countryCode", "US"), entryOf("sports", Arrays.asList("basketball", "tennis"))))
  ```

  ```java Java v5 theme={null}
  // Add property "foo" with value "bar" to the default metadata properties
  BoxFile file = new BoxFile(api, "id");
  file.createMetadata(new Metadata().add("/foo", "bar"));
  ```

  ```py Python v4 theme={null}
  metadata = {
      'foo': 'bar',
      'baz': 'quux',
  }

  applied_metadata = client.file(file_id='11111').metadata().create(metadata)
  print(f'Applied metadata in instance ID {applied_metadata["$id"]}')
  ```

  ```csharp .NET v6 theme={null}
  var metadataValues = new Dictionary<string, object>()
  {
      { "audience", "internal" },
      { "documentType", "Q1 plans" },
      { "competitiveDocument", "no" },
      { "status", "active" },
      { "author": "M. Jones" },
      { "currentState": "proposal" }
  };
  Dictionary<string, object> metadata = await client.MetadataManager
      .CreateFileMetadataAsync(fileId: "11111", metadataValues, "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  var metadataValues = {
   audience: "internal",
   documentType: "Q1 plans",
   competitiveDocument: "no",
   status: "active",
   author: "Jones",
   currentState: "proposal"
  };
  client.files.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues)
   .then(metadata => {
    /* metadata -> {
     audience: 'internal',
     documentType: 'Q1 plans',
     competitiveDocument: 'no',
     status: 'active',
     author: 'Jones',
     currentState: 'proposal',
     '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
     '$parent': 'file_11111',
     '$id': '2094c584-68e1-475c-a581-534a4609594e',
     '$version': 0,
     '$typeVersion': 0,
     '$template': 'marketingCollateral',
     '$scope': 'enterprise_12345' }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `scope` and `templateKey` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link>, or
  <Link href="/guides/metadata/instances/list">list all instances on a file</Link>.
</Info>

<Warning>
  ## Tuple already exists error

  When there is already metadata applied to this file for the given metadata
  template, an error is returned with the error code `tuple_already_exists`. In
  this case, the instance needs to be [updated
  instead](/guides/metadata/instances/update).
</Warning>

## Apply metadata to a folder

To apply an instance of a metadata template to a folder, call the
<Link href="/reference/post-folders-id-metadata-id-id">`POST /folders/:folder_id/metadata/:scope/:templateKey`</Link> API endpoint
with the folder's `folder_id`, the template's `scope` and `templateKey`, and an
optional set of values for each <Link href="/guides/metadata/fields">field</Link> in the template.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "audience": "internal",
         "documentType": "Q1 plans",
         "competitiveDocument": "no",
         "status": "active",
         "author": "Jones",
         "currentState": "proposal"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderMetadata.createFolderMetadataById(
    folder.id,
    'enterprise' as CreateFolderMetadataByIdScope,
    templateKey,
    {
      ['name']: 'John',
      ['age']: 23,
      ['birthDate']: '2001-01-03T02:20:50.520Z',
      ['countryCode']: 'US',
      ['sports']: ['basketball', 'tennis'],
    },
  );
  ```

  ```python Python v10 theme={null}
  client.folder_metadata.create_folder_metadata_by_id(
      folder.id,
      CreateFolderMetadataByIdScope.ENTERPRISE,
      template_key,
      {
          "name": "John",
          "age": 23,
          "birthDate": "2001-01-03T02:20:50.520Z",
          "countryCode": "US",
          "sports": ["basketball", "tennis"],
      },
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FolderMetadata.CreateFolderMetadataByIdAsync(folderId: folder.Id, scope: CreateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: new Dictionary<string, object>() { { "name", "John" }, { "age", 23 }, { "birthDate", "2001-01-03T02:20:50.520Z" }, { "countryCode", "US" }, { "sports", Array.AsReadOnly(new [] {"basketball","tennis"}) } });
  ```

  ```swift Swift v10 theme={null}
  try await client.folderMetadata.createFolderMetadataById(folderId: folder.id, scope: CreateFolderMetadataByIdScope.global, templateKey: "properties", requestBody: ["abc": "xyz"])
  ```

  ```java Java v10 theme={null}
  client.getFolderMetadata().createFolderMetadataById(folder.getId(), CreateFolderMetadataByIdScope.ENTERPRISE, templateKey, mapOf(entryOf("name", "John"), entryOf("age", 23), entryOf("birthDate", "2001-01-03T02:20:50.520Z"), entryOf("countryCode", "US"), entryOf("sports", Arrays.asList("basketball", "tennis"))))
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, "id");
  folder.createMetadata(new Metadata().add("/foo", "bar"));
  ```

  ```py Python v4 theme={null}
  metadata = {
      'foo': 'bar',
      'baz': 'quux',
  }

  applied_metadata = client.folder(folder_id='22222').metadata().create(metadata)
  print(f'Applied metadata in instance ID {applied_metadata["$id"]}')
  ```

  ```csharp .NET v6 theme={null}
  var metadataValues = new Dictionary<string, object>()
  {
      { "audience", "internal" },
      { "documentType", "Q1 plans" },
      { "competitiveDocument", "no" },
      { "status", "active" },
      { "author": "M. Jones" },
      { "currentState": "proposal" }
  };
  Dictionary<string, object> metadata = await client.MetadataManager
      .CreateFolderMetadataAsync(folderId: "11111", metadataValues, "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  var metadataValues = {
   audience: "internal",
   documentType: "Q1 plans",
   competitiveDocument: "no",
   status: "active",
   author: "Jones",
   currentState: "proposal"
  };
  client.folders.addMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", metadataValues)
   .then(metadata => {
    /* metadata -> {
     audience: 'internal',
     documentType: 'Q1 plans',
     competitiveDocument: 'no',
     status: 'active',
     author: 'Jones',
     currentState: 'proposal',
     '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
     '$parent': 'folder_11111',
     '$id': '2094c584-68e1-475c-a581-534a4609594e',
     '$version': 0,
     '$typeVersion': 0,
     '$template': 'marketingCollateral',
     '$scope': 'enterprise_12345' }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `scope` and `templateKey` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link>, or
  <Link href="/guides/metadata/instances/list">list all instances on a folder</Link>.
</Info>

<Warning>
  **Tuple already exists error**

  When there is already metadata applied to this folder for the given metadata
  template, an error is returned with the error code `tuple_already_exists`. In
  this case, the instance needs to be [updated
  instead](/guides/metadata/instances/update).
</Warning>

## Request body

The body of the request can contain a value for each <Link href="/guides/metadata/fields">field</Link> in the
template. To inspect what fields are present on a template, <Link href="/guides/metadata/templates/get">inspect a
metadata template</Link>.

For example, let's assume the following template.

```json theme={null}
{
  "id": "8120731a-41e4-11ea-b77f-2e728ce88125",
  "type": "metadata_template",
  "templateKey": "productInfo",
  "scope": "enterprise_1234567",
  "displayName": "Product Info",
  "hidden": false,
  "copyInstanceOnItemCopy": true,
  "fields": [
    {
      "id": "feed71de-41e5-11ea-b77f-2e728ce88125",
      "type": "string",
      "key": "name",
      "displayName": "Name",
      "hidden": false
    },
    {
      "id": "02b36bb6-41e6-11ea-b77f-2e728ce88125",
      "type": "enum",
      "key": "category",
      "displayName": "Category",
      "hidden": false,
      "options": [
        {
          "id": "06a7bcc2-41e6-11ea-b77f-2e728ce88125",
          "key": "SUVs"
        },
        {
          "id": "0a50df02-41e6-11ea-b77f-2e728ce88125",
          "key": "Saloons"
        },
        {
          "id": "0e466be0-41e6-11ea-b77f-2e728ce88125",
          "key": "Cabriolets"
        }
      ]
    }
  ]
}
```

This template has 2 <Link href="/guides/metadata/fields">template fields</Link>, `name` and `category`. The `name`
field is a regular text field, and the `category` is an enum.

The request body to assign this template to a file or folder can include a value
for any of the fields on the template. It is possible for the body to have no
values for no fields.

In this case, a valid example would be the following request body.

```json theme={null}
{
  "name": "Model 3",
  "category": "SUVs"
}
```

<Note>
  One exception is a `global` scoped template with the key `properties` that can
  be used to assign any data to a template. Using this template, any set of
  key/value pairs can be assigned to a template.
</Note>

<Warning>
  The `category` field in this example is an `enum` field and needs to be one of
  the available options on the field.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Remove metadata from an item
Source: https://developer.box.com/guides/metadata/instances/delete



<RelatedLinks title="REQUIRED GUIDES" />

To remove an instance of a metadata template assigned to a file or
folder, use the item's `id`, and the template's `templateKey`
and `scope`.

<Info>
  Metadata <Link href="/guides/metadata/scopes">scopes</Link> can be either `global` for templates available to
  all enterprises, `enterprise` for templates available to the current
  enterprise, or the `enterprise_:id` for templates belonging to an enterprise
  whose ID is the `:id` value in the scope name.
</Info>

## Remove metadata from a file

To delete an instance of a metadata template from a file, call
the <Link href="/reference/delete-files-id-metadata-id-id">`DELETE /files/:file_id/metadata/:templateKey/schema`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileMetadata.deleteFileMetadataById(
    file.id,
    'enterprise' as DeleteFileMetadataByIdScope,
    templateKey,
  );
  ```

  ```python Python v10 theme={null}
  client.file_metadata.delete_file_metadata_by_id(
      file.id, DeleteFileMetadataByIdScope.ENTERPRISE, template_key
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FileMetadata.DeleteFileMetadataByIdAsync(fileId: file.Id, scope: DeleteFileMetadataByIdScope.Enterprise, templateKey: templateKey);
  ```

  ```swift Swift v10 theme={null}
  try await client.fileMetadata.deleteFileMetadataById(fileId: file.id, scope: DeleteFileMetadataByIdScope.global, templateKey: "properties")
  ```

  ```java Java v10 theme={null}
  client.getFileMetadata().deleteFileMetadataById(file.getId(), DeleteFileMetadataByIdScope.ENTERPRISE, templateKey)
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  file.deleteMetadata("myMetadataTemplate");
  ```

  ```py Python v4 theme={null}
  client.file(file_id='11111').metadata(scope='enterprise', template='myMetadata').delete()
  ```

  ```csharp .NET v6 theme={null}
  await client.MetadataManager.DeleteFileMetadataAsync("11111", "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  client.files.deleteMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES)
   .then(() => {
    // removal succeeded — no value returned
   });;
  ```
</CodeGroup>

This API returns a `204 No Content` API response with no response body when
the instance has been successfully removed from the file.

## Remove metadata from a folder

To delete an instance of a metadata template, call
the <Link href="/reference/delete-folders-id-metadata-id-id">`DELETE /folders/:folder_id/metadata/:templateKey/schema`</Link>
API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderMetadata.deleteFolderMetadataById(
    folder.id,
    'enterprise' as DeleteFolderMetadataByIdScope,
    templateKey,
  );
  ```

  ```python Python v10 theme={null}
  client.folder_metadata.delete_folder_metadata_by_id(
      folder.id, DeleteFolderMetadataByIdScope.ENTERPRISE, template_key
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FolderMetadata.DeleteFolderMetadataByIdAsync(folderId: folder.Id, scope: DeleteFolderMetadataByIdScope.Enterprise, templateKey: templateKey);
  ```

  ```swift Swift v10 theme={null}
  try await client.folderMetadata.deleteFolderMetadataById(folderId: folder.id, scope: DeleteFolderMetadataByIdScope.global, templateKey: "properties")
  ```

  ```java Java v10 theme={null}
  client.getFolderMetadata().deleteFolderMetadataById(folder.getId(), DeleteFolderMetadataByIdScope.ENTERPRISE, templateKey)
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, "id");
  folder.deleteMetadata("myMetadataTemplate");
  ```

  ```py Python v4 theme={null}
  client.folder(folder_id='11111').metadata(scope='enterprise', template='myMetadata').delete()
  ```

  ```csharp .NET v6 theme={null}
  await client.MetadataManager.DeleteFolderMetadataAsync("11111", "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  client.folders.deleteMetadata('67890', client.metadata.scopes.GLOBAL, client.metadata.templates.PROPERTIES)
   .then(() => {
    // removal succeeded — no value returned
   });
  ```
</CodeGroup>

This API returns a `204 No Content` API response with no response body when
the instance has been successfully removed from the folder.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Get metadata on item
Source: https://developer.box.com/guides/metadata/instances/get



Information about an instance of a metadata template assigned to a file or
folder can be retrieved using the item's `id`, and the template's `templateKey`
and `scope`.

<Info>
  Metadata <Link href="/guides/metadata/scopes">scopes</Link> can be either `global` for templates available to
  all enterprises, `enterprise` for templates available to the current
  enterprise, or the `enterprise_:id` for templates belonging to an enterprise
  whose ID is the `:id` value in the scope name.
</Info>

## Get metadata instance on file

To get an instance of a metadata template on a file, call the
<Link href="/reference/get-files-id-metadata-id-id">`GET /files/:file_id/metadata/:scope/:templateKey`</Link> API endpoint
with the file's `file_id` and the template's `scope` and `templateKey`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileMetadata.getFileMetadataById(
    file.id,
    'global' as GetFileMetadataByIdScope,
    'properties',
  );
  ```

  ```python Python v10 theme={null}
  client.file_metadata.get_file_metadata_by_id(
      file.id, GetFileMetadataByIdScope.GLOBAL, "properties"
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FileMetadata.GetFileMetadataByIdAsync(fileId: file.Id, scope: GetFileMetadataByIdScope.Global, templateKey: "properties");
  ```

  ```swift Swift v10 theme={null}
  try await client.fileMetadata.getFileMetadataById(fileId: file.id, scope: GetFileMetadataByIdScope.global, templateKey: "properties")
  ```

  ```java Java v10 theme={null}
  client.getFileMetadata().getFileMetadataById(file.getId(), GetFileMetadataByIdScope.GLOBAL, "properties")
  ```

  ```java Java v5 theme={null}
  // Get the default free-form metadata properties
  BoxFile file = new BoxFile(api, "id");
  Metadata metadata = file.getMetadata();

  // Unknown type metadata field, you can test for type or try to get as any type
  JsonValue unknownValue = metadata.getValue("/someField");

  // String or Enum metadata fields
  String stringValue = metadata.getString("/author");

  // Float metadata fields can be interpreted as any numeric type
  float floatValue = metadata.getFloat("/price");

  // Date metadata fields
  Date dateValue = metadata.getDate("/deadline");

  // Multiselect metadata fields
  List<String> multiSelectValues = metadata.getMultiSelect("/categories");
  ```

  ```py Python v4 theme={null}
  metadata = client.file(file_id='11111').metadata(scope='enterprise', template='myMetadata').get()
  print(f'Got metadata instance {metadata["$id"]}')
  ```

  ```csharp .NET v6 theme={null}
  Dictionary<string, object> metadata = await client.MetadataManager.
      .GetFileMetadataAsync(fileId: "11111", "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  client.files.getMetadata('11111', client.metadata.scopes.ENTERPRISE, 'marketingCollateral')
   .then(metadata => {
    /* metadata -> {
     audience: 'internal',
     documentType: 'Q1 plans',
     competitiveDocument: 'no',
     status: 'active',
     author: 'Jones',
     currentState: 'proposal',
     '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
     '$parent': 'file_11111',
     '$id': '2094c584-68e1-475c-a581-534a4609594e',
     '$version': 0,
     '$typeVersion': 0,
     '$template': 'marketingCollateral',
     '$scope': 'enterprise_12345' }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `scope` and `templateKey` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link>, or
  <Link href="/guides/metadata/instances/list">list all instances on a file</Link>.
</Info>

## Get metadata instance on folder

To get an instance of a metadata template on a folder, call the
<Link href="/reference/get-files-id-metadata-id-id">`GET /folders/:folder_id/metadata/:scope/:templateKey`</Link> API endpoint
with the folder's `folder_id` and the template's `scope` and `templateKey`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderMetadata.getFolderMetadataById(
    folder.id,
    'global' as GetFolderMetadataByIdScope,
    'properties',
  );
  ```

  ```python Python v10 theme={null}
  client.folder_metadata.get_folder_metadata_by_id(
      folder.id, GetFolderMetadataByIdScope.GLOBAL, "properties"
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FolderMetadata.GetFolderMetadataByIdAsync(folderId: folder.Id, scope: GetFolderMetadataByIdScope.Global, templateKey: "properties");
  ```

  ```swift Swift v10 theme={null}
  try await client.folderMetadata.getFolderMetadataById(folderId: folder.id, scope: GetFolderMetadataByIdScope.global, templateKey: "properties")
  ```

  ```java Java v10 theme={null}
  client.getFolderMetadata().getFolderMetadataById(folder.getId(), GetFolderMetadataByIdScope.GLOBAL, "properties")
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, "id");
  Metadata metadata = folder.getMetadata();

  // Unknown type metadata field, you can test for type or try to get as any type
  JsonValue unknownValue = metadata.getValue("/someField");

  // String or Enum metadata fields
  String stringValue = metadata.getString("/author");

  // Float metadata fields can be interpreted as any numeric type
  float floatValue = metadata.getFloat("/price");

  // Date metadata fields
  Date dateValue = metadata.getDate("/deadline");
  ```

  ```py Python v4 theme={null}
  metadata = client.folder(folder_id='22222').metadata(scope='enterprise', template='myMetadata').get()
  print(f'Got metadata instance {metadata["$id"]}')
  ```

  ```csharp .NET v6 theme={null}
  Dictionary<string, object> metadata = await client.MetadataManager.
      .GetFolderMetadataAsync(folderId: "11111", "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  client.folders.getMetadata('11111', client.metadata.scopes.ENTERPRISE, 'marketingCollateral')
   .then(metadata => {
    /* metadata -> {
     audience: 'internal',
     documentType: 'Q1 plans',
     competitiveDocument: 'no',
     status: 'active',
     author: 'Jones',
     currentState: 'proposal',
     '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
     '$parent': 'folder_11111',
     '$id': '2094c584-68e1-475c-a581-534a4609594e',
     '$version': 0,
     '$typeVersion': 0,
     '$template': 'marketingCollateral',
     '$scope': 'enterprise_12345' }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `scope` and `templateKey` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link>, or
  <Link href="/guides/metadata/instances/list">list all instances on a folder</Link>.
</Info>

[e_on_folder]: /reference/get-folders-id-metadata-id-id

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Metadata instances overview
Source: https://developer.box.com/guides/metadata/instances/index



A <Link href="/guides/metadata/instances">metadata instance</Link> describes the relation between
a <Link href="/guides/metadata/templates">metadata template</Link> and a file or folder. It includes the values
that are assigned for every field of the template.

For example, a user might have assigned an `invoiceData` metadata template to a
file and provided 2 values, one for the invoice ID and one for the customer ID.

You can assign up to 100 templates to a specific file or folder.


# List all metadata on an item
Source: https://developer.box.com/guides/metadata/instances/list



Metadata instances can be listed for either a file or a folder.

## List metadata on a file

To list all metadata instances on a file, call the
<Link href="/reference/get-files-id-metadata">`GET /files/:file_id/metadata`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/files/12345/metadata" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileMetadata.getFileMetadata(file.id);
  ```

  ```python Python v10 theme={null}
  client.file_metadata.get_file_metadata(file.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.FileMetadata.GetFileMetadataAsync(fileId: file.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.fileMetadata.getFileMetadata(fileId: file.id)
  ```

  ```java Java v10 theme={null}
  client.getFileMetadata().getFileMetadata(file.getId())
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  Iterable<Metadata> metadataList = file.getAllMetadata();
  for (Metadata metadata : metadataList) {
      // Do something with the metadata.
  }
  ```

  ```py Python v4 theme={null}
  file_metadata = client.file(file_id='11111').get_all_metadata()
  for instance in file_metadata:
      if 'foo' in instance:
          print(f'Metadata instance {instance["id"]} has value "{instance["foo"]}" for foo')
  ```

  ```csharp .NET v6 theme={null}
  BoxMetadataTemplateCollection<Dictionary<string, object>> metadataInstances = await client.MetadataManager
      .GetAllFileMetadataTemplatesAsync(fileId: "11111");
  ```

  ```js Node v4 theme={null}
  client.files.getAllMetadata('11111')
   .then(metadata => {
    /* metadata -> {
     entries: 
     [ { currentDocumentStage: 'Init',
      '$type': 'documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f',
      '$parent': 'file_11111',
      '$id': '50ba0dba-0f89-4395-b867-3e057c1f6ed9',
      '$version': 4,
      '$typeVersion': 2,
      needsApprovalFrom: 'Smith',
      '$template': 'documentFlow',
      '$scope': 'enterprise_12345' },
      { '$type': 'productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9',
      '$parent': 'file_11111',
      '$id': '15d1014a-06c2-47ad-9916-014eab456194',
      '$version': 2,
      '$typeVersion': 1,
      skuNumber: 45334223,
      description: 'Watch',
      '$template': 'productInfo',
      '$scope': 'enterprise_12345' },
      { Popularity: '25',
      '$type': 'properties',
      '$parent': 'file_11111',
      '$id': 'b6f36cbc-fc7a-4eda-8889-130f350cc057',
      '$version': 0,
      '$typeVersion': 2,
      '$template': 'properties',
      '$scope': 'global' } ],
     limit: 100 }
    */
   });
  ```
</CodeGroup>

<Warning>
  This API does not support paging and it will always return all of the metadata
  instances for this file.
</Warning>

## List metadata on a folder

To list all metadata instances on any folder (except for the root folder), call
the <Link href="/reference/get-files-id-metadata">`GET /folders/:file_id/metadata`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/folders/4353455/metadata" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderMetadata.getFolderMetadata(folder.id);
  ```

  ```python Python v10 theme={null}
  client.folder_metadata.get_folder_metadata(folder.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.FolderMetadata.GetFolderMetadataAsync(folderId: folder.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.folderMetadata.getFolderMetadata(folderId: folder.id)
  ```

  ```java Java v10 theme={null}
  client.getFolderMetadata().getFolderMetadata(folder.getId())
  ```

  ```java Java v5 theme={null}
  BoxFolder file = new BoxFolder(api, "id");
  Iterable<Metadata> metadataList = folder.getAllMetadata();
  for (Metadata metadata : metadataList) {
      // Do something with the metadata.
  }
  ```

  ```py Python v4 theme={null}
  folder_metadata = client.folder(folder_id='22222').get_all_metadata()
  for instance in folder_metadata:
      if 'foo' in instance:
          print(f'Metadata instance {instance["id"]} has value "{instance["foo"]}" for foo')
  ```

  ```csharp .NET v6 theme={null}
  BoxMetadataTemplateCollection<Dictionary<string, object>> metadataInstances = await client.MetadataManager
      .GetAllFolderMetadataTemplatesAsync(folderId: "11111");
  ```

  ```js Node v4 theme={null}
  client.folders.getAllMetadata('11111')
   .then(metadata => {
    /* metadata -> {
     entries: 
     [ { currentDocumentStage: 'Init',
      '$type': 'documentFlow-452b4c9d-c3ad-4ac7-b1ad-9d5192f2fc5f',
      '$parent': 'folder_11111',
      '$id': '50ba0dba-0f89-4395-b867-3e057c1f6ed9',
      '$version': 4,
      '$typeVersion': 2,
      needsApprovalFrom: 'Smith',
      '$template': 'documentFlow',
      '$scope': 'enterprise_12345' },
      { '$type': 'productInfo-9d7b6993-b09e-4e52-b197-e42f0ea995b9',
      '$parent': 'folder_11111',
      '$id': '15d1014a-06c2-47ad-9916-014eab456194',
      '$version': 2,
      '$typeVersion': 1,
      skuNumber: 45334223,
      description: 'Watch',
      '$template': 'productInfo',
      '$scope': 'enterprise_12345' },
      { Popularity: '25',
      '$type': 'properties',
      '$parent': 'folder_11111',
      '$id': 'b6f36cbc-fc7a-4eda-8889-130f350cc057',
      '$version': 0,
      '$typeVersion': 2,
      '$template': 'properties',
      '$scope': 'global' } ],
     limit: 100 }
    */
   });
  ```
</CodeGroup>

<Warning>
  This API does not support paging and it will always return all of the metadata
  instances for this file. This API can not be used on the root folder with ID `0`.
</Warning>

[get_metadata_folder]: /reference/get-folders-id-metadata

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Update metadata on an item
Source: https://developer.box.com/guides/metadata/instances/update



<RelatedLinks title="REQUIRED GUIDES" />

Updating the metadata applied to a file or folder can be done by using the
item's `id`, the template's `templateKey` and `scope`, and a set of JSON
operations to manipulate the data on the template instance.

<Note>
  The API identifies templates by `templateKey` and fields by `key`, not by the
  display names shown in the Box web app. The `path` in each operation uses the
  field `key`, for example `/name`. To find these values,
  <Link href="/reference/get-metadata-templates-enterprise">list all metadata templates for your enterprise</Link>.
</Note>

## Update metadata on a file

To update the metadata to a file, call the
<Link href="/reference/put-files-id-metadata-id-id">`PUT /files/:file_id/metadata/:scope/:templateKey`</Link> API endpoint
with the file's `file_id`, the template's `scope` and `templateKey`, and a set of JSON
operations to manipulate the data on the template instance.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/files/12345/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json-patch+json" \
       -d '[
          {
            "op": "test",
            "path": "/competitiveDocument",
            "value": "no"
          },
          {
            "op": "remove",
            "path": "/competitiveDocument"
          },
          {
            "op": "test",
            "path": "/status",
            "value": "active"
          },
          {
            "op": "replace",
            "path": "/status",
            "value": "inactive"
          },
          {
            "op": "test",
            "path": "/author",
            "value": "Jones"
          },
          {
            "op": "copy",
            "from": "/author",
            "path": "/editor"
          },
          {
            "op": "test",
            "path": "/currentState",
            "value": "proposal"
          },
          {
            "op": "move",
            "from": "/currentState",
            "path": "/previousState"
          },
          {
            "op": "add",
            "path": "/currentState",
            "value": "reviewed"
          }
        ]'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.fileMetadata.updateFileMetadataById(
    file.id,
    'enterprise' as UpdateFileMetadataByIdScope,
    templateKey,
    [
      {
        op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
        path: '/name',
        value: 'Jack',
      } satisfies UpdateFileMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
        path: '/age',
        value: 24,
      } satisfies UpdateFileMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
        path: '/birthDate',
        value: '2000-01-03T02:20:50.520Z',
      } satisfies UpdateFileMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
        path: '/countryCode',
        value: 'CA',
      } satisfies UpdateFileMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFileMetadataByIdRequestBodyOpField,
        path: '/sports',
        value: ['football'],
      } satisfies UpdateFileMetadataByIdRequestBody,
    ],
  );
  ```

  ```python Python v10 theme={null}
  client.file_metadata.update_file_metadata_by_id(
      file.id,
      UpdateFileMetadataByIdScope.ENTERPRISE,
      template_key,
      [
          UpdateFileMetadataByIdRequestBody(
              op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
              path="/name",
              value="Jack",
          ),
          UpdateFileMetadataByIdRequestBody(
              op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24
          ),
          UpdateFileMetadataByIdRequestBody(
              op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
              path="/birthDate",
              value="2000-01-03T02:20:50.520Z",
          ),
          UpdateFileMetadataByIdRequestBody(
              op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
              path="/countryCode",
              value="CA",
          ),
          UpdateFileMetadataByIdRequestBody(
              op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
              path="/sports",
              value=["football"],
          ),
      ],
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FileMetadata.UpdateFileMetadataByIdAsync(fileId: file.Id, scope: UpdateFileMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFileMetadataByIdRequestBody() { Op = UpdateFileMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));
  ```

  ```java Java v10 theme={null}
  client.getFileMetadata().updateFileMetadataById(file.getId(), UpdateFileMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/name").value("Jack").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/age").value(24L).build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/birthDate").value("2000-01-03T02:20:50.520Z").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/countryCode").value("CA").build(), new UpdateFileMetadataByIdRequestBody.Builder().op(UpdateFileMetadataByIdRequestBodyOpField.REPLACE).path("/sports").value(Arrays.asList("football")).build()))
  ```

  ```java Java v5 theme={null}
  BoxFile file = new BoxFile(api, "id");
  file.updateMetadata(new Metadata("templateScope", "templateKey").add("/foo", "bar"));
  ```

  ```py Python v4 theme={null}
  file_obj = client.file(file_id='11111')
  file_metadata = file_obj.metadata(scope='enterprise', template='myMetadata')

  updates = file_metadata.start_update()
  updates.add('/foo', 'bar')
  updates.update('/baz', 'murp', old_value='quux')  # Ensure the old value was "quux" before updating to "murp"

  updated_metadata = file_metadata.update(updates)
  print('Updated metadata on file!')
  print(f'foo is now {updated_metadata["foo"]} and baz is now {updated_metadata["baz"]}')
  ```

  ```csharp .NET v6 theme={null}
  var updates = new List<BoxMetadataUpdate>()
  {
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/competitiveDocument",
          Value = "no"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.remove,
          Path = "/competitiveDocument"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/status",
          Value = "active"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.replace,
          Path = "/competitiveDocument",
          Value = "inactive"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/author",
          Value = "Jones"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.copy,
          From="/author",
          Path = "/editor"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/currentState",
          Value = "proposal"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.move,
          From = "/currentState",
          Path = "/previousState"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.add,
          Path = "/currentState",
          Value = "reviewed"
      }
  };
  Dictionary<string, object> updatedMetadata = await client.MetadataManager
      .UpdateFileMetadataAsync("11111", updates, "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  var updates = [
   { op: 'test', path: '/competitiveDocument', value: 'no' },
   { op: 'remove', path: '/competitiveDocument' },
   { op: 'test', path: '/status', value: 'active' },
   { op: 'replace', path: '/status', value: 'inactive' },
   { op: 'test', path: '/author', value: 'Jones' },
   { op: 'copy', from: '/author', path: '/editor' },
   { op: 'test', path: '/currentState', value: 'proposal' },
   { op: 'move', from: '/currentState', path: '/previousState' },
   { op: 'add', path: '/currentState', value: 'reviewed' }
  ];
  client.files.updateMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", updates)
   .then(metadata => {
    /* metadata -> {
     audience: 'internal',
     documentType: 'Q1 plans',
     status: 'inactive',
     author: 'Jones',
     '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
     '$parent': 'file_11111',
     '$id': '2094c584-68e1-475c-a581-534a4609594e',
     '$version': 1,
     '$typeVersion': 0,
     editor: 'Jones',
     previousState: 'proposal',
     currentState: 'reviewed',
     '$template': 'marketingCollateral',
     '$scope': 'enterprise_12345' }
    */
   });
  ```
</CodeGroup>

<Info>
  The authenticated user needs to have write access on the file to be able to
  write changes to the metadata on a file.
</Info>

## Update metadata on a folder

To update the metadata to a folder, call the
<Link href="/reference/put-folders-id-metadata-id-id">`PUT /folders/:folder_id/metadata/:scope/:templateKey`</Link> API
endpoint with the folder's `folder_id`, the template's `scope` and
`templateKey`, and a set of JSON operations to manipulate the data on the template instance.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/folders/4353455/metadata/enterprise_27335/blueprintTemplate" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json-patch+json" \
       -d '[
          {
            "op": "test",
            "path": "/competitiveDocument",
            "value": "no"
          },
          {
            "op": "remove",
            "path": "/competitiveDocument"
          },
          {
            "op": "test",
            "path": "/status",
            "value": "active"
          },
          {
            "op": "replace",
            "path": "/status",
            "value": "inactive"
          },
          {
            "op": "test",
            "path": "/author",
            "value": "Jones"
          },
          {
            "op": "copy",
            "from": "/author",
            "path": "/editor"
          },
          {
            "op": "test",
            "path": "/currentState",
            "value": "proposal"
          },
          {
            "op": "move",
            "from": "/currentState",
            "path": "/previousState"
          },
          {
            "op": "add",
            "path": "/currentState",
            "value": "reviewed"
          }
        ]'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.folderMetadata.updateFolderMetadataById(
    folder.id,
    'enterprise' as UpdateFolderMetadataByIdScope,
    templateKey,
    [
      {
        op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
        path: '/name',
        value: 'Jack',
      } satisfies UpdateFolderMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
        path: '/age',
        value: 24,
      } satisfies UpdateFolderMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
        path: '/birthDate',
        value: '2000-01-03T02:20:50.520Z',
      } satisfies UpdateFolderMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
        path: '/countryCode',
        value: 'CA',
      } satisfies UpdateFolderMetadataByIdRequestBody,
      {
        op: 'replace' as UpdateFolderMetadataByIdRequestBodyOpField,
        path: '/sports',
        value: ['football'],
      } satisfies UpdateFolderMetadataByIdRequestBody,
    ],
  );
  ```

  ```python Python v10 theme={null}
  client.folder_metadata.update_folder_metadata_by_id(
      folder.id,
      UpdateFolderMetadataByIdScope.ENTERPRISE,
      template_key,
      [
          UpdateFolderMetadataByIdRequestBody(
              op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
              path="/name",
              value="Jack",
          ),
          UpdateFolderMetadataByIdRequestBody(
              op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE, path="/age", value=24
          ),
          UpdateFolderMetadataByIdRequestBody(
              op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
              path="/birthDate",
              value="2000-01-03T02:20:50.520Z",
          ),
          UpdateFolderMetadataByIdRequestBody(
              op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
              path="/countryCode",
              value="CA",
          ),
          UpdateFolderMetadataByIdRequestBody(
              op=UpdateFolderMetadataByIdRequestBodyOpField.REPLACE,
              path="/sports",
              value=["football"],
          ),
      ],
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.FolderMetadata.UpdateFolderMetadataByIdAsync(folderId: folder.Id, scope: UpdateFolderMetadataByIdScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/name", Value = "Jack" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/age", Value = 24 },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/birthDate", Value = "2000-01-03T02:20:50.520Z" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/countryCode", Value = "CA" },new UpdateFolderMetadataByIdRequestBody() { Op = UpdateFolderMetadataByIdRequestBodyOpField.Replace, Path = "/sports", Value = Array.AsReadOnly(new [] {"football"}) }}));
  ```

  ```java Java v10 theme={null}
  client.getFolderMetadata().updateFolderMetadataById(folder.getId(), UpdateFolderMetadataByIdScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/name").value("Jack").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/age").value(24L).build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/birthDate").value("2000-01-03T02:20:50.520Z").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/countryCode").value("CA").build(), new UpdateFolderMetadataByIdRequestBody.Builder().op(UpdateFolderMetadataByIdRequestBodyOpField.REPLACE).path("/sports").value(Arrays.asList("football")).build()))
  ```

  ```java Java v5 theme={null}
  BoxFolder folder = new BoxFolder(api, "id");
  folder.updateMetadata(new Metadata().add("/foo", "bar"));
  ```

  ```py Python v4 theme={null}
  folder = client.folder(folder_id='22222')
  folder_metadata = folder.metadata(scope='enterprise', template='myMetadata')

  updates = folder_metadata.start_update()
  updates.add('/foo', 'bar')
  updates.update('/baz', 'murp', old_value='quux')  # Ensure the old value was "quux" before updating to "murp"

  updated_metadata = folder_metadata.update(updates)
  print('Updated metadata on folder!')
  print(f'foo is now {updated_metadata["foo"]} and baz is now {updated_metadata["baz"]}')
  ```

  ```csharp .NET v6 theme={null}
  var updates = new List<BoxMetadataUpdate>()
  {
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/competitiveDocument",
          Value = "no"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.remove,
          Path = "/competitiveDocument"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/status",
          Value = "active"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.replace,
          Path = "/competitiveDocument",
          Value = "inactive"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/author",
          Value = "Jones"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.copy,
          From="/author",
          Path = "/editor"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.test,
          Path = "/currentState",
          Value = "proposal"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.move,
          From = "/currentState",
          Path = "/previousState"
      },
      new BoxMetadataUpdate()
      {
          Op = MetadataUpdateOp.add,
          Path = "/currentState",
          Value = "reviewed"
      }
  };
  Dictionary<string, object> updatedMetadata = await client.MetadataManager
      .UpdateFolderMetadataAsync("11111", updates, "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  var updates = [
   { op: 'test', path: '/competitiveDocument', value: 'no' },
   { op: 'remove', path: '/competitiveDocument' },
   { op: 'test', path: '/status', value: 'active' },
   { op: 'replace', path: '/status', value: 'inactive' },
   { op: 'test', path: '/author', value: 'Jones' },
   { op: 'copy', from: '/author', path: '/editor' },
   { op: 'test', path: '/currentState', value: 'proposal' },
   { op: 'move', from: '/currentState', path: '/previousState' },
   { op: 'add', path: '/currentState', value: 'reviewed' }
  ];
  client.folders.updateMetadata('11111', client.metadata.scopes.ENTERPRISE, "marketingCollateral", updates)
   .then(metadata => {
    /* metadata -> {
     audience: 'internal',
     documentType: 'Q1 plans',
     status: 'inactive',
     author: 'Jones',
     '$type': 'marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe',
     '$parent': 'folder_11111',
     '$id': '2094c584-68e1-475c-a581-534a4609594e',
     '$version': 1,
     '$typeVersion': 0,
     editor: 'Jones',
     previousState: 'proposal',
     currentState: 'reviewed',
     '$template': 'marketingCollateral',
     '$scope': 'enterprise_12345' }
    */
   });
  ```
</CodeGroup>

<Info>
  The authenticated user needs to have write access on the file to be able to
  write changes to the metadata on a file.
</Info>

## JSON Operations

Updating a piece of metadata follows the [JSON-Patch specification][jsonpatch],
which is represented as a list of operation objects.

For metadata instances, these operations can be either `add`, `replace`,
`remove`, `test`, `move`, or `copy`. Every operation exists out of an `op`
name, the [JSON Pointer][pointer] `path` that points to the field to change,
and an optional `value` or `from` value depending on the operation being made.

```json theme={null}
[
  { "op": "test", "path": "/competitiveDocument", "value": "no" },
  { "op": "remove", "path": "/competitiveDocument" },
  { "op": "test", "path": "/status", "value": "active" },
  { "op": "replace", "path": "/status", "value": "inactive" },
  { "op": "test", "path": "/author", "value": "Jones" },
  { "op": "copy", "from": "/author", "path": "/editor" },
  { "op": "move", "from": "/currentState", "path": "/previousState" },
  { "op": "add", "path": "/currentState", "value": "reviewed" }
]
```

<Warning>
  When editing metadata, only values that adhere to the metadata template schema
  will be accepted. The update is applied completely or not at all. If any
  errors occur during the application of the update operations, the metadata
  instance is not changed.

  The template instance can only be updated if the template has already been
  assigned to the file or folder.
</Warning>

### Add a new value

To add a new value on a template, use the `add` operation.

```json theme={null}
[
  {
    "op": "add",
    "path": "/name",
    "value": "Model 3"
  }
]
```

This will add the `name` field with a value of `Model 3`. Before this
operation, the template did not have a value for the `name` field.

```json theme={null}
{
  // "name": null, // old value
  "name": "Model 3", // new value
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}
```

<Warning>
  For `enum` and `multiSelect` fields this new value needs to be one of the
  valid options for the field.
</Warning>

### Replace a value

To replace a value on a template, use the `replace` operation.

```json theme={null}
[
  {
    "op": "replace",
    "path": "/name",
    "value": "Model 4"
  }
]
```

This will replace the `name` field value `Model 3` with a new value of `Model
4`.

```json theme={null}
{
  // "name": "Model 3", # Old value
  "name": "Model 3", // new value
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}
```

<Warning>
  For `enum` and `multiSelect` fields this new value needs to be one of the
  valid options for the field.
</Warning>

### Copy a value

To copy a value from one field to another, use the `copy` operation.

```json theme={null}
[
  {
    "op": "copy",
    "from": "/name",
    "path": "/displayName"
  }
]
```

This will add the `displayName` field with a value that matches the value of the
`name` field. Before this operation, the template did not have a value for the
`displayName` field.

```json theme={null}
{
  "name": "Model 3",
  "displayName": "Model 3", // new value, copied from the name
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}
```

<Warning>
  For `enum` and `multiSelect` fields this new value needs to be one of the
  valid options for the field.
</Warning>

### Move a value

To move a value from one field to another, use the `move` operation.

```json theme={null}
[
  {
    "op": "copy",
    "from": "/name",
    "path": "/displayName"
  }
]
```

This will add the `displayName` field with a value that matches the value of the
`name` field. Before this operation, the template did not have a value for the
`displayName` field. After this operation, the `name` field no longer exists.

```json theme={null}
{
  // "name": "Model 3", // old value, no longer present now
  "displayName": "Model 3", // new value, copied from the name
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}
```

<Warning>
  For `enum` and `multiSelect` fields this new value needs to be one of the
  valid options for the field.
</Warning>

### Remove a value

To remove a value from the metadata instance, use the `remove` operation.

```json theme={null}
[
  {
    "op": "remove",
    "path": "/name"
  }
]
```

This will remove the `name` field completely from the metadata instance.

```json theme={null}
{
  // "name": "Model 3", // old value, no longer present now
  "category": "SUVs",
  "$type": "productInfo-8120731a-41e4-11ea-b77f-2e728ce88125",
  "$parent": "folder_3456",
  "$id": "22ba8c96-41e6-11ea-b77f-2e728ce88125",
  "$version": 3,
  "$typeVersion": 0,
  "$template": "productInfo",
  "$scope": "enterprise_1234567",
  "$canEdit": true
}
```

<Warning>
  For `enum` and `multiSelect` fields this new value needs to be one of the
  valid options for the field.
</Warning>

### Test a value

To test that a field has the value you expect, use the `test` operation.

```json theme={null}
[
  {
    "op": "test",
    "path": "/name",
    "value": "Model 4"
  }
]
```

When a test fails the API will not perform any of the operations and return a
`409 Conflict` HTTP status with the following error.

```json theme={null}
{
  "message": "value differs from expectations",
  "code": "failed_json_patch_application",
  "request_id": "bzxgr1gbcq5h67pj"
}
```

The main purpose of this operation is to validate that the values on the
metadata instance are as expected before any operations are performed. The Box
API either performs all changes or none, and therefore a failing test is very
useful to ensure all values are expected before any transformation is applied.

[jsonpatch]: https://tools.ietf.org/html/rfc6902

[pointer]: https://tools.ietf.org/html/rfc6901

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED RESOURCES" />


# Comparison to regular search
Source: https://developer.box.com/guides/metadata/queries/comparison



At the surface the <Link href="/reference/post-metadata-queries-execute-read">Metadata Query API</Link> seems very similar to the
<Link href="/reference/get-search">Search for content API</Link>, but there are several important
differences in how they operate. At a high level the Metadata Query API is
optimized for exactness and throughput, while regular search is optimized for
relevance to a human user.

## Deep comparison

| | <Link href="/reference/post-metadata-queries-execute-read">Metadata Query API</Link> | <Link href="/reference/get-search">Search API</Link> |
| - | - | - |
| What is indexed? | This API only returns files/folders based on the values in the metadata templates that are searched. | This API returns files, folders and web links based on values in the item names, descriptions, contents (up to the first 10,000 bytes) as well as the associated metadata template instances. |
| Indexing time | This API returns accurate results as soon as metadata has been added, removed, updated or deleted for a file or folder. | This API is subject to a search indexing delay, which is typically a few seconds, yet may be longer in some cases. This means that items may not be returned for more than a few seconds after metadata has been updated. |
| Matching | This API uses exact matching based on SQL conventions. Results are returned based on a specified sort order. | This API uses fuzzy matching and may return results that vary based on string tokenization, removal of special characters, and other search concepts. Result order is based on either relevance or the updated date of the item. |
| Conditional logic | This API supports multi-part boolean expressions with comparison operators. | This API has limited support for querying by metadata. It only supports querying 1 metadata template at a time and only allows simple query operations. |
| Response type | This API returns both the matched file/folder and the associated metadata matched by the query. | This API only returns the matched item. A subsequent API call is needed to return each item's metadata. |
| Throughput | This API is currently subject to per-user rate limits and to a 10 requests per second per enterprise limit. | This API supports 6 searches per second per user, up to 60 searches per minute and 12 searches per second per enterprise. |
| Scale | This API has no limit on the number of items with the specified metadata template that can be returned. It is recommended to only send queries which match no more than 2,000 results. | This API has no limit on number of items with the specified metadata template that can be returned, yet the response time increases significantly as the number of items matching the search grows. This API does have a limit of up to 10 million results for a query. It is recommended to only send queries which match no more than 50,000 results. |
| Scope | This API is always limited to the content to which the user has access. | This API may be either limited to the content to which the user has access (`​user_content​`) or to all content in the enterprise (`​enterprise_content​`). |

<Warning>
  Search API calls that match more than 10,000 results may result in slight
  changes in relevance. This may result in duplicate results and results that
  are not returned. Search should not be considered an ​exact matching​ solution
  on large data sets.
</Warning>

## Scenarios

The following are some example scenarios that may help you decide what API to use.

### Searching an entire enterprise for a term

You want to find all content in an enterprise with content or metadata that
matches the keyword `Guarantee`.

In this case the <Link href="/reference/get-search">Search API</Link> is recommended. This API matches terms
in both content and metadata, and can be scoped to find all content in the
entire enterprise.

### Searching for multiple metadata values

You want to find all documents with the metadata template `​Contract​` having a
value greater than \$100,000, a renewal date in 2019, and which are ​not​ associated
with account number `​1234`.

In this case the <Link href="/reference/post-metadata-queries-execute-read">Metadata Query API</Link> is recommended. With a metadata
query you can write boolean expressions that evaluate multiple fields in
a metadata template, such as a number, a date, and a string.

### Mixing metadata and content search

You want to find all documents with the metadata template `​Contract​` having a
value greater than \$100,000, renewal date in 2019, which are ​not​ associated with
account number `​1234`, ​and which contain the term “Sale” in the title or document
body.

This scenario is currently **not supported**. At the moment neither of the APIs
supports mixing both fuzzy search (searching for "Sale") and the boolean
expression matching metadata fields.


# Create a query
Source: https://developer.box.com/guides/metadata/queries/create



A metadata query is a `POST` request to the ​`/metadata_queries/execute_read`
endpoint, in which the body contains all the parts of the metadata query. Most
important here are the `from` attribute that specifies the template to search
for, the `ancestor_folder_id` to specify the folder to search in, and the
`query` to determine any template fields to search by.

```sh theme={null}
curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "from": "enterprise_123456.contractTemplate",
      "query": "amount >= :value",
      "query_params": {
        "value": 100
      },
      "fields": [
        "name",
        "metadata.enterprise_123456.contractTemplate.customerName",
        "metadata.enterprise_123456.contractTemplate.amount"
      ],
      "ancestor_folder_id": "5555",
      "order_by": [
        {
          "field_key": "amount",
          "direction": "asc"
        }
      ],
      "limit": 100
    }'
```

For more details about all the available parameters, check out any of our other
<Link href="/guides/metadata/queries">metadata query guides</Link>, or the associated <Link href="/reference/post-metadata-queries-execute-read">endpoint
reference</Link>.

<Card href={localizeLink("/guides/metadata/queries/syntax")} title="Learn more about the query syntax" />

## Response

Any files or folders that match the query are returned in the API response.
The body of the response is a JSON object with a list of `entries` for each file
or folder, and a `next_marker` value that you can use to find the next page of
results. Each of the entries will represent the file or
folder that matched the query, and only any fields explicitly requested in the
`field` parameter are returned.

```json theme={null}
{
  "entries": [
    {
      "type": "file",
      "id": "1617554169109",
      "name": "My Contract.docx",
      "metadata": {
        "enterprise_123456": {
          "contractTemplate": {
            "$parent": "file_161753469109",
            "$scope": "enterprise_123456",
            "$template": "contractTemplate",
            "$version": 0,
            "customerName": "Phoenix Corp",
            "amount": 100
          }
        }
      }
    }
  ],
  "limit": 20,
  "next_marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff"
}
```

By default this API returns `20` items per page, but more items can be requested
using marker-based pagination.

<Card href={localizeLink("/guides/metadata/queries/pagination")} title="Learn more about paginating query results" />


# Common errors
Source: https://developer.box.com/guides/metadata/queries/errors



Metadata query API errors mostly are <Link href="/guides/api-calls/permissions-and-errors/common-errors">similar to errors returned by other
APIs</Link>, however at this time some incorrect client requests may result in
a server-side error with a HTTP status code in the `5XX` range rather than an
appropriate `400 Bad Request` error.

This is a known issue which will be addressed soon.

## Incorrect template key and scope

A common error is to use an incorrect value for the `from` value in the
request, which can result in various errors in the `HTTP 4XX` range.

Without a correct `from` value the API does not know what template to search
for. The value in `from` must be formed as `scope.templateKey`.

In this case `scope` is your enterprise's template scope, which looks something
like `enterprise_123456`. The numeric value here is your enterprise's ID. Any
scope that does not match this format, including the `global` scope and the
`enterprise` shorthand scope, will return an error.

The `templateKey` is the unique key for the metadata template within your
enterprise. The API returns an error when a template with the given key does not
exist, or when the key is used within the wrong enterprise where the key does not
exist.

<Note>
  Use the `templateKey` and field `key` values in your query, not the display
  names shown in the Box web app. For example, a template displayed as
  **Product Info** can have the `templateKey` `productInfo`. The
  <Link href="/reference/get-metadata-templates-enterprise">List all metadata templates for enterprise endpoint</Link>
  returns all templates available in your enterprise, including their `scope`,
  `templateKey`, and a `fields` array with each field's `key` and `displayName`.
</Note>

## Missing value in `query_param`

A common error is to forget to include a query argument in the `query_params`
object, which results in a `HTTP 400` error with a code of
`unexpected_json_type`.

Without all arguments present in the `query_params` the API can not compile your
request into a full query.

For example, assume your search `query` is as follows
`amount >= :value AND status = :status`. All of the arguments that start with a
colon `:` will need to be present in the `query_params`. In this case your query
parameters would have to look something like this. Missing out on any of these
values will result in an error.

```json theme={null}
"query_params": {
  "value": 100,
  "status": "active"
}
```

<Note>
  The name of each argument can be configured to your liking and does not need to
  match the field key. The only requirement is that it starts with a `:`.
</Note>

## Missing `ancestor_folder_id`

A common error is to forget the `ancestor_folder_id` in the request, which
results in a `HTTP 400` error with a code of `bad_request`.

Without the `ancestor_folder_id` value the API does not know what folder to
search for results in. When in doubt a value of `0` can be used for the user's
root folder.


# Metadata queries
Source: https://developer.box.com/guides/metadata/queries/index



A metadata query provides a way to find files and
folders by searching for the metadata attached to them.

For example, to find all the files for an invoice with a certain ID, the query
would look for all files and folders with the `invoiceData` template attached to
it and a value of `id = :id`, where `:id` would be the value of the invoice.

## Authentication

The metadata query API can be used by applications that have been authenticated
using traditional <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> or <Link href="/guides/authentication/jwt">JWT</Link>.


# Query item fields
Source: https://developer.box.com/guides/metadata/queries/item-fields



Item fields are searchable metadata fields that describe items (files and folders) in Box. These fields expose built-in item properties such as name, type, owner, and timestamps with defined data types so you can filter, sort, and search Box content.

## Supported item fields

The following table lists the item fields you can use in metadata queries.

| Field name | Description | Sorting |
| - | - | - |
| `item.type` | Type of the item: `file` or `folder` | Yes |
| `item.name` | Name of the item | Yes |
| `item.description` | Description of the item | Yes |
| `item.extension` | File extension, such as `pdf`, `jpeg`, `xlsx`, `txt`, `xls`, `png`, `log`, or `csv` | Yes |
| `item.owned_by` | Owner of the item, for example `user_123` | Yes |
| `item.owner_enterprise_id` | Enterprise ID of the item owner, for example `1234` | Yes |
| `item.created_at` | Date and time when the item was created in Box | Yes |
| `item.modified_at` | Date and time when the item was last updated in Box | Yes |


# Metadata query limitations
Source: https://developer.box.com/guides/metadata/queries/limitations



A few limits apply to the metadata query APIs.

## Files and folders

​A metadata query will only return items (files or folders) to which the
requesting user has at least `previewer` access.

## Enterprise vs Global templates

A metadata query only works with metadata templates that have been created by
that enterprise. A query will not return results based on the content of free
form key-value pairs stored in the `​global.properties` template.

## Classification metadata templates

Box uses metadata templates to power its content classification. These metadata
templates can not be used in metadata queries, as they will most likely run
into issues regarding large results sets. More on this next.

There are no immediate plans to start supporting these queries in the future.


# Paginate and sort
Source: https://developer.box.com/guides/metadata/queries/pagination



By default only 20 query results are returned per page and the order of these
results is not guaranteed and may change. Pagination and sorting allow for
getting more results and defining the order of the results.

## Pagination

By default the API only returns the first page of 20 results. To request more
results per page the `limit` query parameter can be sent with the request.

```sh theme={null}
curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "from": "enterprise_123456.contractTemplate",
      "fields": ["name"],
      "ancestor_folder_id": "5555",
      "limit": 100
    }'
```

The maximum value for `limit` is 100. To return more pages of results each page
returns a `next_marker` value.

```json theme={null}
{
  "entries": [...],
  "next_marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff"
}
```

This `next_marker` can be used to form a new request for the next page of
results.

```sh theme={null}
curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
    -H 'Authorization: Bearer <ACCESS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
      "from": "enterprise_123456.contractTemplate",
      "fields": ["name"],
      "ancestor_folder_id": "5555",
      "limit": 100,
      "marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff"
    }'
```

<Note>
  When a response does not include a next marker it indicates that no more
  matching results exist.
</Note>

<Warning>
  To use the `next_marker` it is important to use the exact same query for the
  next page of results. The API will return an error if any of the parameters
  like the `query`, `query_params`, or others are changed.
</Warning>

## Sort

Results can be ordered by any of the supported metadata field types. The only
supported types currently are `float`, `date`, and `string`
<Link href="/guides/metadata/fields">fields</Link>. Ordering by `enum` or `multiSelect` value is
currently not supported.

To order results, provide one or more field keys to sort by, as well as a
direction.

```json theme={null}
"order_by": [
  {
    "field_key": "amount”,
    "direction": "desc"
  },
  {
    "field_key": "created_at",
    "direction": "desc"
  }
]
```

<Warning>
  The ordering direction must be the same for all ​​specified keys. In other
  words, for each `field_key` the `direction` must be the same.
</Warning>


# Query syntax
Source: https://developer.box.com/guides/metadata/queries/syntax



The query syntax for the metadata query API is similar to that of a SQL
database. To query for all files and folders that match a contract metadata
template with a contract value of over \$100 the following metadata query could
be created.

```json theme={null}
{
  "from": "enterprise_123456.contractTemplate",
  "query": "amount >= :value",
  "query_params": {
    "value": 100
  },
  "fields": [
    "name",
    "metadata.enterprise_123456.contractTemplate.amount"
  ],
  "ancestor_folder_id": "5555"
}
```

In this case the `from` value represents the `scope` and `templateKey` of the
metadata template, and the `ancestor_folder_id` represents the folder ID to
search within, including its subfolders.

## The `fields` parameter

By default, this API will only return the base-representation of a file or
folder, which includes their `id`, `type`, and `etag` values. To request any
additional data the `fields` parameter can be used to query any additional
fields, as well as any metadata associated to the item.

For example:

* `created_by` will add the details of the user who created the item to the response.
* `metadata.<scope>.<templateKey>` will return the base-representation of the metadata instance identified by the `scope` and `templateKey`.
* `metadata.<scope>.<templateKey>.<field>` will return all fields in the base-representation of the metadata instance identified by the `scope` and `templateKey` plus the field specified by the `field` name. Multiple fields for the same `scope` and `templateKey` can be defined.

## The `query` parameter

The `query` parameter represents the SQL-like query to perform on the selected
metadata instance. This parameter is optional, and without this parameter the
API would return all files and folders for this template.

Every left hand field name, like `amount`, needs to match the `key` of a
field on the associated metadata template. In other words, you can only search
for fields that are actually present on the associated metadata instance. Any
other field name will result in the API returning an error.

### The `query_params` parameter

To make it less complicated to embed dynamic values into the query string, an
argument can be defined using a colon syntax, like `:value`. Each argument that
is specified like this needs a subsequent value with that key in the
`query_params` object, for example:

```json theme={null}
{
  ...,
  "query": "amount >= :amount AND country = :country",
  "query_params": {
    "amount": 100,
    "country": "United States"
  },
  ...
}
```

### Logical operators

A query supports the following logical operators.

| Operator | |
| - | - |
| `AND` | Matches when all the conditions separated by `AND` are `TRUE`. |
| `OR` | Matches when any of the conditions separated by `OR` is `TRUE`. |
| `NOT` | Matches when the preceding condition(s) is **not** `TRUE`. |
| `LIKE` | Matches when the template field value matches a pattern. Only supported for string values. See [pattern matching](#pattern-matching) for more details. See additional limitations below. |
| `NOT LIKE` | Matches when the template field value does **not** match a pattern. Only supported for string values. See [pattern matching](#pattern-matching) for more details. See additional limitations below. |
| `ILIKE` | Identical to `LIKE` but case insensitive. See additional limitations below. |
| `NOT ILIKE` | Identical to `NOT LIKE` but case insensitive. See additional limitations below. |
| `IN` | Matches when a template field value equals any value in a specified list. Use explicitly defined `query_params` arguments for each list item, such as `amount IN (:arg1, :arg2, :arg3)`. By design, the IN operator isn't supported for multiselect fields in metadata queries and returns a 400 error. |
| `NOT IN` | Similar to `IN` but when the template field value matches none of the arguments provided in the list. |
| `IS NULL` | Matches when the template field value is `null`. |
| `IS NOT NULL` | Matches when the template field value is not `null` . |
| `HASANY` | Matches when the field value is equal to any of the arguments provided. The format requires each item in the list to be an explicitly defined `query_params` argument, for example, amount `HASANY (:arg1, :arg2, :arg3)`. |
| `HASALL` | Matches when the field value has a match for all the arguments provided. The format requires each item in the list to be an explicitly defined `query_params` argument, for example, amount `HASALL (:arg1, :arg2, :arg3)`. |
| `HASANCESTOR` | Matches when the field value is a descendant of any argument provided. The format requires each item in the list to be an explicitly defined `query_params` argument, for example, amount `HASANCESTOR (:arg1, :arg2, :arg3)`. Supported only for the taxonomy MD field. |

<Note>
  Any match on a `string` or `enum` field is case sensitive except when using
  the `ILIKE` operator.
</Note>

### Comparison operators

A query supports the following comparison operators.

| Operator | |
| - | - |
| `=` | Ensures a template field value is **equal to** the specified value |
| `>` | Ensures a template field value is **greater than** the specified value |
| `<` | Ensures a template field value is **less than** the specified value |
| `>=` | Ensures a template field value is **greater than or equal to** the specified value |
| `<=` | Ensures a template field value is **less than or equal to** the specified value |
| `<>` | Ensures a template field value is **not equal to** the specified value |

<Warning>
  Bit-wise and arithmetic operators are not supported by the Metadata Query API.
</Warning>

### Pattern matching

The `LIKE`, `NOT LIKE`, `ILIKE`, and `NOT ILIKE` operators match a string
to a pattern. The pattern supports the following reserved characters.

* `%` The percent sign represents zero, one, or multiple characters, for example `%Contract` matches `Contract`, `Sales Contract`, but not `Contract (Sales)`,
* `_` The underscore represents a single character, for example `Bo_` matches `Box`, `Bot`, but not `Bots`,

Both of these reserved characters can be used before, after, or in between other
characters. A pattern can include multiple reserved characters, for example
`Box% (____)` would match `Box Contract (2020)`.

An example query would look something like this. Note that the `%`-wrapped
string is not in the `query` attribute but in the list of `query_params`.

```json theme={null}
{
  ...,
  "query": "country ILIKE :country",
  "query_params": {
    "country": "%United%"
  },
  ...
}
```

<Note>
  The backslash character `\` can be used to escape the `%` or
  `_` characters if those need to be matched literally, for example
  `20\%` would match the literal value of `20%`.
</Note>


# Apply metadata to a file
Source: https://developer.box.com/guides/metadata/quick-start/create-instance



<ProgressBar />

With your new `customerData` template in hand you can now apply this template to
a file or folder. To apply this template you will need the `scope` and
`templateKey` of the template, as well as the ID of the item to apply the
template to.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X POST https://api.box.com/2.0/files/12345/metadata/enterprise/customerInfo \
      -H "authorization: Bearer <ACCESS_TOKEN>" \
      -H "content-type: application/json" \
      -d '{
        "name": "Box, Inc",
        "industry": "Technology",
        "tav": 1000000
      }'
  ```

  ```csharp .NET theme={null}
  var metadataValues = new Dictionary<string, object>()
  {
      { "name", "Box, Inc" },
      { "industry", "Technology" },
      { "tav", 100000 }
  };

  Dictionary<string, object> metadata = await client.MetadataManager
      .CreateFileMetadataAsync(fileId: "12345", metadataValues, "enterprise", "customerInfo");
  ```

  ```java Java theme={null}
  BoxFile file = new BoxFile(api, "12345");

  file.createMetadata(
      "customerInfo",
      "enterprise",
      new Metadata()
          .add("name", "Box, Inc")
          .add("industry", "Technology")
          .add("tav", 100000)
  );
  ```

  ```python Python theme={null}
  metadata = {
      'name': 'Box, Inc',
      'industry': 'Technology',
      'tav': 1000000
  }

  client.file(file_id='11111').metadata(scope='enterprise', template='customerInfo').set(metadata)
  ```

  ```js Node theme={null}
  client.files.addMetadata(
      '12345',
      client.metadata.scopes.ENTERPRISE,
      "customerInfo",
      {
          name: "Box, Inc",
          industry: "Technology",
          tav: 1000000
      }
  ).then(metadata => {
      // ...
  });
  ```
</CodeGroup>

<Warning>
  The `industry` field in this example is an `enum` field and therefore the
  value needs to be one of the available options on the field. Any other value
  will result in an error.
</Warning>

The API will return the newly created metadata instance.

```json theme={null}
{
  "name": "Box, Inc",
  "industry": "Technology",
  "tav": 1000000,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$parent": "folder_12345,",
  "$scope": "enterprise_34567",
  "$template": "customerInfo",
  "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2,
  "$version": 1,
  "$canEdit": true
}
```

<Next>I've applied metadata to a file</Next>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create a metadata query
Source: https://developer.box.com/guides/metadata/quick-start/create-query



<ProgressBar />

As a final step, let's look at how you can create a query to find specific files
and folders based on the metadata attached to those files/folders.

A <Link href="/guides/metadata/queries">metadata query</Link> provides a way to find files and
folders by searching for the metadata attached to them. The search syntax
is similar to SQL and it supports boolean operations and comparative operators
to perform powerful searches.

In our case, let's create a query to find any files or folders that have an
instance of the `customerInfo` metadata template attached to them. We will
filter this list down to any files that belong to a customer whose total account
value is more than \$200,000.

```sh cURL theme={null}
curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
    -H 'Authorization: Bearer <ACCESS_TOKEN>" ' \
    -H 'Content-Type: application/json' \
    -d '{
      "from": "enterprise_123456.customerInfo",
      "fields": [
        "name",
        "enterprise_123456.customerInfo.name"
        "enterprise_123456.customerInfo.tav"
      ],
      "query": "tav >= :value",
      "query_params": {
        "value": 200000
      },
      "ancestor_folder_id": "0"
    }'
```

This API will return a list of matched files and folders, as well as the
metadata that matched the query for that file.

```json theme={null}
{
  "entries": [
    {
      "type": "file",
      "id": "11111",
      "etag": "0",
      "metadata": {
        "enterprise_123456": {
          "customerInfo": {
            "name": "Box",
            "tav": 1000000,
            "$parent": "folder_12345,",
            "$scope": "enterprise_123456",
            "$template": "customerInfo",
            "$version": 1
          }
        }
      }
    }
  ],
  "limit": 20,
  "next_marker": "AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff"
}
```

By default this API returns `20` items per page, but more items can be requested
using marker-based pagination.

<Card href={localizeLink("/guides/metadata/queries")} title="Learn more about metadata queries" />

<Next>I've queried a file using metadata</Next>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create a custom metadata template
Source: https://developer.box.com/guides/metadata/quick-start/create-template



<ProgressBar />

To create a custom metadata template for your enterprise you can use
<Link href="/reference/post-metadata-templates-schema">our API directly</Link> or
one of our SDKs to create a new template.

For this `customerInfo` template, we're going to create a template with 3
fields. The first field is a text field to hold the customer's `name`, the
second is a dropdown list of the possible values for the `industry` the customer
operates in, and the final field represents the total annual contract value (`tav`).

<Card href={localizeLink("/guides/metadata/fields")} title="Learn about the different field types" />

To create this template we need to pass in the configuration for the fields, as
well as a display name for the field.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X POST https://api.box.com/2.0/metadata_templates/schema \
      -H "authorization: Bearer <ACCESS_TOKEN>" \
      -H "content-type: application/json" \
      -d '{
        "scope": "enterprise",
        "displayName": "Customer Info",
        "fields": [
          {
            "type": "string",
            "displayName": "Name"
          },
          {
            "type": "enum",
            "displayName": "Industry",
            "options": [
              {"key": "Technology"},
              {"key": "Healthcare"},
              {"key": "Legal"}
            ]
          },
          {
            "type": "float",
            "displayName": "Total account value",
            "key": "tav"
          }
        ]
      }'
  ```

  ```csharp .NET theme={null}
  var templateParams = new BoxMetadataTemplate()
  {
    DisplayName = "Customer Info",
    Scope = "enterprise",
    Fields = new List<BoxMetadataTemplateField>()
    {
      new BoxMetadataTemplateField()
      {
        Type = "string",
        DisplayName = "Name"
      },
      new BoxMetadataTemplateField()
      {
        Type = "enum",
        DisplayName = "Industry",
        Options = new List<BoxMetadataTemplateFieldOption>()
        {
          new BoxMetadataTemplateFieldOption() { Key = "Technology" },
          new BoxMetadataTemplateFieldOption() { Key = "Healthcare" },
          new BoxMetadataTemplateFieldOption() { Key = "Legal" }
        }
      },
      new BoxMetadataTemplateField()
      {
        Type = "float",
        DisplayName = "Total account value",
        Key="tav"
      },
    }
  };
  BoxMetadataTemplate template = await  client.MetadataManager.CreateMetadataTemplate(templateParams);
  ```

  ```java Java theme={null}
  MetadataTemplate.Field name = new MetadataTemplate.Field();
  name.setType("string");
  name.setDisplayName("Name");

  MetadataTemplate.Field industry = new MetadataTemplate.Field();
  industry.setType("enum");
  industry.setDisplayName("Industry");

  MetadataTemplate.Option technology = new MetadataTemplate.Option();
  technology.setKey("Technology");

  MetadataTemplate.Option healthcare = new MetadataTemplate.Option();
  healthcare.setKey("Healthcare");

  MetadataTemplate.Option legal = new MetadataTemplate.Option();
  legal.setKey("Legal");

  List<MetadataTemplate.Option> options = new ArrayList<MetadataTemplate.Option>();
  options.add(technology);
  options.add(healthcare);
  options.add(legal);

  MetadataTemplate.Field tav = new MetadataTemplate.Field();
  tav.setType("float");
  tav.setDisplayName("Total account value");
  tav.setKey("tav");

  List<MetadataTemplate.Field> fields = new ArrayList<MetadataTemplate.Field>();
  fields.add(name);
  fields.add(industry);
  fields.add(tav);

  MetadataTemplate template = MetadataTemplate.createMetadataTemplate(api, "enterprise", "customerInfo", "Customer Info", false, fields);
  ```

  ```python Python theme={null}
  from boxsdk.object.metadata_template import MetadataField, MetadataFieldType

  fields = [
      MetadataField(MetadataFieldType.STRING, 'Name')
      MetadataField(MetadataFieldType.ENUM, 'Industry', options=['Technology', 'Healthcare', 'Legal'])
  ]
  template = client.create_metadata_template('Customer Info', fields)
  ```

  ```js Node theme={null}
  client.metadata.createTemplate(
      'Customer Info',
      [
          {
              type: 'string',
              displayName: 'Name'
          },
          {
              type: 'enum',
              displayName: 'Industry',
              options: [
                  {key: 'Technology'},
                  {key: 'Healthcare'},
                  {key: 'Legal'}
              ]
          },
          {
              type: 'float',
              displayName: 'Total account value',
              key: 'tav'
          }
      ]
  ).then(template => {
      // ...
  });
  ```
</CodeGroup>

<Warning>
  **Admin permissions required**

  Creating metadata templates is restricted to users with admin permission. This
  means that only admins, or co-admins who have been granted rights to **Create
  and edit metadata templates for your company** by the admin can use the web
  app or the API to manage templates.
</Warning>

The API will return the newly created metadata template.

```json theme={null}
{
  "id": "100ac693-a468-4b37-9535-05984b804dc2",
  "type": "metadata_template",
  "templateKey": "customerInfo",
  "scope": "enterprise_34567",
  "displayName": "Customer Info",
  "hidden": false,
  "copyInstanceOnItemCopy": false,
  "fields": [
    {
      "id": "5c6a5906-003b-4654-9deb-472583fc2930",
      "type": "string",
      "key": "name",
      "displayName": "Name",
      "hidden": false
    },
    {
      "id": "cf3eb5b8-52ef-456c-b175-44354a27e289",
      "type": "enum",
      "key": "industry",
      "displayName": "Industry",
      "options": [
        {"key": "Technology"},
        {"key": "Healthcare"},
        {"key": "Legal"}
      ],
      "hidden": false
    },
    {
      "id": "5c6a5906-4654-9deb-003b-472583fc2930",
      "type": "float",
      "key": "tav",
      "displayName": "Total account value",
      "hidden": false
    }
  ]
}
```

<Note>
  **Template key**

  Although you did not explicitly set the template key the key is automatically
  derived from the `displayName` value. In this case, the `templateKey` would be
  `customerInfo`.
</Note>

<Next>I've created a custom template</Next>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Working with Metadata
Source: https://developer.box.com/guides/metadata/quick-start/index



The Metadata APIs are a great tool to allow applications to automatically add
additional information to files and folders.

<Frame>
  <img alt="An example of Metadata" />
</Frame>

## Overview

This guide will take you through the following steps.

1. <Link href="/guides/metadata/quick-start/list-all">List all templates</Link> available to you.
2. <Link href="/guides/metadata/quick-start/create-template">Create a custom metadata template</Link> to hold data specific to your enterprise.
3. <Link href="/guides/metadata/quick-start/create-instance">Apply a custom metadata template</Link> to a file, allowing you to assign custom data to a file.
4. <Link href="/guides/metadata/quick-start/update-instance">Update metadata instance</Link> on a file, allowing you to change the data assigned to a file.
5. <Link href="/guides/metadata/quick-start/update-template">Update a metadata template</Link> and change the data applied to all instances of this template.
6. <Link href="/guides/metadata/quick-start/create-query">Create a query to find files by metadata</Link> and change the data applied to all instances of this template.

<Next>
  I am ready to get started
</Next>


# List all metadata templates (quick start)
Source: https://developer.box.com/guides/metadata/quick-start/list-all



<ProgressBar />

It's likely your enterprise already has a list of metadata templates that you
can use right off-the-shelf without having to create your own.

In general, metadata templates are either available to only your enterprise or
to every enterprise using Box. The `scope` of a template defines if a template
is available to everyone (`global`) or only to your enterprise (`enterprise`).

<Card href={localizeLink("/guides/metadata/scopes")} title="Learn more about metadata scopes" />

## Listing templates

A few <Link href="/reference/get-metadata-templates-global">global templates</Link> are available to all
customers.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_templates/global" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.getGlobalMetadataTemplates();
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.get_global_metadata_templates()
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.GetGlobalMetadataTemplatesAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.getGlobalMetadataTemplates()
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().getGlobalMetadataTemplates()
  ```

  ```java Java v5 theme={null}
  Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates('global', api);
  for (MetadataTemplate templateInfo : templates) {
      // Do something with the metadata template.
  }
  ```

  ```py Python v4 theme={null}
  templates = client.get_metadata_templates(scope='global)
  for template in templates:
      print(f'Metadata template {template.templateKey} is in global scope')
  ```

  ```csharp .NET v6 theme={null}
  BoxEnterpriseMetadataTemplateCollection<BoxMetadataTemplate> templates = await client.MetadataManager
      .GetEnterpriseMetadataAsync("global");
  ```

  ```js Node v4 theme={null}
  client.metadata.getTemplates('global')
   .then(templates => {
    // ...
   });
  ```
</CodeGroup>

Many of these templates are for Box's internal use, yet your application can use
and apply these. More useful are templates <Link href="/reference/get-metadata-templates-enterprise">created by applications and admins
within your enterprise</Link> to hold data
specific to your enterprise's needs.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_templates/enterprise" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.getEnterpriseMetadataTemplates();
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.get_enterprise_metadata_templates()
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.GetEnterpriseMetadataTemplatesAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.getEnterpriseMetadataTemplates()
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().getEnterpriseMetadataTemplates()
  ```

  ```java Java v5 theme={null}
  Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates(api);
  for (MetadataTemplate templateInfo : templates) {
      // Do something with the metadata template.
  }
  ```

  ```py Python v4 theme={null}
  templates = client.get_metadata_templates()
  for template in templates:
      print(f'Metadata template {template.templateKey} is in enterprise scope')
  ```

  ```csharp .NET v6 theme={null}
  BoxEnterpriseMetadataTemplateCollection<BoxMetadataTemplate> templates = await client.MetadataManager
      .GetEnterpriseMetadataAsync();
  ```

  ```js Node v4 theme={null}
  client.metadata.getTemplates('enterprise')
   .then(templates => {
    /* templates -> {
     limit: 100,
     entries: 
     [ { templateKey: 'documentFlow',
      scope: 'enterprise_12345',
      displayName: 'Document Flow',
      hidden: false,
      fields: 
       [ { type: 'string',
        key: 'currentDocumentStage',
        displayName: 'Current Document Stage',
        hidden: false }
       { type: 'string',
        key: 'needsApprovalFrom',
        displayName: 'Needs Approval From',
        hidden: false },
       { type: 'string',
        key: 'nextDocumentStage',
        displayName: 'Next Document Stage',
        hidden: false }
       { type: 'float',
        key: 'maximumDaysAllowedInCurrentStage',
        displayName: 'Maximum Days Allowed In Current Stage',
        hidden: false }
      { templateKey: 'marketingCollateral',
      scope: 'enterprise_12345',
      displayName: 'Marketing Collateral',
      hidden: false,
      fields: 
       [ { type: 'string',
        key: 'audience1',
        displayName: 'Audience',
        hidden: false },
       { type: 'string',
        key: 'previousState',
        displayName: 'Previous State',
        hidden: false } ] },
      { templateKey: 'productInfo',
      scope: 'enterprise_12345',
      displayName: 'Product Info',
      hidden: false,
      fields: 
       [ { type: 'float',
        key: 'skuNumber',
        displayName: 'SKU Number',
        hidden: false },
       { type: 'enum',
        key: 'department',
        displayName: 'Department',
        hidden: false,
        options: 
        [ { key: 'Beauty' },
        { key: 'Shoes' },
        { key: 'Accessories' },
        { key: 'Clothing' },
        { key: 'Handbags' },
        { key: 'Bedding' },
        { key: 'Watches' } ] },
       { type: 'date',
        key: 'displayDate',
        displayName: 'Display Date',
        hidden: false } ] } ],
     next_marker: null,
     prev_marker: null }
    */
   });
  ```
</CodeGroup>

## A metadata template

A <Link href="/guides/metadata/templates">metadata template</Link> describes a set of key/value
pairs that can be assigned to a file or folder.

For example, a `customerInfo` template might hold data about a customer,
having a field for the customer name as well as the customer's industry.

```json theme={null}
{
  "id": "100ac693-a468-4b37-9535-05984b804dc2",
  "type": "metadata_template",
  "templateKey": "customerInfo",
  "scope": "enterprise_12345",
  "displayName": "Customer Info",
  "hidden": false,
  "copyInstanceOnItemCopy": false,
  "fields": [
    {
      "id": "5c6a5906-003b-4654-9deb-472583fc2930",
      "type": "string",
      "key": "name",
      "displayName": "Name",
      "hidden": false
    },
    {
      "id": "cf3eb5b8-52ef-456c-b175-44354a27e289",
      "type": "enum",
      "key": "industry",
      "displayName": "Industry",
      "options": [
        {"key": "Technology"},
        {"key": "Healthcare"},
        {"key": "Legal"}
      ],
      "hidden": false
    }
  ]
}
```

<Next>I've listed the templates available to me</Next>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Metadata quick start: next steps
Source: https://developer.box.com/guides/metadata/quick-start/next-steps



<ProgressBar />

You've reached the end of this Quick Start guide. By now you should have taken
the following steps.

1. <Link href="/guides/metadata/quick-start/list-all">Listed all templates</Link> available to you.
2. <Link href="/guides/metadata/quick-start/create-template">Created a custom metadata template</Link> to hold data specific to your enterprise.
3. <Link href="/guides/metadata/quick-start/create-instance">Applied a custom metadata template</Link> to a file, allowing you to assign custom data to a file.
4. <Link href="/guides/metadata/quick-start/update-instance">Updated a metadata instance</Link> on a file, allowing you to change the data assigned to a file.
5. <Link href="/guides/metadata/quick-start/update-template">Updated a metadata template</Link> and changed the data applied to all instances of this template.
6. <Link href="/guides/metadata/quick-start/create-query">Queried for files and folders</Link> by matching the values in the metadata instances attached to them.

## Next Steps

We recommend the following resources to learn more about using metadata with the
Box API.

* <Link href="/guides/metadata/scopes">Learn more about metadata scopes</Link>
* <Link href="/guides/metadata/fields">Learn more about the different field types</Link> that can be used on a template.


# Update metadata on a file
Source: https://developer.box.com/guides/metadata/quick-start/update-instance



<ProgressBar />

Once metadata has been applied to a file or folder there is often a need to
update the metadata at a later date.

Updating a metadata instance is done by applying a set of operations to the
original data. These operations are performed atomically, ensuring that the
changes are either all applied or not applied at all.

<Card href={localizeLink("/guides/metadata/instances/update")} title="Learn more about updating instances" />

In this case, let's assume we want to change the `name` of the customer from
`Box, Inc` to `Box`. We can apply two operations, firstly, we ensure the
value of the name is still `Box, Inc` before we change it, and secondly we make
the change.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X PUT https://api.box.com/2.0/files/12345/metadata/enterprise/customerInfo \
      -H "authorization: Bearer <ACCESS_TOKEN>" \
      -H "content-type: application/json-patch+json" \
      -d '[
        {
          "op": "test",
          "path": "/name",
          "value": "Box, Inc"
        },
        {
          "op": "replace",
          "path": "/name",
          "value": "Box"
        }
      ]'
  ```

  ```csharp .NET theme={null}
  var updates = new List<BoxMetadataUpdate>()
  {
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.test,
        Path = "/name",
        Value = "Box, Inc"
    },
    new BoxMetadataUpdate()
    {
        Op = MetadataUpdateOp.replace,
        Path = "/name",
        Value = "Box"
    }
  };
  Dictionary<string, object> updatedMetadata = await client.MetadataManager
      .UpdateFileMetadataAsync("12345", updates, "enterprise", "customerInfo");
  ```

  ```java Java theme={null}
  BoxFile file = new BoxFile(api, "12345");
  file.updateMetadata(
    file.createMetadata(
    "customerInfo",
    "enterprise",
    new Metadata().test("/name", "Box, Inc").replace("/name", "Box")
  );
  ```

  ```python Python theme={null}
  file = client.file(file_id='12345')
  metadata = file.metadata(scope='enterprise', template='customerInfo')

  updates = metadata.start_update()
  updates.test('/name', 'Box, Inc')
  updates.replace('/name', 'Box')

  file.update(updates)
  ```

  ```js Node theme={null}
  var updates = [
      { op: 'test', path: '/name', value: 'Box, Inc' },
      { op: 'replace', path: '/name', value: 'Box' }
  ];

  client.files.updateMetadata(
      '12345',
      client.metadata.scopes.ENTERPRISE,
      "customerInfo",
      updates
  ).then(metadata => {
      //...
  });
  ```
</CodeGroup>

<Card href={localizeLink("/guides/metadata/instances/update")} title="Learn more about all operations" />

The API will return the updated metadata instance.

```json theme={null}
{
  "name": "Box",
  "industry": "Technology",
  "tav": 1000000,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$parent": "folder_12345,",
  "$scope": "enterprise_34567",
  "$template": "customerInfo",
  "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2,
  "$version": 1,
  "$canEdit": true
}
```

<Next>I've updated metadata on a file</Next>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Update a metadata template (quick start)
Source: https://developer.box.com/guides/metadata/quick-start/update-template



<ProgressBar />

Let's look at how we can update an existing metadata template.

Updates to metadata templates are performed through **operations** rather than
directly changing the template itself. This method allows you to update any
existing metadata instances that are already applied to files and folders.

<Card href={localizeLink("/guides/metadata/templates/update")} title="Learn more about updating templates" />

In this case, let's assume that we realized that having a `Name` field is a bit
ambiguous, and therefore, we want to change the `Name` field of the `customerInfo` template
to `Company Name` instead. By using the `editField` operation we can change the
`displayName` and the `key` of the field on the template and on every instance
of the template that might be applied to a file or folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -X PUT https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema \
      -H "authorization: Bearer <ACCESS_TOKEN>" \
      -H "content-type: application/json" \
      -d '[
        {
          "op": "editField",
          "fieldKey": "name",
          "data": {
            "key": "company_name",
            "displayName": "Company Name"
          }
        }
      ]'
  ```

  ```csharp .NET theme={null}
  var updates = new List<BoxMetadataTemplateUpdate>()
  {
    new BoxMetadataTemplateUpdate()
    {
        Op = MetadataTemplateUpdateOp.editField,
        FieldKey = "name",
        Data = new {
            key = "company_name",
            displayName = "Company Name"
        }
    }
  };
  BoxMetadataTemplate updatedTemplate = await client.MetadataManager
      .UpdateMetadataTemplate(updates, "enterprise", "customerData");
  ```

  ```java Java theme={null}
  List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>();

  String editField = "{\"op\":\"editField\",\"fieldKey\":\"name\",\"data\":{\"key\":\"company_name\",\"displayName\":\"Company Name\"}}";
  updates.add(new MetadataTemplate.FieldOperation(editField));

  MetadataTemplate.updateMetadataTemplate(api, "enterprise", "customerData", updates);
  ```

  ```python Python theme={null}
  template = client.metadata_template('enterprise', 'customerData')
  updates = template.start_update()
  updates.edit_field('name', key='company_name', display_name="Company Name")
  template.update_info(updates)
  ```

  ```js Node theme={null}
  var operations = [
      {
          op: 'editField',
          fieldKey: 'name',
          data: {
              key: 'company_name',
              displayName: "Company Name"
          }
      }
  ];

  client.metadata.updateTemplate(
      'enterprise',
      'customerData',
      operations
  ).then(template => {
      //..
  });
  ```
</CodeGroup>

The API will return the updated metadata template.

```json theme={null}
{
  "id": "100ac693-a468-4b37-9535-05984b804dc2",
  "type": "metadata_template",
  "templateKey": "customerInfo",
  "scope": "enterprise_34567",
  "displayName": "Customer Info",
  "hidden": false,
  "copyInstanceOnItemCopy": false,
  "fields": [
    {
      "id": "5c6a5906-003b-4654-9deb-472583fc2930",
      "type": "string",
      "key": "company_name",
      "displayName": "Company Name",
      "hidden": false
    },
    {
      "id": "cf3eb5b8-52ef-456c-b175-44354a27e289",
      "type": "enum",
      "key": "industry",
      "displayName": "Industry",
      "options": [
        {"key": "Technology"},
        {"key": "Healthcare"},
        {"key": "Legal"}
      ],
      "hidden": false
    },
    {
      "id": "5c6a5906-4654-9deb-003b-472583fc2930",
      "type": "float",
      "key": "tav",
      "displayName": "Total account value",
      "hidden": false
    }
  ]
}
```

Updating the template through operations has the benefit that any instance of
the template is automatically updated as well. In this case, the instance we
created in previous steps would now look something like this.

```json theme={null}
{
  "company_name": "Box",
  "industry": "Technology",
  "tav": 1000000,
  "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
  "$parent": "folder_12345,",
  "$scope": "enterprise_34567",
  "$template": "customerInfo",
  "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
  "$typeVersion": 2,
  "$version": 1,
  "$canEdit": true
}
```

<Next>I've updated metadata template</Next>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Metadata template scopes
Source: https://developer.box.com/guides/metadata/scopes



Metadata templates are grouped into two distinct groups, or **scopes**.

* **`global`**: a group of templates that is available to everyone using Box, regardless of the enterprise they are in. An example is the `global.properties` template that serves as a place to put free-form key/value `string` pairs without any additional schema associated with it.
* **`enterprise`** or **`enterprise_*`**: a group of templates defined by a user within an enterprise. These templates are either created by admins in the web application, or by applications using the API. When accessing or creating templates within the authenticated user's enterprise a short-hand of `enterprise` can be used. When accessing templates that belong to another enterprise - for example when accessing metadata on files belonging to other enterprises - the scope `enterprise_*` is used where `*` is the ID of the enterprise the template belongs to.

<Warning>
  **Permissions**

  It is important to note that no metadata templates can be created within the
  `global` scope, and that metadata templates made within the user's enterprise
  can only be accessed by users with access to that enterprise.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED RESOURCES" />


# Create metadata taxonomy items
Source: https://developer.box.com/guides/metadata/taxonomies/create



Metadata taxonomies can be created using the taxonomy’s `displayName` and `namespace`, with related items created using the `namespace` and `taxonomy_key`.

## Create a metadata taxonomy

Create a new taxonomy that can be referenced by metadata templates.

Call the <Link href="/reference/post-metadata-taxonomies">`POST /metadata_taxonomies`</Link> API endpoint with the taxonomy’s `displayName` and `namespace`. Box will optionally generate a key if you didn't specify one.

<CodeGroup>
  ```sh cURL theme={null}
  curl --request POST \ 
  --url "https://api.box.com/2.0/metadata_taxonomies" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  --header "Content-Type: application/json" \ 
  --data '{ 
  "displayName": "DISPLAY_NAME", 
  "namespace": "{namespace}", 
  "key": "{taxonomy_key}" 
  }'
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.create_metadata_taxonomy(
      display_name, namespace, key=taxonomy_key
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.createMetadataTaxonomy({
    displayName: displayName,
    key: taxonomyKey,
    namespace: namespace,
  } satisfies CreateMetadataTaxonomyRequestBody);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.createMetadataTaxonomy(requestBody: CreateMetadataTaxonomyRequestBody(displayName: displayName, key: taxonomyKey, namespace: namespace))
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().createMetadataTaxonomy(new CreateMetadataTaxonomyRequestBody.Builder(displayName, namespace).key(taxonomyKey).build())
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.CreateMetadataTaxonomyAsync(requestBody: new CreateMetadataTaxonomyRequestBody(displayName: displayName, namespaceParam: namespaceParam) { Key = taxonomyKey });
  ```
</CodeGroup>

## Create metadata taxonomy levels

Before you can add nodes, you must define the hierarchy of your taxonomy by creating one or more levels. Each level represents a hierarchical tier (for example, `Country`, `State`, `City`).

Call the <Link href="/reference/post-metadata-taxonomies-id-id-levels">`POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels`</Link> API endpoint with the taxonomy’s `displayName`, `description`, and `level`.

<CodeGroup>
  ```sh cURL theme={null}
  curl --request POST \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/levels" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  --header "Content-Type: application/json" \ 
  --data '{ 
  "levels": [ 
  { 
  "displayName": "Continent", 
  "description": "Continent Level" 
  }, 
  { 
  "displayName": "Country", 
  "description": "Country Level" 
  } 
  ] 
  }' 
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.create_metadata_taxonomy_level(
      namespace,
      taxonomy_key,
      [
          MetadataTaxonomyLevel(display_name="Continent", description="Continent Level"),
          MetadataTaxonomyLevel(display_name="Country", description="Country Level"),
      ],
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.createMetadataTaxonomyLevel(
    namespace,
    taxonomyKey,
    [
      {
        displayName: 'Continent',
        description: 'Continent Level',
      } satisfies MetadataTaxonomyLevel,
      {
        displayName: 'Country',
        description: 'Country Level',
      } satisfies MetadataTaxonomyLevel,
    ],
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.createMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: [MetadataTaxonomyLevel(displayName: "Continent", description: "Continent Level"), MetadataTaxonomyLevel(displayName: "Country", description: "Country Level")])
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().createMetadataTaxonomyLevel(namespace, taxonomyKey, Arrays.asList(new MetadataTaxonomyLevel.Builder().displayName("Continent").description("Continent Level").build(), new MetadataTaxonomyLevel.Builder().displayName("Country").description("Country Level").build()))
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.CreateMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: Array.AsReadOnly(new [] {new MetadataTaxonomyLevel() { DisplayName = "Continent", Description = "Continent Level" },new MetadataTaxonomyLevel() { DisplayName = "Country", Description = "Country Level" }}));
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

## Add an additional level

After defining the initial levels, you can add another level to the end of the existing hierarchy (for example, adding “City” after “Country”).

Call the <Link href="/reference/post-metadata-taxonomies-id-id-levels--append">`POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels:append`</Link> API endpoint with the taxonomy’s `displayName` and `description`.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request POST \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/levels:append" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  --header "Content-Type: application/json" \ 
  --data '{ 
  "displayName": "Region", 
  "description": "Region Description" 
  }'  
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.add_metadata_taxonomy_level(
      namespace, taxonomy_key, "Region", description="Region Description"
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.addMetadataTaxonomyLevel(
    namespace,
    taxonomyKey,
    {
      displayName: 'Region',
      description: 'Region Description',
    } satisfies AddMetadataTaxonomyLevelRequestBody,
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.addMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: AddMetadataTaxonomyLevelRequestBody(displayName: "Region", description: "Region Description"))
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().addMetadataTaxonomyLevel(namespace, taxonomyKey, new AddMetadataTaxonomyLevelRequestBody.Builder("Region").description("Region Description").build())
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.AddMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new AddMetadataTaxonomyLevelRequestBody(displayName: "Region") { Description = "Region Description" });
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

## Add nodes to the taxonomy

With the hierarchy defined, you can begin adding nodes, which are the data in the taxonomy hierarchy.

Call the <Link href="/reference/post-metadata-taxonomies-id-id-nodes">`POST /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes`</Link> API endpoint with the taxonomy’s `displayName`, `level`, and `parentId`.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request POST \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  --header "Content-Type: application/json" \ 
  --data '{ 
  "displayName": "Europe", 
  "level": 1 
  }'   
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.create_metadata_taxonomy_node(
      namespace, taxonomy_key, "Europe", 1
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.createMetadataTaxonomyNode(
    namespace,
    taxonomyKey,
    {
      displayName: 'Europe',
      level: 1,
    } satisfies CreateMetadataTaxonomyNodeRequestBody,
  );
  ```

  ```swift theme={null}
  try await client.metadataTaxonomies.createMetadataTaxonomyNode(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: CreateMetadataTaxonomyNodeRequestBody(displayName: "Europe", level: 1))
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().createMetadataTaxonomyNode(namespace, taxonomyKey, new CreateMetadataTaxonomyNodeRequestBody("Europe", 1))
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.CreateMetadataTaxonomyNodeAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new CreateMetadataTaxonomyNodeRequestBody(displayName: "Europe", level: 1));
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Get metadata taxonomy items
Source: https://developer.box.com/guides/metadata/taxonomies/get



Information about metadata taxonomies can be retrieved using the `namespace`, `taxonomy_key`, `node_id`, and `field_key`.

## List metadata taxonomy nodes

Retrieve a list of nodes defined within a metadata taxonomy. Nodes are the hierarchical data available in your taxonomy.

To list all nodes, call the <Link href="/reference/get-metadata-taxonomies-id-id-nodes">`GET /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request GET \ 
    --url https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes \ 
    --header 'Authorization: Bearer <token>' 
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.get_metadata_taxonomy_nodes(namespace, taxonomy_key)
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.getMetadataTaxonomyNodes(namespace, taxonomyKey);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.getMetadataTaxonomyNodes(namespace: namespace, taxonomyKey: taxonomyKey)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().getMetadataTaxonomyNodes(namespace, taxonomyKey)
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.GetMetadataTaxonomyNodesAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

## Get a metadata taxonomy by key

Get the full definition of a specific taxonomy including how many levels it has, and what the display names and descriptions of those levels are.

To get information by taxonomy key, call the <Link href="/reference/get-metadata-taxonomies-id-id">`GET /metadata_taxonomies/{namespace}/{taxonomy_key}`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request GET \ 
    --url https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key} \ 
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.get_metadata_taxonomy_by_key(namespace, taxonomy_key)
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.getMetadataTaxonomyByKey(
    namespace,
    taxonomyKey,
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.getMetadataTaxonomyByKey(namespace: namespace, taxonomyKey: taxonomyKey)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().getMetadataTaxonomyByKey(namespace, taxonomyKey)
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.GetMetadataTaxonomyByKeyAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

## Get a metadata taxonomy node by ID

You can fetch a specific node and its metadata using its ID. Nodes are the hierarchical data available in your taxonomy.

To get a node, call the <Link href="/reference/get-metadata-taxonomies-id-id-nodes-id">`GET /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request GET \ 
    --url https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id} \ 
    --header 'Authorization: Bearer <token>' 
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.get_metadata_taxonomy_node_by_id(
      namespace, taxonomy_key, country_node.id
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.getMetadataTaxonomyNodeById(
    namespace,
    taxonomyKey,
    countryNode.id,
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.getMetadataTaxonomyNodeById(namespace: namespace, taxonomyKey: taxonomyKey, nodeId: countryNode.id)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().getMetadataTaxonomyNodeById(namespace, taxonomyKey, countryNode.getId())
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.GetMetadataTaxonomyNodeByIdAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, nodeId: countryNode.Id);
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link>, <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link>, and <Link href="/reference/resources/metadata-taxonomy-node#schema-id">`node_id`</Link> of a taxonomy.
</Info>

## List metadata taxonomy field options

Retrieve the nodes that serve as selectable options for a taxonomy field, as defined inside a metadata template.

To list possible values for taxonomy nodes in a template, call the <Link href="/reference/get-metadata-templates-id-id-fields-id-options">`GET /metadata_templates/{namespace}/{template_key}/fields/{field_key}/options`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request GET \  
    --url https://api.box.com/2.0/metadata_templates/{namespace}/{template_key}/fields/{field_key}/options \ 
    --header 'Authorization: Bearer <token>'
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.get_metadata_template_field_options(
      namespace, metadata_template_key, "taxonomy"
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.getMetadataTemplateFieldOptions(
    namespace,
    metadataTemplateKey,
    'taxonomy',
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.getMetadataTemplateFieldOptions(namespace: namespace, templateKey: metadataTemplateKey, fieldKey: "taxonomy")
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().getMetadataTemplateFieldOptions(namespace, metadataTemplateKey, "taxonomy")
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.GetMetadataTemplateFieldOptionsAsync(namespaceParam: namespaceParam, templateKey: metadataTemplateKey, fieldKey: "taxonomy");
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link>, <Link href="/guides/metadata/templates/create#template-keys">`template_key`</Link>, and <Link href="/guides/metadata/templates/create">`field_key`</Link> of a taxonomy.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Metadata taxonomies overview
Source: https://developer.box.com/guides/metadata/taxonomies/index



A metadata taxonomy enables Box admins to define metadata hierarchies, as well as:

* Add multi-level metadata to a file or folder

* Define terms that form available taxonomy options

* Reuse a taxonomy in multiple metadata templates

Taxonomies can help admins organize and manage their company's metadata structures. An example of a 5-level taxonomy could include the categories of Region, Country, State, County, and City.

A taxonomy can have a depth of up to 10 levels.


# List metadata taxonomies
Source: https://developer.box.com/guides/metadata/taxonomies/list



Retrieve all metadata taxonomies defined within a given namespace, such as an enterprise. This lets you discover which taxonomies are available before working with a specific one.

To list taxonomies, call the <Link href="/reference/get-metadata-taxonomies-id">`GET /metadata_taxonomies/{namespace}`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request GET \
  --url https://api.box.com/2.0/metadata_taxonomies/{namespace} \
  --header 'Authorization: Bearer <token>'
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.get_metadata_taxonomies(namespace)
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.getMetadataTaxonomies(namespace);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.getMetadataTaxonomies(namespace: namespace)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().getMetadataTaxonomies(namespace)
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.GetMetadataTaxonomiesAsync(namespaceParam: namespaceParam);
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> of a taxonomy.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Remove metadata taxonomy items
Source: https://developer.box.com/guides/metadata/taxonomies/remove



Remove metadata taxonomies and their structural components. Taxonomy deletion is permanent and irreversible, so use with caution.

## Delete a metadata taxonomy

Deletes an entire metadata taxonomy and all associated levels and nodes. This action cannot be undone. The taxonomy and its nodes will no longer be accessible for metadata templates or other API calls.

Call the <Link href="/reference/delete-metadata-taxonomies-id-id">`DELETE /metadata_taxonomies/{namespace}/{taxonomy_key}`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl --request DELETE \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" 
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.delete_metadata_taxonomy(namespace, taxonomy_key)
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.deleteMetadataTaxonomy(namespace, taxonomyKey);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.deleteMetadataTaxonomy(namespace: namespace, taxonomyKey: taxonomyKey)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().deleteMetadataTaxonomy(namespace, taxonomyKey)
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.DeleteMetadataTaxonomyAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

## Remove a metadata taxonomy node

Deletes a specific node within a taxonomy. If the node has child nodes, you must delete those children first before you can remove the parent node. This endpoint does not cascade; it only deletes individual nodes that have no children under them.

Call the <Link href="/reference/delete-metadata-taxonomies-id-id-nodes-id">`DELETE /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl --request DELETE \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" 
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.delete_metadata_taxonomy_node(
      namespace, taxonomy_key, country_node.id
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.deleteMetadataTaxonomyNode(
    namespace,
    taxonomyKey,
    countryNode.id,
  );
  ```

  ```swift theme={null}
  try await client.metadataTaxonomies.deleteMetadataTaxonomyNode(namespace: namespace, taxonomyKey: taxonomyKey, nodeId: countryNode.id)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().deleteMetadataTaxonomyNode(namespace, taxonomyKey, countryNode.getId())
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.DeleteMetadataTaxonomyNodeAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, nodeId: countryNode.Id);
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link>, <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link>, and <Link href="/reference/resources/metadata-taxonomy-node#schema-id">`node_id`</Link> of a taxonomy.
</Info>

## Remove the last level of a taxonomy

Removes the last level of a taxonomy’s hierarchy. Levels are evaluated in hierarchical order, and this call trims only the deepest level.

Call the <Link href="/reference/post-metadata-taxonomies-id-id-levels--trim">`POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels:trim`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}

  curl --request POST \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/levels:trim" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" 
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.delete_metadata_taxonomy_level(namespace, taxonomy_key)
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.deleteMetadataTaxonomyLevel(
    namespace,
    taxonomyKey,
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.deleteMetadataTaxonomyLevel(namespace: namespace, taxonomyKey: taxonomyKey)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().deleteMetadataTaxonomyLevel(namespace, taxonomyKey)
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.DeleteMetadataTaxonomyLevelAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey);
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Update metadata taxonomies
Source: https://developer.box.com/guides/metadata/taxonomies/update



Update metadata taxonomy elements such as `displayNames`, `descriptions`, and other attributes of an existing taxonomy structure.

## Update a metadata taxonomy

Use this endpoint to update top-level attributes of an existing taxonomy, such as changing its `displayName`.

Call the <Link href="/reference/patch-metadata-taxonomies-id-id">`PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl --request PATCH \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  --header "Content-Type: application/json" \ 
  --data '{ 
  "displayName": "UPDATED DISPLAY NAME" 
  }'
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.update_metadata_taxonomy(
      namespace, taxonomy_key, updated_display_name
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.updateMetadataTaxonomy(namespace, taxonomyKey, {
    displayName: updatedDisplayName,
  } satisfies UpdateMetadataTaxonomyRequestBody);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.updateMetadataTaxonomy(namespace: namespace, taxonomyKey: taxonomyKey, requestBody: UpdateMetadataTaxonomyRequestBody(displayName: updatedDisplayName))
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().updateMetadataTaxonomy(namespace, taxonomyKey, new UpdateMetadataTaxonomyRequestBody(updatedDisplayName))
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.UpdateMetadataTaxonomyAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, requestBody: new UpdateMetadataTaxonomyRequestBody(displayName: updatedDisplayName));
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link> and <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link> of a taxonomy.
</Info>

## Update a taxonomy level

Update the display name and description of an existing level within a taxonomy. The level index identifies which level to update.

Call the <Link href="/reference/patch-metadata-taxonomies-id-id-levels-id">`PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}/levels/{level_index}`</Link> API endpoint with the `displayName` and `description`.

<CodeGroup>
  ```sh cURL theme={null}
  curl --request PATCH \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/levels/1" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  --header "Content-Type: application/json" \ 
  --data '{ 
  "displayName": "Continent UPDATED", 
  "description": "Continent Level UPDATED" 
  }'
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.update_metadata_taxonomy_level_by_id(
      namespace,
      taxonomy_key,
      1,
      "Continent UPDATED",
      description="Continent Level UPDATED",
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.updateMetadataTaxonomyLevelById(
    namespace,
    taxonomyKey,
    1,
    {
      displayName: 'Continent UPDATED',
      description: 'Continent Level UPDATED',
    } satisfies UpdateMetadataTaxonomyLevelByIdRequestBody,
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.updateMetadataTaxonomyLevelById(namespace: namespace, taxonomyKey: taxonomyKey, levelIndex: Int64(1), requestBody: UpdateMetadataTaxonomyLevelByIdRequestBody(displayName: "Continent UPDATED", description: "Continent Level UPDATED"))
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().updateMetadataTaxonomyLevelById(namespace, taxonomyKey, 1L, new UpdateMetadataTaxonomyLevelByIdRequestBody.Builder("Continent UPDATED").description("Continent Level UPDATED").build())
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.UpdateMetadataTaxonomyLevelByIdAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, levelIndex: 1L, requestBody: new UpdateMetadataTaxonomyLevelByIdRequestBody(displayName: "Continent UPDATED") { Description = "Continent Level UPDATED" });
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link>, <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link>, and <Link href="/reference/resources/metadata-taxonomy-level">`level_index`</Link> of a taxonomy.
</Info>

## Update a taxonomy node

Use this endpoint to modify the display name or relationship attributes of an existing node in a taxonomy - for example, renaming **Paris** to **Paris City**.

Call the <Link href="/reference/patch-metadata-taxonomies-id-id-nodes-id">`PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}`</Link> API endpoint with the taxonomy’s `displayName`.

<CodeGroup>
  ```sh cURL theme={null}
  curl --request PATCH \ 
  --url "https://api.box.com/2.0/metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}" \ 
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \ 
  --header "Content-Type: application/json" \ 
  --data '{ 
  "displayName": "Poland UPDATED" 
  }'
  ```

  ```python Python v10 theme={null}
  client.metadata_taxonomies.update_metadata_taxonomy_node(
      namespace, taxonomy_key, country_node.id, display_name="Poland UPDATED"
  )
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTaxonomies.updateMetadataTaxonomyNode(
    namespace,
    taxonomyKey,
    countryNode.id,
    {
      requestBody: {
        displayName: 'Poland UPDATED',
      } satisfies UpdateMetadataTaxonomyNodeRequestBody,
    } satisfies UpdateMetadataTaxonomyNodeOptionalsInput,
  );
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTaxonomies.updateMetadataTaxonomyNode(namespace: namespace, taxonomyKey: taxonomyKey, nodeId: countryNode.id, requestBody: UpdateMetadataTaxonomyNodeRequestBody(displayName: "Poland UPDATED"))
  ```

  ```java Java v10 theme={null}
  client.getMetadataTaxonomies().updateMetadataTaxonomyNode(namespace, taxonomyKey, countryNode.getId(), new UpdateMetadataTaxonomyNodeRequestBody.Builder().displayName("Poland UPDATED").build())
  ```

  ```cs .NET v10 theme={null}
  await client.MetadataTaxonomies.UpdateMetadataTaxonomyNodeAsync(namespaceParam: namespaceParam, taxonomyKey: taxonomyKey, nodeId: countryNode.Id, requestBody: new UpdateMetadataTaxonomyNodeRequestBody() { DisplayName = "Poland UPDATED" });
  ```
</CodeGroup>

<Info>
  Additional information is available for the <Link href="/reference/resources/metadata-taxonomy#schema-namespace">`namespace`</Link>, <Link href="/reference/resources/metadata-taxonomy#schema-key">`taxonomy_key`</Link>, and <Link href="/reference/resources/metadata-taxonomy-node">`node_id`</Link> of a taxonomy.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />

<RelatedLinks title="RELATED RESOURCES" />


# Create a metadata template
Source: https://developer.box.com/guides/metadata/templates/create



<RelatedLinks title="REQUIRED GUIDES" />

To create a metadata template, pass a `scope`, `displayName` and an optional set
of `fields` to the <Link href="/reference/post-metadata-templates-schema">`POST /metadata_templates/schema`</Link> API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/metadata_templates/schema" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
        "scope": "enterprise",
        "displayName": "Customer",
        "fields": [
          {
            "type": "string",
            "key": "name",
            "displayName": "Name",
            "description": "The customer name",
            "hidden": false
          },
          {
            "type": "date",
            "key": "last_contacted_at",
            "displayName": "Last Contacted At",
            "description": "When this customer was last contacted at",
            "hidden": false
          },
          {
            "type": "enum",
            "key": "industry",
            "displayName": "Industry",
            "options": [
              {"key": "Technology"},
              {"key": "Healthcare"},
              {"key": "Legal"}
            ]
          },
          {
            "type": "multiSelect",
            "key": "role",
            "displayName": "Contact Role",
            "options": [
              {"key": "Developer"},
              {"key": "Business Owner"},
              {"key": "Marketing"},
              {"key": "Legal"},
              {"key": "Sales"}
            ]
          }
        ]
      }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.createMetadataTemplate({
    scope: 'enterprise',
    displayName: templateKey,
    templateKey: templateKey,
    fields: [
      {
        type: 'string' as CreateMetadataTemplateRequestBodyFieldsTypeField,
        key: 'testName',
        displayName: 'testName',
      } satisfies CreateMetadataTemplateRequestBodyFieldsField,
      {
        type: 'float' as CreateMetadataTemplateRequestBodyFieldsTypeField,
        key: 'age',
        displayName: 'age',
      } satisfies CreateMetadataTemplateRequestBodyFieldsField,
      {
        type: 'date' as CreateMetadataTemplateRequestBodyFieldsTypeField,
        key: 'birthDate',
        displayName: 'birthDate',
      } satisfies CreateMetadataTemplateRequestBodyFieldsField,
      {
        type: 'enum' as CreateMetadataTemplateRequestBodyFieldsTypeField,
        key: 'countryCode',
        displayName: 'countryCode',
        options: [
          {
            key: 'US',
          } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
          {
            key: 'CA',
          } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
        ],
      } satisfies CreateMetadataTemplateRequestBodyFieldsField,
      {
        type: 'multiSelect' as CreateMetadataTemplateRequestBodyFieldsTypeField,
        key: 'sports',
        displayName: 'sports',
        options: [
          {
            key: 'basketball',
          } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
          {
            key: 'football',
          } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
          {
            key: 'tennis',
          } satisfies CreateMetadataTemplateRequestBodyFieldsOptionsField,
        ],
      } satisfies CreateMetadataTemplateRequestBodyFieldsField,
    ],
  } satisfies CreateMetadataTemplateRequestBody);
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.create_metadata_template(
      "enterprise",
      template_key,
      template_key=template_key,
      fields=[
          CreateMetadataTemplateFields(
              type=CreateMetadataTemplateFieldsTypeField.STRING,
              key="testName",
              display_name="testName",
          ),
          CreateMetadataTemplateFields(
              type=CreateMetadataTemplateFieldsTypeField.FLOAT,
              key="age",
              display_name="age",
          ),
          CreateMetadataTemplateFields(
              type=CreateMetadataTemplateFieldsTypeField.DATE,
              key="birthDate",
              display_name="birthDate",
          ),
          CreateMetadataTemplateFields(
              type=CreateMetadataTemplateFieldsTypeField.ENUM,
              key="countryCode",
              display_name="countryCode",
              options=[
                  CreateMetadataTemplateFieldsOptionsField(key="US"),
                  CreateMetadataTemplateFieldsOptionsField(key="CA"),
              ],
          ),
          CreateMetadataTemplateFields(
              type=CreateMetadataTemplateFieldsTypeField.MULTISELECT,
              key="sports",
              display_name="sports",
              options=[
                  CreateMetadataTemplateFieldsOptionsField(key="basketball"),
                  CreateMetadataTemplateFieldsOptionsField(key="football"),
                  CreateMetadataTemplateFieldsOptionsField(key="tennis"),
              ],
          ),
      ],
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.CreateMetadataTemplateAsync(requestBody: new CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey) { TemplateKey = templateKey, Fields = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.String, key: "testName", displayName: "testName"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Float, key: "age", displayName: "age"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Date, key: "birthDate", displayName: "birthDate"),new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.Enum, key: "countryCode", displayName: "countryCode") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "US"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "CA")}) },new CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.MultiSelect, key: "sports", displayName: "sports") { Options = Array.AsReadOnly(new [] {new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "basketball"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "football"),new CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "tennis")}) }}) });
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.createMetadataTemplate(requestBody: CreateMetadataTemplateRequestBody(scope: "enterprise", displayName: templateKey, templateKey: templateKey, fields: [CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.string, key: "testName", displayName: "testName"), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.float, key: "age", displayName: "age"), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.date, key: "birthDate", displayName: "birthDate"), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.enum_, key: "countryCode", displayName: "countryCode", options: [CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "US"), CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "CA")]), CreateMetadataTemplateRequestBodyFieldsField(type: CreateMetadataTemplateRequestBodyFieldsTypeField.multiSelect, key: "sports", displayName: "sports", options: [CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "basketball"), CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "football"), CreateMetadataTemplateRequestBodyFieldsOptionsField(key: "tennis")])]))
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().createMetadataTemplate(new CreateMetadataTemplateRequestBody.Builder("enterprise", templateKey).templateKey(templateKey).fields(Arrays.asList(new CreateMetadataTemplateRequestBodyFieldsField(CreateMetadataTemplateRequestBodyFieldsTypeField.STRING, "testName", "testName"), new CreateMetadataTemplateRequestBodyFieldsField(CreateMetadataTemplateRequestBodyFieldsTypeField.FLOAT, "age", "age"), new CreateMetadataTemplateRequestBodyFieldsField(CreateMetadataTemplateRequestBodyFieldsTypeField.DATE, "birthDate", "birthDate"), new CreateMetadataTemplateRequestBodyFieldsField.Builder(CreateMetadataTemplateRequestBodyFieldsTypeField.ENUM, "countryCode", "countryCode").options(Arrays.asList(new CreateMetadataTemplateRequestBodyFieldsOptionsField("US"), new CreateMetadataTemplateRequestBodyFieldsOptionsField("CA"))).build(), new CreateMetadataTemplateRequestBodyFieldsField.Builder(CreateMetadataTemplateRequestBodyFieldsTypeField.MULTISELECT, "sports", "sports").options(Arrays.asList(new CreateMetadataTemplateRequestBodyFieldsOptionsField("basketball"), new CreateMetadataTemplateRequestBodyFieldsOptionsField("football"), new CreateMetadataTemplateRequestBodyFieldsOptionsField("tennis"))).build())).build())
  ```

  ```java Java v5 theme={null}
  MetadataTemplate.Field metadataField = new MetadataTemplate.Field();
  metadataField.setType("string");
  metadataField.setKey("text");
  metadataField.setDisplayName("Text");

  List<MetadataTemplate.Field> fields = new ArrayList<MetadataTemplate.Field>();
  fields.add(metadataField);

  MetadataTemplate template = MetadataTemplate.createMetadataTemplate(api, "enterprise", "CustomField", "Custom Field", false, fields);

  final JsonObject jsonObject = new JsonObject();
  jsonObject.add("text", "This is a test text");

  Metadata metadata = new Metadata(jsonObject);
  boxFile.createMetadata("CustomField", metadata);
  ```

  ```py Python v4 theme={null}
  from boxsdk.object.metadata_template import MetadataField, MetadataFieldType

  fields = [
      MetadataField(MetadataFieldType.STRING, 'Name'),
      MetadataField(MetadataFieldType.DATE, 'Birthday', 'bday'),
      MetadataField(MetadataFieldType.ENUM, 'State', options=['CA', 'TX', 'NY'])
  ]
  template = client.create_metadata_template('Employee Record', fields, hidden=True)
  print(f'Metadata template ID {template.scope}/{template.templateKey} created!')
  ```

  ```csharp .NET v6 theme={null}
  var templateParams = new BoxMetadataTemplate()
  {
      TemplateKey = "marketingCollateral",
      DisplayName = "Marketing Collateral",
      Scope = "enterprise",
      Fields = new List<BoxMetadataTemplateField>()
      {
          new BoxMetadataTemplateField()
          {
              Type = "enum",
              Key = "audience",
              DisplayName = "Audience",
              Options = new List<BoxMetadataTemplateFieldOption>()
              {
                  new BoxMetadataTemplateFieldOption() { Key = "internal" },
                  new BoxMetadataTemplateFieldOption() { Key = "external" }
              }
          },
          new BoxMetadataTemplateField()
          {
              Type = "string",
              Key = "author",
              DisplayName = "Author"
          }
      }
  };
  BoxMetadataTemplate template = await client.MetadataManager.CreateMetadataTemplate(templateParams);
  ```

  ```js Node v4 theme={null}
  // Create a new template, but hide it for now until it's ready for use
  client.metadata.createTemplate(
    'Vendor Contract',
    [
     {
      type: 'date',
      key: 'signed',
      displayName: 'Date Signed'
     },
     {
      type: 'string',
      key: 'vendor',
      displayName: 'Vendor'
     },
     {
      type: 'enum',
      key: 'fy',
      displayName: 'Fiscal Year',
      options: [
       {key: 'FY17'},
       {key: 'FY18'},
       {key: 'FY19'}
      ]
     }
    ],
    {
     hidden: true,
     templateKey: 'vcontract',
     copyInstanceOnItemCopy: false
    }
   )
   .then(template => {
    /* template -> {
     id: '17f2d715-6acb-45f2-b96a-28b15efc9faa',
     templateKey: 'vcontract',
     scope: 'enterprise_12345',
     displayName: 'Vendor Contract',
     hidden: true,
     copyInstanceOnItemCopy: false,
     fields: 
     [ { type: 'date',
      key: 'signed',
      displayName: 'Date Signed',
      hidden: false },
      { type: 'string',
      key: 'vendor',
      displayName: 'Vendor',
      hidden: false },
      { type: 'enum',
      key: 'fy',
      displayName: 'Fiscal Year',
      options: 
       [ { key: 'FY17' },
       { key: 'FY18' },
       { key: 'FY19' } ],
      hidden: false } ] }
    */
   });
  ```
</CodeGroup>

<Note>
  Metadata templates can only be created for the `enterprise` scope. Templates
  can not be created for the `global` scope.
</Note>

<Warning>
  **Admin permissions required**

  Creating metadata templates is restricted to users with admin permission. This
  means that only admins, or co-admins who have been granted rights to **Create
  and edit metadata templates for your company** by the admin can use the web
  app or the API to manage templates.
</Warning>

## Template Fields

The `fields` attribute represents the set of individual fields that a user can
fill in on a template. For example, a `customer` template might have a `name`
field of type `string`.

Template fields can be of `string`, `enum`, `float`, `date` or
`multiSelect` type. Each field requires at least a `type`, `displayName` and `key`.

```json theme={null}
{
  "scope": "enterprise",
  "displayName": "Customer",
  "fields": [
    {
      "type": "string",
      "key": "name",
      "displayName": "Name"
    }
  ]
}
```

The `enum` and `multiSelect` field types represent a dropdown list where a user
can select respectively one or many options from a list of items.

```json theme={null}
{
  "scope": "enterprise",
  "displayName": "Customer",
  "fields": [
    {
      "type": "enum",
      "key": "industry",
      "displayName": "Industry",
      "options": [
        {"key": "Technology"},
        {"key": "Healthcare"},
        {"key": "Legal"}
      ]
    }
  ]
}
```

<Card href={localizeLink("/guides/metadata/fields")} title="Learn more about Metadata Template Fields" />

## Template Keys

When a metadata template is created, a `templateKey` is automatically generated
from the `displayName` of the template unless a `templateKey` is explicitly
provided. When creating the template key, any spaces and irregular
characters in the name are removed, and the string is transformed to camel case.

For example, a metadata template that is named
`Test Name (with-special_) Characters` will have a `templateKey` of
`testNameWithspecialCharacters`.

This template key is then used when making any API requests to get the
template's information or assign it to an item.

[user-types]: /guides/getting-started/users

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete a metadata template
Source: https://developer.box.com/guides/metadata/templates/delete



<RelatedLinks title="REQUIRED GUIDES" />

Deleting a metadata template can be achieved by calling the <Link href="/reference/delete-metadata-templates-id-id-schema">`DELETE
/metadata_templates/enterprise/:templateKey/schema`</Link> API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.deleteMetadataTemplate(
    'enterprise' as DeleteMetadataTemplateScope,
    template.templateKey!,
  );
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.delete_metadata_template(
      DeleteMetadataTemplateScope.ENTERPRISE, template.template_key
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.DeleteMetadataTemplateAsync(scope: DeleteMetadataTemplateScope.Enterprise, templateKey: NullableUtils.Unwrap(template.TemplateKey));
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.deleteMetadataTemplate(scope: DeleteMetadataTemplateScope.enterprise, templateKey: template.templateKey!)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().deleteMetadataTemplate(DeleteMetadataTemplateScope.ENTERPRISE, template.getTemplateKey())
  ```

  ```java Java v5 theme={null}
  MetadataTemplate.deleteMetadataTemplate(api, "enterprise", "templateName");
  ```

  ```py Python v4 theme={null}
  client.metadata_template('enterprise', 'employeeRecord').delete()
  ```

  ```js Node v4 theme={null}
  client.metadata.deleteTemplate('enterprise', 'testtemplate', callback);
  ```
</CodeGroup>

This API returns a `204 No Content` API response with no response body when
the template has been successfully deleted. This API also removes all the
template instances from any files and folders.

Only templates created within the `enterprise` scope can be deleted.

<Warning>
  **Admin permissions required**

  Deleting metadata templates is restricted to users with admin permission. This
  means that only admins, or co-admins who have been granted rights to **Create
  and edit metadata templates for your company** by the admin can use the web
  app or the API to manage templates.
</Warning>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get a metadata template
Source: https://developer.box.com/guides/metadata/templates/get



Information for a metadata template can be retrieved using the template's name
and scope, or the template's identifier.

<Info>
  The authenticated user can only get information about metadata templates
  <Link href="/guides/metadata/scopes">scoped</Link> within the `global` scope or the `enterprise_:id` scope where
  `:id` is the ID of their enterprise.
</Info>

## Get a metadata template by name

To get a metadata template by name, call the <Link href="/reference/get-metadata-templates-id-id-schema">`GET
/metadata_templates/:scope/:templateKey/schema`</Link> API endpoint with the
template's `scope` and `templateKey`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.getMetadataTemplate(
    'enterprise' as GetMetadataTemplateScope,
    template.templateKey!,
  );
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.get_metadata_template(
      GetMetadataTemplateScope.ENTERPRISE, template.template_key
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.GetMetadataTemplateAsync(scope: GetMetadataTemplateScope.Enterprise, templateKey: NullableUtils.Unwrap(template.TemplateKey));
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.getMetadataTemplate(scope: GetMetadataTemplateScope.enterprise, templateKey: template.templateKey!)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().getMetadataTemplate(GetMetadataTemplateScope.ENTERPRISE, template.getTemplateKey())
  ```

  ```java Java v5 theme={null}
  MetadataTemplate template = MetadataTemplate.getMetadataTemplate(api, "templateName");
  ```

  ```py Python v4 theme={null}
  template = client.metadata_template('enterprise', 'employeeRecord').get()
  print(f'The {template.displayName} template has {len(template.fields)} fields')
  ```

  ```csharp .NET v6 theme={null}
  BoxMetadataTemplate template = await client.MetadataManager
      .GetMetadataTemplate("enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  client.metadata.getTemplateSchema('enterprise', 'vcontract')
   .then(template => {
    /* template -> {
     id: '17f2d715-6acb-45f2-b96a-28b15efc9faa',
     templateKey: 'vcontract',
     scope: 'enterprise_12345',
     displayName: 'Vendor Contract',
     hidden: true,
     fields: 
     [ { type: 'date',
      key: 'signed',
      displayName: 'Date Signed',
      hidden: false },
      { type: 'string',
      key: 'vendor',
      displayName: 'Vendor',
      hidden: false },
      { type: 'enum',
      key: 'fy',
      displayName: 'Fiscal Year',
      options: 
       [ { key: 'FY17' },
       { key: 'FY18' },
       { key: 'FY19' } ],
      hidden: false } ] }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `scope` and `templateKey` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link>, or
  <Link href="/guides/metadata/instances/list">list all instances on an item</Link>.
</Info>

## Get a metadata template by ID

To get a metadata template by ID, you will need to pass the template's
`id` to the <Link href="/reference/get-metadata-templates-id">`GET
/metadata_templates/:id`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_templates/d9671692-3df6-11ea-b77f-2e728ce88125" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.getMetadataTemplateById(template.id);
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.get_metadata_template_by_id(template.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.GetMetadataTemplateByIdAsync(templateId: template.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.getMetadataTemplateById(templateId: template.id)
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().getMetadataTemplateById(template.getId())
  ```

  ```java Java v5 theme={null}
  MetadataTemplate template = MetadataTemplate.getMetadataTemplateByID(api, "37c0204b-3fe1-4a32-b9da-f28e88f4c4c6");
  ```

  ```py Python v4 theme={null}
  template = client.metadata_template_by_id(template_id='abcdef-fba434-ace44').get()
  print(f'The {template.displayName} template has {len(template.fields)} fields')
  ```

  ```csharp .NET v6 theme={null}
  BoxMetadataTemplate template = await client.MetadataManager
      .GetMetadataTemplateById("17f2d715-6acb-45f2-b96a-28b15efc9faa");
  ```

  ```js Node v4 theme={null}
  client.metadata.getTemplateByID('17f2d715-6acb-45f2-b96a-28b15efc9faa')
   .then(template => {
    /* template -> {
     id: '17f2d715-6acb-45f2-b96a-28b15efc9faa',
     templateKey: 'vcontract',
     scope: 'enterprise_12345',
     displayName: 'Vendor Contract',
     hidden: true,
     fields: 
     [ { type: 'date',
      key: 'signed',
      displayName: 'Date Signed',
      hidden: false },
      { type: 'string',
      key: 'vendor',
      displayName: 'Vendor',
      hidden: false },
      { type: 'enum',
      key: 'fy',
      displayName: 'Fiscal Year',
      options: 
       [ { key: 'FY17' },
       { key: 'FY18' },
       { key: 'FY19' } ],
      hidden: false } ] }
    */
   });
  ```
</CodeGroup>

<Info>
  To get the `id` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link>, or
  <Link href="/guides/metadata/instances/list">list all instances on an item</Link>.
</Info>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Metadata templates overview
Source: https://developer.box.com/guides/metadata/templates/index



A metadata template describes a set of key/value
pairs that can be assigned to a file or folder.

For example, an `invoiceData` template might hold data about an invoice, having
a field for the invoice ID as well as the customer ID.

A file or folder can have multiple distinct template <Link href="/guides/metadata/instances">instances</Link>
associated with it, such as a `marketingCollateral` instance and a
`retentionPolicy` instance.

## Metadata scopes

Metadata templates are grouped into two distinct groups, or **scopes**.

<Card href={localizeLink("/guides/metadata/scopes")} title="Learn more about Metadata Scopes" />

## Permissions and restrictions

There is a limit of 500 templates per enterprise.

Creating metadata templates is restricted to users with admin permission. This
means that only admins, or co-admins who have been granted rights to **Create
and edit metadata templates for your company** by the admin can use the web
app or the API to manage templates.

[template]: /guides/metadata/templates


# List all metadata templates
Source: https://developer.box.com/guides/metadata/templates/list



<RelatedLinks title="REQUIRED GUIDES" />

Metadata templates can be listed for either the <Link href="/guides/metadata/scopes">enterprise or the global
scope</Link>.

## List global templates

To list all global metadata templates, call the <Link href="/reference/get-metadata-templates-global">`GET
/metadata_templates/global`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_templates/global" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.getGlobalMetadataTemplates();
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.get_global_metadata_templates()
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.GetGlobalMetadataTemplatesAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.getGlobalMetadataTemplates()
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().getGlobalMetadataTemplates()
  ```

  ```java Java v5 theme={null}
  Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates('global', api);
  for (MetadataTemplate templateInfo : templates) {
      // Do something with the metadata template.
  }
  ```

  ```py Python v4 theme={null}
  templates = client.get_metadata_templates(scope='global)
  for template in templates:
      print(f'Metadata template {template.templateKey} is in global scope')
  ```

  ```csharp .NET v6 theme={null}
  BoxEnterpriseMetadataTemplateCollection<BoxMetadataTemplate> templates = await client.MetadataManager
      .GetEnterpriseMetadataAsync("global");
  ```

  ```js Node v4 theme={null}
  client.metadata.getTemplates('global')
   .then(templates => {
    // ...
   });
  ```
</CodeGroup>

<Info>
  This API returns a list of all the metadata templates created by Box and made
  available to all enterprises.
</Info>

## List current enterprise's templates

To list all metadata templates created for usage within the current
enterprise, call the <Link href="/reference/get-metadata-templates-enterprise">`GET  /metadata_templates/enterprise`</Link> API
endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/metadata_templates/enterprise" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.getEnterpriseMetadataTemplates();
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.get_enterprise_metadata_templates()
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.GetEnterpriseMetadataTemplatesAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.getEnterpriseMetadataTemplates()
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().getEnterpriseMetadataTemplates()
  ```

  ```java Java v5 theme={null}
  Iterable<MetadataTemplate> templates = MetadataTemplate.getEnterpriseMetadataTemplates(api);
  for (MetadataTemplate templateInfo : templates) {
      // Do something with the metadata template.
  }
  ```

  ```py Python v4 theme={null}
  templates = client.get_metadata_templates()
  for template in templates:
      print(f'Metadata template {template.templateKey} is in enterprise scope')
  ```

  ```csharp .NET v6 theme={null}
  BoxEnterpriseMetadataTemplateCollection<BoxMetadataTemplate> templates = await client.MetadataManager
      .GetEnterpriseMetadataAsync();
  ```

  ```js Node v4 theme={null}
  client.metadata.getTemplates('enterprise')
   .then(templates => {
    /* templates -> {
     limit: 100,
     entries: 
     [ { templateKey: 'documentFlow',
      scope: 'enterprise_12345',
      displayName: 'Document Flow',
      hidden: false,
      fields: 
       [ { type: 'string',
        key: 'currentDocumentStage',
        displayName: 'Current Document Stage',
        hidden: false }
       { type: 'string',
        key: 'needsApprovalFrom',
        displayName: 'Needs Approval From',
        hidden: false },
       { type: 'string',
        key: 'nextDocumentStage',
        displayName: 'Next Document Stage',
        hidden: false }
       { type: 'float',
        key: 'maximumDaysAllowedInCurrentStage',
        displayName: 'Maximum Days Allowed In Current Stage',
        hidden: false }
      { templateKey: 'marketingCollateral',
      scope: 'enterprise_12345',
      displayName: 'Marketing Collateral',
      hidden: false,
      fields: 
       [ { type: 'string',
        key: 'audience1',
        displayName: 'Audience',
        hidden: false },
       { type: 'string',
        key: 'previousState',
        displayName: 'Previous State',
        hidden: false } ] },
      { templateKey: 'productInfo',
      scope: 'enterprise_12345',
      displayName: 'Product Info',
      hidden: false,
      fields: 
       [ { type: 'float',
        key: 'skuNumber',
        displayName: 'SKU Number',
        hidden: false },
       { type: 'enum',
        key: 'department',
        displayName: 'Department',
        hidden: false,
        options: 
        [ { key: 'Beauty' },
        { key: 'Shoes' },
        { key: 'Accessories' },
        { key: 'Clothing' },
        { key: 'Handbags' },
        { key: 'Bedding' },
        { key: 'Watches' } ] },
       { type: 'date',
        key: 'displayDate',
        displayName: 'Display Date',
        hidden: false } ] } ],
     next_marker: null,
     prev_marker: null }
    */
   });
  ```
</CodeGroup>

<Info>
  This API returns a list of all the metadata templates created by this
  enterprise, and these templates are only available to apply to files in this enterprise.
</Info>

## Pagination

This API uses <Link href="/guides/api-calls/pagination/marker-based">marker-based pagination</Link> and can return a
`next_marker` value in the response body to indicate that more templates might
be available.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Update a metadata template
Source: https://developer.box.com/guides/metadata/templates/update



<RelatedLinks title="REQUIRED GUIDES" />

Updating a metadata template can be achieved by passing an array of operations
to the <Link href="/reference/put-metadata-templates-id-id-schema">`PUT /metadata_templates/:scope/:templateKey/schema`</Link> API.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/metadata_templates/enterprise/blueprintTemplate/schema" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json-patch+json" \
       -d '[
         {
           "op": "editField",
           "fieldKey": "category",
           "data": {
             "displayName": "Customer Group"
           }
         }
       ]'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.metadataTemplates.updateMetadataTemplate(
    'enterprise' as UpdateMetadataTemplateScope,
    templateKey,
    [
      {
        op: 'addField' as UpdateMetadataTemplateRequestBodyOpField,
        fieldKey: 'newfieldname',
        data: { ['type']: 'string', ['displayName']: 'newFieldName' },
      } satisfies UpdateMetadataTemplateRequestBody,
    ],
  );
  ```

  ```python Python v10 theme={null}
  client.metadata_templates.update_metadata_template(
      UpdateMetadataTemplateScope.ENTERPRISE,
      template_key,
      [
          UpdateMetadataTemplateRequestBody(
              op=UpdateMetadataTemplateRequestBodyOpField.ADDFIELD,
              field_key="newfieldname",
              data={"type": "string", "displayName": "newFieldName"},
          )
      ],
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.MetadataTemplates.UpdateMetadataTemplateAsync(scope: UpdateMetadataTemplateScope.Enterprise, templateKey: templateKey, requestBody: Array.AsReadOnly(new [] {new UpdateMetadataTemplateRequestBody(op: UpdateMetadataTemplateRequestBodyOpField.AddField) { FieldKey = "newfieldname", Data = new Dictionary<string, object>() { { "type", "string" }, { "displayName", "newFieldName" } } }}));
  ```

  ```swift Swift v10 theme={null}
  try await client.metadataTemplates.updateMetadataTemplate(scope: UpdateMetadataTemplateScope.enterprise, templateKey: templateKey, requestBody: [UpdateMetadataTemplateRequestBody(op: UpdateMetadataTemplateRequestBodyOpField.addField, fieldKey: "newfieldname", data: ["type": "string", "displayName": "newFieldName"])])
  ```

  ```java Java v10 theme={null}
  client.getMetadataTemplates().updateMetadataTemplate(UpdateMetadataTemplateScope.ENTERPRISE, templateKey, Arrays.asList(new UpdateMetadataTemplateRequestBody.Builder(UpdateMetadataTemplateRequestBodyOpField.ADDFIELD).data(mapOf(entryOf("type", "string"), entryOf("displayName", "newFieldName"))).fieldKey("newfieldname").build()))
  ```

  ```java Java v5 theme={null}
  List<MetadataTemplate.FieldOperation> updates = new ArrayList<MetadataTemplate.FieldOperation>();

  String addCategoryFieldJSON = "{\"op\":\"addField\","\"data\":{"
      + "\"displayName\":\"Category\",\"key\":\"category\",\"hidden\":false,\"type\":\"string\"}}";
  updates.add(new MetadataTemplate.FieldOperation(addCategoryFieldJSON));

  String changeTemplateNameJSON = "{\"op\":\"editTemplate\",\"data\":{"
      + "\"displayName\":\"My Metadata\"}}";
  updates.add(new MetadataTemplate.FieldOperation(changeTemplateNameJSON));

  MetadataTemplate.updateMetadataTemplate(api, "enterprise", "myData", updates);
  ```

  ```py Python v4 theme={null}
  template = client.metadata_template('enterprise', 'employeeRecord')
  updates = template.start_update()
  updates.add_enum_option('state', 'WI')
  updates.edit_template({'hidden': False})
  updates.edit_template({'copyInstanceOnItemCopy': False})
  updated_template = template.update_info(updates=updates)
  ```

  ```csharp .NET v6 theme={null}
  var updates = new List<BoxMetadataTemplateUpdate>()
  {
      new BoxMetadataTemplateUpdate()
      {
          Op = MetadataTemplateUpdateOp.addEnumOption,
          FieldKey = "fy",
          Data = new {
              key = "FY20"
          }
      },
      new BoxMetadataTemplateUpdate()
      {
          Op = MetadataTemplateUpdateOp.editTemplate,
          Data = new {
              hidden = false
          }
      }
  };
  BoxMetadataTemplate updatedTemplate = await client.MetadataManager
      .UpdateMetadataTemplate(updates, "enterprise", "marketingCollateral");
  ```

  ```js Node v4 theme={null}
  // Add a new option to the Fiscal Year field, and un-hide the template
  var operations = [
   {
    op: 'addEnumOption',
    fieldKey: 'fy',
    data: { key: 'FY20' }
   },
   {
    op: 'editTemplate',
    data: { hidden: false }
   }
  ];
  client.metadata.updateTemplate('enterprise', 'vcontract', operations)
   .then(template => {
    /* template -> {
     templateKey: 'vcontract',
     scope: 'enterprise_12345',
     displayName: 'Vendor Contract',
     hidden: false,
     fields: 
     [ { type: 'date',
      key: 'signed',
      displayName: 'Date Signed',
      hidden: false },
      { type: 'string',
      key: 'vendor',
      displayName: 'Vendor',
      hidden: false },
      { type: 'enum',
      key: 'fy',
      displayName: 'Fiscal Year',
      options: 
       [ { key: 'FY17' },
       { key: 'FY18' },
       { key: 'FY19' },
       { key: 'FY20' } ],
      hidden: false } ] }
    */
   });
  ```
</CodeGroup>

<Warning>
  **Admin permissions required**

  Updating metadata templates is restricted to users with admin permission. This
  means that only admins, or co-admins who have been granted rights to **Create
  and edit metadata templates for your company** by the admin can use the web
  app or the API to manage templates.
</Warning>

## Operations

Updates to metadata templates are performed through **operations** rather than
directly changing the template itself. This method allows us to update any
existing metadata instances that are already applied to files and folders.

## Template operations

Template operations update a template's details or fields. These operations are
generally safe as they are applied to any template instance without much impact.

### Edit a template

The operation `editTemplate` allows for editing any of the base properties of
the template, like the `displayName`, `copyInstanceOnItemCopy` and more.

| Parameter | |
| - | - |
| `data` | An object representing the properties to change |

```json theme={null}
[
  {
    "op": "editTemplate",
    "data": {
      "displayName": "Client",
      "copyInstanceOnItemCopy": true
    }
  }
]
```

This will update the template to have a new display name of Client.

<Warning>
  This will affect existing instances of this template.
</Warning>

### Add a field to a template

The operation `addField` adds a field to a template.

| Parameter | |
| - | - |
| `data` | An object representing field to add |

```json theme={null}
[
  {
    "op": "addField",
    "data": {
      "displayName": "Category",
      "key": "category",
      "hidden": false,
      "type": "string"
    }
  }
]
```

This will add a new non-hidden string field with a `displayName` and `key` of
**category**.

<Warning>
  This will affect existing instances of this template.
</Warning>

### Reorder fields

The operation `reorderFields` reorders the list of fields in a template to match
the requested field list.

| Parameter | |
| - | - |
| `fieldKeys` | The new list of field keys in the requested order |

```json theme={null}
{
  "op": "reorderFields",
  "fieldKeys": ["field2", "field1", "field3"]
}
```

This will reorder the fields for the template to have `field2` first, followed
by `field1`, then `field3`.

<Warning>
  This will affect existing instances of this template. It will reorder the
  fields, yet keep the values of the fields intact.
</Warning>

## Field operations

Field operations transform the schema of a template. The following is a list of
operations that can be used in this API and can potentially change the data of
any previously assigned templates.

These changes will be logged as template changes but not as file changes.

### Edit a field

The operation `editField` edits any number of the base properties of a
field like the `displayName`, `description`, `key`, and `hidden` state.

| Parameter | |
| - | - |
| `data` | An object representing the new properties to set for the field |
| `fieldKey` | The key of the field to be edited |

```json theme={null}
{
  "op": "editField",
  "fieldKey": "category",
  "data": {
    "displayName": "Customer Group"
  }
}
```

This will update the field `category` to have a new display name of
**Customer Group**. If the key is changed, existing values of the specified
field are migrated to the new key. The search index will be updated, yet it may
take time depending on how many files are affected by the change.

<Warning>
  This may affect existing instances of this template.
</Warning>

### Remove a field

The operation `removeField` removes a field from a template.

| Parameter | |
| - | - |
| `fieldKey` | The key of the field to remove from the template |

```json theme={null}
{
  "op": "removeField",
  "fieldKey": "brand"
}
```

This will remove the field `brand` from the template as well as all instances of
the template. The search index will be updated, yet it may take time depending on
how many files are affected by the change.

<Warning>
  This will affect existing instances of this template.
</Warning>

## Field Option Operations

Both the <Link href="/guides/metadata/fields/enum">`enum`</Link> and
<Link href="/guides/metadata/fields/multi-select">`multiSelect`</Link> metadata field types support
some additional operations to change the options of the fields.

| Operation | |
| - | - |
| <Link href="/guides/metadata/fields/enum#add-an-option">`addEnumOption`</Link> | Adds an option to an `enum` field |
| <Link href="/guides/metadata/fields/enum#edit-an-option">`editEnumOption`</Link> | Edits an `enum` field option |
| <Link href="/guides/metadata/fields/enum#reorder-options">`reorderEnumOptions`</Link> | Re-orders the options on an `enum` field |
| <Link href="/guides/metadata/fields/enum#remove-an-option">`removeEnumOption`</Link> | Removes an `enum` field option |
| <Link href="/guides/metadata/fields/multi-select#add-an-option">`addMultiSelectOption`</Link> | Adds an option to a `multiSelect` field |
| <Link href="/guides/metadata/fields/multi-select#edit-an-option">`editMultiSelectOption`</Link> | Edits a `multiSelect` field option |
| <Link href="/guides/metadata/fields/multi-select#reorder-options">`reorderMultiSelectOptions`</Link> | Re-orders the options on a `multiSelect` field |
| <Link href="/guides/metadata/fields/multi-select#remove-an-option">`removeMultiSelectOption`</Link> | Removes a `multiSelect` field option |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box query
Source: https://developer.box.com/guides/query/box-query



The Box Query API lets you search for and find objects in Box. You can filter and sort results using metadata templates and item fields, so you can build detailed queries.

It goes beyond basic file and folder search and supports more types of Box items.

To create a query, call the POST [https://api.box.com/2.0/query](https://api.box.com/2.0/query) endpoint with query details.

## Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

| Parameter | Type | Description | Example |
| - | - | - | - |
| **`query.predicate`** | string | A filter for your query, in SQL-like syntax. Use `:parameter` placeholders for values. See supported operators for [metadata template fields](https://cloud.box.com/s/bkcwr35hypy4so1gvdza5x2vv16) and <Link href="/guides/metadata/queries/item-fields">item properties</Link>. | `"amount >= :value"` |
| `query.params` | object | Values for each `:placeholder` in the predicate. Each key matches the placeholder name without `:`. Value types must match the predicate fields. | `{ "value": 100 }` |
| `query.ancestors` | array | Limits results to items inside specific ancestors and their sub-items. Each object needs an `id` and `type` (such as `folder`). You need read access to every ancestor listed. | `[{ "id": "123", "type": "folder" }]` |
| `query.order_by` | array | How to sort results. Each object needs `field_key` and `direction` (`asc` or `desc`). Add multiple objects to sort by more than one field. | `[{ "field_key": "box:item:created_at", "direction": "desc" }]` |
| `limit` | integer | Maximum number of results to return. Default is 50. Must be between 0 and 100. | `50` |
| `fields` | array | Extra fields to include in each result. By default, results include only item type and ID. Each value can be an item field key or a metadata template or field key. | `["box:item:created_at", "enterprise_123:templateKey:someField"]` |
| `marker` | string | Token from a previous response to get the next page of results. Use only when continuing a previous request, and keep all other parameters the same. | `"AAAAAmVYB1FWec8GH6..."` |

## Examples

Query on two custom Metadata templates:

```json theme={null}
{
"query": {
	"predicate": "enterprise_12345678:contract:status = :contractStatus AND
enterprise_12345678:project:inceptionDate >= :date",
	"params": {
		"contractStatus": "Signed",
		"date": "2020-01-01T00:00:00Z"
	},
},
"order_by": [
{
	"field_key": "enterprise_12345678:project:projectId",
	"direction": "asc"
	},
	],
	"limit": 10,
	"include_total_count": true,
	"fields": [
		"box:item:name",
		"enterprise_12345678:project"
	]
}
```

Query on one custom metadata template and item information:

```json theme={null}
{
"query": {
	"predicate": "enterprise_12345678:inventory:book:purchasePrice >= :p1 AND
box:item:name = :name",
	"params": {
		"p1": 100,
		"name": "The Hobbit"
	},
	"ancestors": [
		"folder_789"
	],
},
"order_by": [
	{
		"field_key": "enterprise_12345678:inventory:book:purchasePrice",
		"direction": "asc"
	},
],
"limit": 1,
"include_total_count": true,
"fields": [
	"box:item:name",
	"enterprise_12345678:book"
	]
}
```

## Response

```json theme={null}
{
	"entries": [
		{
			"id": "12345",
			"type": "file",
			"box": {
				"item": {
					"name": "My Form"
				},
			},
		"enterprise_12345678": {
			"book": {
				"$id": "82ba3e97-496c-475d-85f2-078c690c434c",
				"$parent": "file_12345",
				"$scope": "enterprise_12345678",
				"$template": "book",
				"$type": "book-b52189dd-caa3-44e9-ba36-d31079bb10e6",
				"isbn": "1871263670",
				"purchasePrice": 234.57,
				"publicationYear": "1937"
			}
		}
	}
	],
	"next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=A="
}
```

## Response fields

| Field | Type | Description |
| - | - | - |
| **`entries`** | array | The list of items that match the query. Each object contains a type and ID for a single item matching the predicate. If a `fields` parameter is specified in the request, then additional item and/or metadata fields are provided. |
| **`next_marker`** | string or null | A token that can be used to get the next page of results. If there are no more results, this value is null. Otherwise, the value can be provided as the `marker` parameter to a follow up request to retrieve additional entries. |

<Note>
  Pagination uses markers, not snapshots. If you combine all pages, you may not get a complete
  list of matching items at one moment in time. New matches may appear after you start, and items from earlier pages can be missing from later pages if they are changed or deleted while you are fetching the results.
</Note>

## Error codes

| Error Code | Error Type | Error Message |
| - | - | - |
| `400` | `UNEXPECTED_JSON_TYPE` | Expected JSON with type string. |
| `400` | `INVALID_QUERY` | Failed to parse query: Unexpected end of input. |
| `400` | `INVALID_QUERY` | Scope is invalid. |
| `401` | `UNAUTHORIZED` | The provided access token is invalid. |
| `403` | `FORBIDDEN` | Query API found either too many items or too many inaccessible items matching the query. |
| `404` | `INSTANCE_NOT_FOUND` | The templates you referenced were not found. |
| `404` | `ITEM_NOT_FOUND` | Item not found. |
| `500` | `INTERNAL_SERVER_ERROR` | Internal server error. |


# Query insights
Source: https://developer.box.com/guides/query/insights



Query insights API lets you compute aggregated insights (sums, averages, counts, and more) over items that match a metadata-based query. The system applies the specified filters first, then performs aggregation based on the provided grouping criteria, if any.

To get insights, call the `POST https://api.box.com/2.0/query/insights` endpoint.

## Parameters

To make a call, you must pass the following parameters. The request body has two top-level fields: `query` and `metrics`. Mandatory parameters are in **bold**.

| Parameter | Type | Description | Example |
| - | - | - | - |
| **`query`** | object | Defines the filtering conditions and grouping parameters for an insights request. Holds `predicate`, `params`, `ancestors`, and `group_by` together (not mutually exclusive). | `ancestors` |
| **`query.predicate`** | string | Filters the dataset before the metric computation. The predicate syntax is similar to an SQL `WHERE` clause and can include parameterized arguments. | `enterprise_12345678:book:amount >= :value` |
| `query.params` | object | Must include a key for each placeholder, where the key matches the placeholder name without the `:` prefix. Value types must match the field types used in the predicate. **Required only if the predicate contains parameter placeholders** (for example, `:param`). | `{ "value": 100 }` |
| `query.ancestors` | array of objects | Filters results based on item ancestry. Each object needs an `id` and `type` (such as `folder`). Returns items contained within any of the specified ancestors. The user must have access to all provided ancestors, otherwise the request is rejected. If empty or omitted, insights are computed across all accessible items (root context, 0). | `[{ "id": "123", "type": "folder" }]` |
| `query.group_by` | array of objects | Specifies how data is grouped. Each entry defines a grouping field and an optional bucket limit. Only a single group-by field is currently supported. Grouping is applied after filters and before metric computation. Grouping on high-cardinality fields can error; keep cardinality below 10,000. | `[{ "field": "enterprise_12345678:book:category", "bucket_limit": 5 }]` |
| `query.group_by[].field` | string | Fully qualified field name to group by. Supported fields include metadata and item properties (see [supported field types](/guides/metadata/fields/index)). | `enterprise_12345678:book:category` |
| `query.group_by[].bucket_limit` | integer | Maximum number of buckets to return for the grouping. Defaults to 5, maximum allowed value is 10. | `5` |
| **`metrics`** | object (map) | A set of named metrics to compute. Each entry maps a user-defined alias to a metric operation applied to a field. Metrics are evaluated after filters (and grouping, if specified). Maximum 10 metrics in a request. | See examples below. |
| `metrics.<alias>.type` | string | Aggregation function to apply. Supported values: `sum`, `avg`, `min`, `max`, `count`. | `count` |
| `metrics.<alias>.field` | string | Fully qualified field name on which the metric is computed. | `enterprise_12345678:product:category` |

### Metric names

Each key in the `metrics` object is an alias defined by you for the metric.

**Naming convention**

* Must be a non-empty string
* Must be unique within the request
* Maximum length: 256 characters
* Allowed characters: letters (a–z, A–Z), digits (0–9), and special characters `_`, `-`, and `.`
* Must not start with a digit or special character
* Whitespace and other special characters are not allowed

**Behavior**

* If `group_by` is not specified, metrics are computed over the entire filtered dataset (ungrouped aggregation).
* If `metrics` is an empty object (), a default `totalResultCount` count metric is returned over the filtered dataset (see Total document count example).

## Examples

### Total contract value

Get total contract value and counts for top 3 contract types created in June 2025.

**Request:**

```json theme={null}
{
    "query": {
      "predicate": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2",
      "params": {
        "templateArg": "enterprise_12345678:sales",
        "dateArg1": "2025-06-01T00:00:00-07:00",
        "dateArg2": "2025-07-01T00:00:00-07:00"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ],
      "group_by": [
        {
          "field": "enterprise_12345678:sales:contractType",
          "bucket_limit": 3
        }
      ]
    },
    "metrics": {
      "totalContractValue": {
        "type": "sum",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "countContractType": {
        "type": "count",
        "field": "enterprise_12345678:sales:contractType"
      }
    }
  }
```

**Response:**

```json theme={null}
{
  "insights": [
    {
      "key": [ "ContractType1" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 180000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 245
          }
        }
      }
    },
    {
      "key": [ "ContractType4" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 100000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 185
          }
        }
      }
    },
    {
      "key": [ "ContractType2" ],
      "type": "group",
      "metrics": {
        "totalContractValue": {
          "type": "sum",
          "values": {
            "sum": 200000
          }
        },
        "countContractType": {
          "type": "count",
          "values": {
            "count": 150
          }
        }
      }
    },
    {
      "key": [],
      "type": "other",
      "metrics": {
        "totalCountBeyondTopGroups": {
          "type": "count",
          "values": {
            "count": 165
          }
        }
      }
    }
  ]
}
```

### Overall average, minimum, maximum contract value

Get overall average, minimum, and maximum contract value for contracts created in June 2025.

**Request:**

```json theme={null}
{
    "query": {
      "predicate": "EXISTS(:templateArg) AND box:item:created_at >= :dateArg1 AND box:item:created_at < :dateArg2",
      "params": {
        "templateArg": "enterprise_12345678:sales",
        "dateArg1": "2025-06-01T00:00:00-07:00",
        "dateArg2": "2025-07-01T00:00:00-07:00"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ]
    },
    "metrics": {
      "avgContractValue": {
        "type": "avg",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "minContractValue": {
        "type": "min",
        "field": "enterprise_12345678:sales:contractValue"
      },
      "maxContractValue": {
        "type": "max",
        "field": "enterprise_12345678:sales:contractValue"
      }
    }
  }
```

**Response:**

```json theme={null}
{
    "insights": [
      {
        "key": [],
        "type": "overall",
        "metrics": {
          "avgContractValue": {
            "type": "avg",
            "values": {
              "avg": 45055.50
            }
          },
          "minContractValue": {
            "type": "min",
            "values": {
              "min": 22000
            }
          },
          "maxContractValue": {
            "type": "max",
            "values": {
              "max": 75000
            }
          }
        }
      }
    ]
  }
```

### Total document count

Get total document count only by passing an empty metrics object.

**Request:**

```json theme={null}
{
    "query": {
      "predicate": "EXISTS(:templateArg)",
      "params": {
        "templateArg": "enterprise_12345678:sales"
      },
      "ancestors": [
        {
          "id": "123",
          "type": "folder"
        }
      ]
    },
    "metrics": {}
  }
```

**Response:**

```json theme={null}
{
    "insights": [
      {
        "key": [],
        "type": "overall",
        "metrics": {
          "totalResultCount": {
            "type": "count",
            "values": {
              "count": 12345
            }
          }
        }
      }
    ]
  }
```

## Response fields

| Field | Type | Description | Example |
| - | - | - | - |
| `insights` | array | The calculated results of the request. Each entry corresponds to a specific result type and contains the associated grouping keys (if applicable) and calculated metrics. | See below. |
| `insights.key` | array of objects | The grouping key values for the entry. Structure depends on the entry type. | See below. |
| `insights.key` | array of strings | One value for each `group_by` field. | `["Shoe"]` |
| `insights.type` | string | The type of insight entry. One of `group`, `overall`, or `other`. | `group` |
| `insights.metrics` | object | A map of the calculated metric results. Each key is a user-defined metric alias. Each value contains the metric type and its calculated values. The count metric for the other type is in the `totalCountBeyondTopGroups` key. | `"metrics": {"totalPrice": {"type": "sum","values": {"sum": 50}}` |

### Insight entry types

| Type | Description |
| - | - |
| `group` | Metrics for a specific group defined by `group_by`. `key` contains one value per `group_by` field, for example \["Shoe"] for category = `"Shoe"`. |
| `overall` | Metrics calculated across the entire dataset (no grouping). `key` is always an empty array `[]`. |
| `other` | Aggregated count for results outside the top returned groups. An empty array `[]` represents all remaining groups not included in the top results. |

## Bucket ordering

For requests with `group_by`, bucket ordering is implicit and always descending by item count (the number of documents in each bucket). The largest buckets are returned first. This ordering cannot be customized.

For the **Enum** and **Taxonomy** fields, deleted options can temporarily appear in top groups while the deletion job is in progress. Such groups have their keys shown as `[DELETED]`.

## Error codes

The list below is not exhaustive, additional error codes and details can be introduced as the API evolves.

| Error Code | Error Type | Error Message |
| - | - | - |
| `400` | `BAD_REQUEST` | Expected JSON with type string or *Failed to parse query: Unexpected end of input* message. Returned when the query cannot be parsed or an unexpected JSON is provided. |
| `401` | `UNAUTHORIZED` | The access token provided is invalid. Returned when an invalid or expired access token is used. |
| `403` | `FORBIDDEN` | Query is restricted for this enterprise/scope. |
| `404` | `INSTANCE_NOT_FOUND` | The templates you referenced were not found. |
| `429` | `RATE_LIMIT_EXCEEDED` | `EnterpriseId` is being rate limited. |
| `500` | `INTERNAL_SERVER_ERROR` | Internal server error. |


# Enterprise-wide search
Source: https://developer.box.com/guides/search/enterprise



By default, a search is only performed against the content that the
authenticated user has access to. In some cases, administrators might want to
search against all content owned by all users. For this use-case the `scope`
query parameter can be set to a value of `enterprise_content`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&scope=enterprise_content" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");
  searchParams.setScope("enterprise_content");

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", mdFilters: filters, scope: "enterprise_content");
  ```

  ```python Python theme={null}
  client.search().query("sales", metadata_filters=metadata_search_filters, scope="enterprise_content")
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          scope: "enterprise_content"
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

<Warning>
  The `enterprise_content` scope can be requested by an admin through our
  <Link href="/support">support channels</Link>. Once this scope has been enabled for a user, it
  will allow that user to query for content across the entire enterprise and not
  only the content that they have access to.
</Warning>


# Requesting extra fields
Source: https://developer.box.com/guides/search/fields



By default, the search API returns the **standard** format of a
<Link href="/reference/resources/file">File</Link>, <Link href="/reference/resources/folder">Folder</Link>, or <Link href="/reference/resources/web-link">Web Link</Link>. Each of
these resources supports additional fields that can be requested through the
`fields` query parameter.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&fields=name,tags" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  final List<String> fields = new ArrayList<String>();
  fields.add("name");
  fields.add("tags");
  searchParams.setFields(fields)

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  IEnumerable<string> fields = new List<string>() { "name", "tags"};
  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", fields: fields);
  ```

  ```python Python theme={null}
  client.search().query("sales", metadata_filters=metadata_search_filters, fields=["name", "tags"])
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          fields: "name,tags"
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

<Info>
  For more details on these fields, please check out the
  <Link href="/reference/resources/file--full">full File</Link>, <Link href="/reference/resources/folder--full">full Folder</Link>,
  and <Link href="/reference/resources/web-link">full Web Link</Link> resources.
</Info>

<Warning>
  When the `fields` parameter is used to query additional information about the
  items, only those fields and a few **base** fields (`id`, `type`, `name`, etc)
  are returned. Any fields that were originally in the response would now have to
  be requested explicitly.
</Warning>


# Filter search results
Source: https://developer.box.com/guides/search/filtering



The <Link href="/reference/get-search">`GET /search`</Link> API supports a variety of
different ways to filter the results returned by the API.

## Filter by content type

By default, a search returns items for which either the name, description, file
content, tags, or comments match the query provided. By setting the
`content_types` parameter the search can be narrowed down to only the items that
match the query for the content type defined.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&content_types=name,tags" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  final List<String> contentTypes = new ArrayList<String>();
  contentTypes.add("name");
  contentTypes.add("tags");
  searchParams.setContentTypes(contentTypes)

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  var contentTypes = new List<string>();
  contentTypes.Add("name");
  contentTypes.Add("tags");

  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", contentTypes: contentTypes);
  ```

  ```python Python theme={null}
  client.search().query("sales", content_types=["name", "tags"])
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          content_types:  [
              "name",
              "tags"
          ]
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

| Content type | |
| - | - |
| `name` | The name of the item, as defined by its `name` field. |
| `description` | The description of the item, as defined by its `description` field. |
| `file_content` | The actual content of the file. |
| `comments` | The content of any of the comments on a file or folder. |
| `tags` | Any tags that are applied to an item, as defined by its `tags` field. |

## Filter by date

By default, search returns files created at any time, and updated at any time.
It is possible to filter results by both the date the file or folder was
last updated or when it was created.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&created_at_range=2014-05-15T13:35:01Z,2015-05-15T13:35:01&updated_at_range=2014-05-15T13:35:01," \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  String createdFromDateString = "2014-05-15T13:35:01Z";
  String createdToDateString = "2015-05-15T13:35:01Z";
  Date createdFromDate = sdf.parse(createdFromDateString);
  Date createdToDate = sdf.parse(createdToDateString);
  DateRange createdRange = new DateRange(createdFromDate, createdToDate);
  searchParams.setCreatedRange(createdRange)

  String updatedFromDateString = "2014-05-15T13:35:01Z";
  Date updatedFromDate = sdf.parse(updatedFromDateString);
  DateRange updatedRange = new DateRange(updatedFromDate, null);
  searchParams.setUpdatedRange(updatedRange)

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  var createdAtRangeFromDate = new DateTime(1988, 11, 18, 9, 30, 0, DateTimeKind.Utc);
  var createdAtRangeToDate = new DateTime(2018, 11, 18, 9, 30, 0, DateTimeKind.Utc);
  var updatedAtRangeFromDate = new DateTime(1988, 11, 18, 9, 30, 0, DateTimeKind.Utc);

  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", contentTypes: contentTypes, createdAtRangeFromDate: createdAtRangeFromDate, createdAtRangeToDate: createdAtRangeToDate, updatedAtRangeFromDate: updatedAtRangeFromDate);
  ```

  ```python Python theme={null}
  client.search().query("sales", created_at_range=["2014-05-15T13:35:01Z", "2015-05-15T13:35:01Z"], updated_at_range=["2014-05-15T13:35:01Z", null])
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          created_at_range: "2014-05-15T13:35:01Z,2015-05-15T13:35:01Z",
          updated_at_range: "2014-05-15T13:35:01Z,"
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

| Query parameter | |
| - | - |
| `created_at_range` | Defines a range of `created_at` dates for which to return results. The upper or lower bound can be left empty to create an open-ended range. |
| `updated_at_range` | Defines a range of `updated_at` dates for which to return results. The upper or lower bound can be left empty to create an open-ended range. |

## Filter by file extension

By default, a search returns items with any kind of file extension. It is
possible to filter search results to only files with one or more specific file
extensions using the `file_extensions` query parameter.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&file_extensions=pdf,txt" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  final List<String> fileExtensions = new ArrayList<String>();
  fileExtensions.add("pdf");
  fileExtensions.add("txt");
  searchParams.setFileExtensions(fileExtensions)

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  var fileExtensions = new List<string>();
  fileExtensions.Add("pdf");
  fileExtensions.Add("txt");

  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", fileExtensions: fileExtensions);
  ```

  ```python Python theme={null}
  client.search().query("sales", file_extensions=["pdf", "txt"])
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          file_extensions:  [
              "pdf",
              "txt"
          ]
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

## Filter by file size

By default, a search returns items of any file size. It is
possible to filter search results to only files within a specific file
size using the `size_range` query parameter.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&size_range=10000,20000" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  SizeRange sizeRange = new SizeRange(10000, 20000);
  searchParams.setSizeRange(sizeRange);

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", sizeRangeLowerBoundBytes: 10000, sizeRangeUpperBoundBytes: 20000);
  ```

  ```python Python theme={null}
  client.search().query("sales", size_range=[10000,20000])
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          size_range: '10000,20000'
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

## Filter by file type

By default, a search returns files, folders, and web links. To narrow down
the results to only one of these, a `type` query parameter can be set to either
`file`, `folder` or `web_link`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&type=file" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");
  searchParams.setType("file");

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", type: "file");
  ```

  ```python Python theme={null}
  client.search().query("sales", type="file")
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          type: "file"
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

## Filter by metadata

It is possible to filter search results by their associated metadata, or even
perform entire searches based on only the metadata, all using the `mdfilters`
query parameter.

<Card href={localizeLink("/guides/search/quick-start")} title="Learn more about metadata filters" />

## Filter by owner

By default, a search returns all the items the authenticated user has access to,
regardless of who owns the items. To narrow down to only items owned by specific
users, use the `owner_user_ids` query parameter.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&owner_user_ids=34446362,462281242" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  final List<String> userIds = new ArrayList<String>();
  userIds.add("34446362");
  userIds.add("462281242");
  searchParams.setOwnerUserIds(userIds)

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  var userIds = new List<string>();
  userIds.Add("34446362");
  userIds.Add("462281242");

  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", ownerUserIds: userIds);
  ```

  ```python Python theme={null}
  client.search().query("sales", owner_user_ids=["34446362", "462281242"])
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          owner_user_ids: "34446362,462281242"
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

## Filter by parent folder

By default, a search returns all the items in any folder the user has access
to. To narrow down the results to only items in specific folders, use the
`ancestor_folder_ids` query parameter.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&ancestor_folder_ids=45235463,73445321" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  final List<String> folderIds = new ArrayList<String>();
  folderIds.add("45235463");
  folderIds.add("73445321");
  searchParams.setAncestorFolderIds(folderIds)

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  var folderIds = new List<string>();
  folderIds.Add("45235463");
  folderIds.Add("73445321");

  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", ancestorFolderIds: folderIds);
  ```

  ```python Python theme={null}
  client.search().query("sales", ancestor_folder_ids=["45235463", "73445321"])
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          ancestor_folder_ids: "45235463,73445321"
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>


# Search
Source: https://developer.box.com/guides/search/index



The Box API provides a way to find content in Box using
full-text search queries. Support for the Box search API is available
in all our supported SDKs and the CLI.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.search.searchForContent({
    ancestorFolderIds: ['0'],
    mdfilters: [
      {
        filters: searchFilters,
        scope: 'enterprise' as MetadataFilterScopeField,
        templateKey: templateKey,
      } satisfies MetadataFilter,
    ],
  } satisfies SearchForContentQueryParams);
  ```

  ```python Python v10 theme={null}
  client.search.search_for_content(
      ancestor_folder_ids=["0"],
      mdfilters=[
          MetadataFilter(
              filters=search_filters,
              scope=MetadataFilterScopeField.ENTERPRISE,
              template_key=template_key,
          )
      ],
  )
  ```

  ```java Java v10 theme={null}
  client.getSearch().searchForContent(new SearchForContentQueryParams.Builder().ancestorFolderIds(Arrays.asList("0")).mdfilters(Arrays.asList(new MetadataFilter.Builder().scope(MetadataFilterScopeField.ENTERPRISE).templateKey(templateKey).filters(searchFilters).build())).build())
  ```

  ```java Java v5 theme={null}
  // Find the first 10 files matching "taxes"
  long offsetValue = 0;
  long limitValue = 10;
  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("taxes");
  searchParams.setType("file");
  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```python Python v4 theme={null}
  items = client.search().query(query='TEST QUERY', limit=100, file_extensions=['pdf', 'doc'])
  for item in items:
      print(f'The item ID is {item.id} and the item name is {item.name}')
  ```

  ```cs .NET v6 theme={null}
  // Search for PDF or Word documents matching "Meeting Notes"
  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("Meeting Notes", fileExtensions: new { "pdf", "docx" });
  ```

  ```javascript Node v4 theme={null}
  // Search for PDF or Word documents matching "Mobile"
  client.search.query(
  	'Mobile',
  	{
  		fields: 'name,modified_at,size,extension,permissions,sync_state',
  		file_extensions: 'pdf,doc',
  		limit: 200,
  		offset: 0
  	})
  	.then(results => {
  		/* results -> {
  			total_count: 1,
  			entries: 
  			[ { type: 'file',
  				id: '11111',
  				sequence_id: '1',
  				etag: '1',
  				sha1: 'f89d97c5eea0a68e2cec911s932eca34a52355d2',
  				name: 'Box for Sales - Empowering Your Mobile Worker White paper 2pg (External).pdf',
  				description: '',
  				size: 408979,
  				path_collection: 
  					{ total_count: 2,
  					entries: 
  					[ { type: 'folder',
  						id: '0',
  						sequence_id: null,
  						etag: null,
  						name: 'All Files' },
  						{ type: 'folder',
  						id: '22222',
  						sequence_id: '1',
  						etag: '1',
  						name: 'Marketing Active Work' } ] },
  				created_at: '2014-05-17T12:59:45-07:00',
  				modified_at: '2014-05-17T13:00:20-07:00',
  				trashed_at: null,
  				purged_at: null,
  				content_created_at: '2014-05-17T12:58:58-07:00',
  				content_modified_at: '2014-05-17T12:58:58-07:00',
  				created_by: 
  					{ type: 'user',
  					id: '33333',
  					name: 'Example User',
  					login: 'user@example.com' },
  				modified_by: 
  					{ type: 'user',
  					id: '33333',
  					name: 'Example User',
  					login: 'user@example.com' },
  				owned_by: 
  					{ type: 'user',
  					id: '33333',
  					name: 'Example User',
  					login: 'user@example.com' },
  				shared_link: null,
  				parent: 
  					{ type: 'folder',
  					id: '22222',
  					sequence_id: '1',
  					etag: '1',
  					name: 'Marketing Active Work' },
  				item_status: 'active' } ],
  			limit: 200,
  			offset: 0 }
  		*/
  	});
  ```
</CodeGroup>

<Note>
  Explore the <Link href="/reference/get-search">reference documentation</Link> to learn more
  about all the different features available to the search API.
</Note>

## Query operators

The search API supports a few different
<Link href="/guides/search/query-operators">search operators</Link>, including
`AND`, `OR`, `NOT` and `""`. These operators can be used to refine the search
results to only return items that match a more complicated combination of
search terms.

```sh theme={null}
curl -i -X GET "https://api.box.com/2.0/search?query=box%20AND%20sales" \
    -H "Authorization: Bearer <ACCESS_TOKEN>"
```

<Card href={localizeLink("/guides/search/query-operators")} title="Learn more about using logical operators" />

## Search indexing

Box keeps a search index for any files or folders stored in Box.
Every time a file or folder is changed, those words are added to
the index. When a search is performed, the API looks in the search
index for files and folders that match the query. When content is added,
updated, or deleted in Box, the search index is updated accordingly.

<Card href={localizeLink("/guides/search/indexing")} title="Learn more about the Box search index" />

<Info>
  In some cases an index might not be updated even after a few seconds.
  In those cases we recommend reaching out to [Box Support][support]
  to get the issue resolved.
</Info>

<Warning>
  If your enterprise has full text search turned off
  (e.g. [Keysafe][keysafe] customers), characters within a document
  cannot be searched. If you need to find out if full
  text search is turned off, reach out to your account team.
</Warning>

## Comparison to Metadata Queries

At the surface the search API seems very similar
to the <Link href="/guides/metadata/queries">Metadata Query API</Link>, but there are several important differences
in how they operate. At a high level the Metadata Queries are
optimized for exactness and throughput, while regular search is optimized
for relevance to a human user.

| | <Link href="/reference/post-metadata-queries-execute-read">Metadata Query API</Link> | <Link href="/reference/get-search">Search API</Link> |
| - | - | - |
| What is indexed? | This API only returns files/folders based on the values in the metadata templates that are searched | This API returns files, folders and web links based on values in the item names, descriptions, contents (up to the first 10,000 bytes) as well as the associated metadata template instances |
| Indexing time | This API will return accurate results as soon as metadata has been added, removed, updated or deleted for a file or folder | This API is subject to a search indexing delay, which is typically a few seconds yet may be longer in some cases. This means that items may not be returned for more than a few seconds after metadata has been updated |
| Matching | This API uses exact matching based on SQL conventions. Results are returned based on a specified sort order | This API uses fuzzy matching and may return results that vary based on string tokenization, removal of special characters, and other search concepts. Result order is based on either relevance or the updated date of the item |
| Conditional logic | This API supports multi-part boolean expressions with comparison operators | This API has limited support for querying by metadata. It only supports querying 1 metadata template at a time and only allows simple query operations. |
| Response type | This API returns both the matched file/folder and the associated metadata matched by the query | This API only returns the matched item. A subsequent API call is needed to return each item's metadata |
| Throughput | This API is currently subject to per-user rate limits and to a 10 requests per second per enterprise limit | This API supports 6 searches per second per user, up to 60 searches per minute and 12 searches per second per enterprise |
| Scale | This API has no limit on the number of items with the specified metadata template that can be returned. It is recommended to only send queries which match no more than 2,000 results. | This API has no limit on number of items with the specified metadata template that can be returned, yet the response time increases significantly as the number of items matching the search grows. This API does have a limit of up to 10 million results for a query. It is recommended to only send queries which match no more than 50,000 results. |
| Scope | This API is always limited to the content to which the user has access | This API may be either limited to the content to which the user has access (`​user_content​`) or to all content in the enterprise (`​enterprise_content​`). |

<Card href={localizeLink("/guides/metadata/queries/comparison")} title="Learn more about the metadata query API" />

[support]: /support

[keysafe]: https://www.box.com/security/keysafe


# Search indexing
Source: https://developer.box.com/guides/search/indexing



Box keeps a search index for any files or folders stored in Box.
Every time a file or folder is changed, those words are added to the index.
When a search is performed, the API looks in the search index for files and
folders that match the query. When content is added, updated, or deleted in
Box, the search index is updated accordingly.

## Search Availability

It can take time between uploading or modifying a
file for it to be fully indexed and ready to be searched. In most cases,
newly added or changed files can be expected to be available via Box search
in seconds. The current service load determines the index time and it may
take more than a few seconds in some cases.

<Info>
  In some cases an index might not be updated even after a few seconds.
  In those cases we recommend reaching out to [Box Support][support]
  to get the issue resolved.
</Info>

## Search Access

Only content that the authenticated user has access to
(items they can preview and/or view) will be returned in the search results.

In other words, a user needs to either own an item or be collaborated in on an
item for it to show up in the search results. If a user doesn't have access to
an item, or if they have been shared the item via a shared link, then the item
will also not appear in the search results.

One exception is that items that have been recently accessed via a shared link
can be requested in the search results by setting the
`include_recent_shared_links` query parameter to `true`.

## Prefix Matching and Wildcard Search

Trailing wildcards (also known as
prefix matching) are implicitly included in search results because of the way
text is indexed. Searching for `Bo` results in items with titles containing
`Box` or `Boat` or `Boxer`. It is the equivalent of searching for `Bo*` or
`Bo%` in traditional search engines. Traditional wildcard notation is not
supported by Box, such as `%ox%`. While we support prefix matching on titles,
we do not support prefix matching on body content, suffix matching in the
title or body content, or infix (middle of the word) matching in the title or
body content. For example, a search on `cal` would match results for a **file
named** `California` but not `decal` or `recall`. It would not match results
with **file body contents** of prefixes, infixes, or suffixes including
`California`, `recall`, or `decal`.

## Stemming

Box Search uses stemming to match terms from the query to terms
in the index. Because of this, words that include the same stem may be
included in the result set, even if the words do not contain the exact form
in the query. For example, `run` and `running` map to the same stem, so a
search on `running` may return a document containing `run` in the title.

## File Content Searching

The content within files is also stored
within the Box search index. The following file types allow searching for
their content:

| | | | | |
| - | - | - | - | - |
| `boxnote` | `csv` | `doc` | `docx` | `gdoc` |
| `gsheet` | `gslide` | `gslides` | `htm` | `html` |
| `msg` | `odp` | `odt` | `ods` | `pdf` |
| `ppt` | `pptx` | `rtf` | `tsv` | `wpd` |
| `xhtml` | `xls` | `xlsm` | `xlsx` | `xml` |
| `xsd` | `xsl` | `as` | `as3` | `asm` |
| `bat` | `c` | `cc` | `cmake` | `cpp` |
| `cs` | `css` | `cxx` | `diff` | `erb` |
| `groovy` | `h` | `haml` | `hh` | `java` |
| `js` | `json` | `less` | `log` | `m` |
| `make` | `md` | `ml` | `mm` | `php` |
| `pl` | `plist` | `properties` | `py` | `rb` |
| `rst` | `sass` | `scala` | `script` | `scm` |
| `sml` | `sql` | `sh` | `txt` | `vi` |
| `vim` | `webdoc` | `yaml` | | |

## Indexed Text per Document

The Box search index stores up to 10,000 bytes
(\~10,000 characters in English) per document for accounts from Business level
and above. This amount can vary from document to document because of
language, Box’s indexing method, and document type.

<Warning>
  If your enterprise has full text search turned off
  (e.g. [Keysafe][keysafe] customers), characters within a document
  cannot be searched. If you need to find out if full
  text search is turned off, reach out to your account team.
</Warning>

## OCR Support

Box does not currently perform OCR on its documents.

## Document Versions

Search only indexes content from the current version
of a document, so that you do not have to sift through hundreds of irrelevant
search results of outdated documents. You cannot use search to query
non-current versions of a document.

## Language Support

Box search supports the following languages: Chinese,
English, French, German, Italian, Japanese, and Spanish. Box does not support
indexing of multiple languages within a single document.

## Trash

Searching the trash is available via the API by using the
`trash_content` query parameter.

<Card href="https://support.box.com/hc/en-us/articles/360043696314-Search-for-Files-Folders-and-Content" title="Check our community article with the latest details on Search in Box" />

[support]: /support

[keysafe]: https://www.box.com/security/keysafe


# Metadata Query Filters
Source: https://developer.box.com/guides/search/metadata-filters



The <Link href="/reference/get-search">`GET /search`</Link> API allows for filtering search results by their
associated metadata. A `mdfilters` query parameter allows a developer to specify
a metadata template and the desired values to query.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&mdfilters=%5B%7B%22scope%22%3A%22enterprise%22%2C%22templateKey%22%3A%22contract%22%2C%22filters%22%3A%7B%22category%22%3A%22online%22%7D%7D%5D" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  BoxMetadataFilter bmf = new BoxMetadataFilter();
  bmf.setScope("enterprise");
  bmf.setTemplateKey("contract");
  bmf.setFilter("category", "online")
  searchParams.setMetadataFilter(bmf)

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  var filter = new
  {
      category = "online"
  };

  var filters = new List<BoxMetadataFilterRequest>()
  {
      new BoxMetadataFilterRequest()
      {
          Scope = "enterprise",
          TemplateKey = "contract",
          Filters: filter
      }
  };
  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", mdFilters: filters);
  ```

  ```python Python theme={null}
  from boxsdk.object.search import MetadataSearchFilter, MetadataSearchFilters

  metadata_search_filter = MetadataSearchFilter(scope='enterprise', template_key='contract')
  metadata_search_filter.add_value_based_filter(field_key='category', value='online')
  metadata_search_filters = MetadataSearchFilters()
  metadata_search_filters.add_filter(metadata_search_filter)

  client.search().query("sales", metadata_filters=metadata_search_filters)
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          mdfilters: [
              {
                  scope: 'enterprise',
                  templateKey: 'contract',
                  filters: {
                      category: 'online'
                  }
              }
          ]
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

<Info>
  This example filters a search for any content that matches the query `sales`
  by any item that has `enterprise.contract` metadata attached to it and where
  the `category` field is set to `online`.
</Info>

## Introduction to Metadata

Metadata allows users and applications to define and store custom data
associated with files and folders.

<Frame>
  <img alt="String field" />
</Frame>

Metadata consists of key/value pairs that are assigned to a file or a folder.
For example, an important contract may have the key/value pairs of
`clientNumber: 820183` and `category: online`.

The `mdfilters` query parameter allows developers to find files and folders that
have a specific piece of metadata attached to them.

<Card href={localizeLink("/guides/metadata")} title="Learn more about metadata templates and instances" />

## Metadata Filter Syntax

The `mdfilters` parameter can currently only contain one filter, although this
may be expanded in the future.

Each filter defines the `scope` and `templateKey` of the metadata template to
filter on.

```json theme={null}
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {}
  }
]
```

<Info>
  To get the `scope` and `templateKey` for a template, either
  <Link href="/guides/metadata/templates/list">list all metadata templates</Link> for an enterprise, or
  <Link href="/guides/metadata/instances/list">list all metadata instances on an item</Link>.
</Info>

With the template defined, the `filters` field accepts a few different filter
formats. The format of the filter very much depends on the type of field being
filtered by.

### Filter by `string` field

To filter by a field of type `string` a filter will need to define the `key` of
the field and the desired value to find items for.

```json theme={null}
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": "online"
    }
  }
]
```

<Info>
  This example will find all files and folders that have an instance of the
  `enterprise.contract` template applied to it, and for which the field with the
  key `category` is set to the value `online`.
</Info>

### Filter by `float` field

To filter by a field of type `float`, you will need to define a range by
specifying a `gt` (greater-than) and/or `lt` (lower-than) value. To find an
exact value, you can input the same value for both `gt` and `lt`.

```json theme={null}
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "amount": {
        "gt": 10000,
        "lt": 20000
      }
    }
  }
]
```

This example will find all files and folders that have an instance of the
`enterprise.contract` template applied to it, and for which the field with the
key `amount` is set to a value equal or higher than `10000` and equal or lower
than `2000`. Note that `gt` and `lt` are inclusive and do not need to
both be set.

<Info>
  If you create a query based on numbers, do not
  exceed the range of -16777215 and +16777215.
  For metadata search using number attributes
  the index value is stored as FLOAT32. As a result,
  integers between -16777215 and +16777215 can be precisely represented.
  Any operation with numbers beyond the range can lose its precision.
</Info>

### Filter by `date` field

To filter by a field of type `date` a filter will need to define the `key` of
the field and the desired range to find items by specifying a `gt`
(greater-than) and `lt` (lower-than) value. Please note that `gt` and `lt` are
inclusive.

```json theme={null}
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "expirationDate": {
        "gt": "2016-08-01T00:00:00Z",
        "lt": "2017-08-01T00:00:00Z"
      }
    }
  }
]
```

<Info>
  This example will find all files and folders that have an instance of the
  `enterprise.contract` template applied and have an `expirationDate` set to
  a date after or exactly `2016-08-01T00:00:00Z`
  and before or exactly `2017-08-01T00:00:00Z`.
</Info>

### Filter by `enum` field

To filter by a field of type `enum` a filter will need to define the `key` of
the field and the desired value to find items for.

```json theme={null}
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": "online"
    }
  }
]
```

<Info>
  This example will find all files and folders that have an instance of the
  `enterprise.contract` template applied to it, and for which the field with the
  key `category` is set to the value `online`.
</Info>

### Filter by `multiSelect` field

To filter by a field of type `multiSelect` a filter will need to define the
`key` of the field and any of the potential desired values to find items for.
When performing a search, the query will essentially perform an `OR` operation
to match any template where any of the provided values match this field.

```json theme={null}
[
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": [
        "online",
        "enterprise"
      ]
    }
  }
]
```

<Info>
  This example will find all files and folders that have an instance of the
  `enterprise.contract` template applied to it, and for which the field with the
  key `category` is set to the value `online` or `enterprise`.
</Info>


# Search result pagination
Source: https://developer.box.com/guides/search/pagination



The search API supports offset-based pagination using the `offset` and `limit`
query parameters. Marker-based pagination is not supported.

## API Pagination

To fetch the first page of search results, the API needs to be called
either without the `offset` parameter, or with the `offset` set to `0`. The
`limit` field is optional.

```sh theme={null}
curl https://api.box.com/2.0/search?query=sales&offset=0&limit=100 \
    -H "authorization: Bearer ACCESS_TOKEN"
```

To fetch the next page of entries the API needs to be called with
an `offset` parameter that equals the sum of the previous `offset` value and
limit returned in the previous result, `previous_offset + previous_limit`.

```sh theme={null}
curl https://api.box.com/2.0/search?query=sales&offset=100&limit=100 \
    -H "authorization: Bearer ACCESS_TOKEN"
```

<Note>
  Note that the `offset` should be increased by the previous `limit` and not by
  the size of the entries in the response array, as this may be less than the
  limit. Generally we advise using the value of the `limit` in the response
  object to increase the `offset` value.
</Note>

The final page of items has been requested when the next `offset` value exceeds
the `total_count` value in the response object. At this point there are no more
items to fetch.

<Card href={localizeLink("/guides/api-calls/pagination/offset-based")} title="Learn more about offset-based pagination" />

## SDK Pagination

Each of our SDKs has built-in support for API pagination. The following code
samples show how to use pagination in the search API.

<CodeGroup>
  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 50;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");

  PartialCollection<BoxItem.Info> page1 = boxSearch.searchRange(offsetValue, limitValue, searchParams);

  offsetValue += 50;
  PartialCollection<BoxItem.Info> page2 = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  BoxCollection<BoxItem> page1 = await client.SearchManager
      .QueryAsync("sales", limit: 50);
  BoxCollection<BoxItem> page2 = await client.SearchManager
      .QueryAsync("sales", limit: 50, offset: 50);
  ```

  ```python Python theme={null}
  page1 = client.search().query(query='sales', limit=50)
  page2 = client.search().query(query='sales', limit=50, offset=50)
  ```

  ```js Node theme={null}
  const page1 = await client.search.query('sales', {
      limit: 50
  })
  const page2 = await client.search.query('sales'. {
      limit: 50,
      offset: 50
  })
  ```
</CodeGroup>


# Query operators
Source: https://developer.box.com/guides/search/query-operators



The <Link href="/reference/get-search">`GET /search`</Link> API supports a variety of
different query operators to help refining the results returned
by the API.

All of these operations are passed into the `query` parameter when
creating the search.

## Exact matches with `""`

By wrapping a query in double quotes (`""`) only exact matches are
returned by the API. Exact searches do not return search matches
based on specific character sequences. Instead, they return
matches based on phrases, that is, word sequences.

For example, a search for `"Blue-Box"` may return search results
including the sequence `"blue.box"`, `"Blue Box"`, and `"Blue-Box"`;
any item containing the words `Blue` and `Box` consecutively, in
the order specified.

## Matching multiple terms with `AND`

When the `AND` operator is used, the search returns items that
contain both the search terms on the left and right of the operator.

For example, a search for `marketing AND BoxWorks` returns items
that have both `marketing` and `BoxWorks` within its text in any order.
It does not return a result that only has `BoxWorks` in its text.

## Matching either search term with `OR`

When the `OR` operator is used, the search returns items that
contain either the search terms on the left or right of the operator.

For example, a search for `marketing OR BoxWorks` returns a result that
has either `marketing` or `BoxWorks` within its text. Using this
operator is not necessary as we implicitly interpret multi-word
queries as `OR` unless another supported boolean term is used.

## Excluding search terms with `NOT`

When the `NOT` operator is used, the search returns items that
do not contain the term that follows the operator.

For example, a search for `marketing AND NOT BoxWorks` returns a result
that has only `marketing` within its text. Results containing
`BoxWorks` are omitted.

<Warning>
  Please note that we do not support lower case (that is,
  `and`, `or`, and `not`) or mixed case (that is, `And`, `Or`, and `Not`)
  operators.
</Warning>

<Card href="https://support.box.com/hc/en-us/articles/360043696314-Search-for-Files-Folders-and-Content" title="Check our community article with the latest details on Search in Box" />


# Add Metadata Template to a File
Source: https://developer.box.com/guides/search/quick-start/apply-template-to-file



<ProgressBar />

Your metadata template needs to be applied to at least one file to ensure
a result in step 4. There are two ways to add a metadata template to a file:
via the UI or via the API.

## UI

To apply metadata to a file using the UI, navigate to a file and open the
preview. Use the **Metadata** tab and click **Add**. Find the metadata template
created in step 1 and select a value. Ensure you click **Save**.

<Frame>
  <img alt="Select a Metadata Template" />

  <img alt="Select a Value" />
</Frame>

## API

To add a metadata template to a file you will need to use the
<Link href="/reference/post-files-id-metadata-id-id/">create metadata instance on a file endpoint</Link>. You will also
need the `scope` and `templateKey` template values from the previous step.
Below is an example of what the API call looks like to apply the same metadata
shown in the UI above.

<Frame>
  <img alt="Select a Metadata Template" />
</Frame>

<Next>I applied my template to at least one file</Next>


# Create a Metadata Template
Source: https://developer.box.com/guides/search/quick-start/create-metadata-template



<ProgressBar />

There are two ways to create a new metadata template: via the Admin Console or
via the API using an Admin Access Token. If you already have a metadata template
created that you would like to use you can skip to the next step.

## Admin Console

To create a template via the Admin Console, navigate to:

**Admin Console** > **Content** Tab > **Metadata** > **Create New**

<Frame>
  <img alt="Create Metadata Template" />
</Frame>

<Warning>
  The metadata feature is reserved for Business Plus accounts and above. To
  upgrade your account, please contact your Box account team.
</Warning>

Once you select **Create New**, you are brought to a form used to create a new
template, which is shown below. Select a **Dropdown-Single Select** format.

<Warning>
  Selecting a Dropdown-Multi Select format will change the structure of your query
  later on in this quick-start.
</Warning>

<Frame>
  <img alt="Metadata Template Form" />
</Frame>

## API

Creating a metadata template via the API requires an <Link href="/guides/authentication/tokens">Access Token</Link>
associated with a Box Admin or Co-Admin with permission to
**create and edit metadata templates for your company**. If you are not sure
who your token is associated with, make an API call to the
<Link href="/reference/get-users-me">get current user endpoint</Link>. The easiest way to obtain a token
meeting these requirements is to log in as an Admin or Co-Admin, pull up the
application in the [Developer Console][dc], and click
**Generate Developer Token** under the **Configuration** tab.
<Link href="/guides/authentication/tokens/developer-tokens">Developer tokens</Link> are always associated with the user logged into the
Developer Console when the button is clicked.

Using [Postman][postman] and the <Link href="/guides/tooling/postman">Box Postman Collection</Link>, below is
an example of what an API call looks like to create the same metadata template
created above using the Admin Console.

<Frame>
  <img alt="Create Template API Call" />
</Frame>

<Tip>
  If you would like to use a different template format than a Dropdown-Single
  Select, you will need to consult our reference documentation, as the body of the
  API call will differ from the example above.
</Tip>

The response to this API call provides crucial information you will need later.
If you created your template via the UI, you will learn how to obtain this
information in the next step.

<Next>I created a metadata template</Next>

[dc]: https://account.box.com/developers/console

[postman]: https://postman.com/


# Search content using metadata
Source: https://developer.box.com/guides/search/quick-start/index



The Box Metadata Query API enables programmatic search of Box content based
strictly on applied custom metadata values.

The structure of a metadata query is similar to that of a SQL query and allows
for Boolean operators, such as AND, OR, and NOT, as well as comparison or range
operators, such as equal to, greater-than, and less-than.

Some benefits of the Metadata Query API include:

* no indexing delay; query immediately after metadata creations, updates, and deletions
* ability to specify a sort order by one or more fields
* no limitation on the number of characters that are queryable
* queries return item properties and metadata instances

<Frame>
  <img alt="Metadata" />
</Frame>

## Overview

This guide will take you through the following steps.

1. <Link href="/guides/search/quick-start/create-metadata-template">Create a metadata template</Link>
2. <Link href="/guides/search/quick-start/locate-template-info">Locate information about the metadata template</Link> via API
3. <Link href="/guides/search/quick-start/apply-template-to-file">Apply the metadata template</Link> to at least one file
4. <Link href="/guides/search/quick-start/metadata-query-api">Construct a metadata query API call</Link> to obtain the content from step 3


# Locate Information about a Metadata Template
Source: https://developer.box.com/guides/search/quick-start/locate-template-info



<ProgressBar />

<Warning>
  If you created your metadata template using the API and have the successful
  response on hand, you can skip this step.
</Warning>

If you created your metadata template via the Admin Console, you will need to
obtain an <Link href="/guides/authentication/tokens">Access Token</Link> for an Admin or Co-Admin with permission to
**Create and edit metadata templates for your company**. As mentioned in
step 1, the easiest way to obtain a token meeting these requirements is to log
in as an Admin or Co-Admin, pull up the application in the
[Developer Console][dc], and click **Generate Developer Token** under the
**Configuration** tab.

Use this token to make an API call to the
<Link href="/reference/get-metadata-templates-enterprise/">list all metadata templates for enterprise endpoint</Link>, as shown
below. You should be able to find information about your template in the
response. Specifically, note the `scope` and `templateKey`.

<Frame>
  <img alt="List All Templates" />
</Frame>

<Next>I obtained the details about my template</Next>

[dc]: https://account.box.com/developers/console


# Use the Metadata Query API
Source: https://developer.box.com/guides/search/quick-start/metadata-query-api



<ProgressBar />

Finally, build a <Link href="/reference/post-metadata-queries-execute-read/">metadata query API call</Link>. Here is an example of what the
body of the API call looks like:

```json theme={null}
{
  "from": "enterprise_22201764.contact_role",
  "query": "departments = :departments",
  "query_params": {"departments": "legal"},
  "ancestor_folder_id": "0",
  "fields": ["id"]
}
```

This API call will return any file ID that meets the following criteria: 

* Has the Contact Role template applied
* Has a value of departments is legal
* Is located anywhere under the root folder, since "0" is the `ancestor_folder_id`

As you can see below, this results in a successful call showing information
about the file we added the template to in step 2.

<Frame>
  <img alt="Search Query Result" />
</Frame>

<Next>I found my content using a search query</Next>


# Next Steps
Source: https://developer.box.com/guides/search/quick-start/next-steps



<ProgressBar />

You've reached the end of this Quick Start guide. By now you should have taken
the following steps.

1. <Link href="/guides/search/quick-start/create-metadata-template">Created a metadata template</Link>
2. <Link href="/guides/search/quick-start/locate-template-info">Located information about the metadata template</Link> from step 1 via API
3. <Link href="/guides/search/quick-start/apply-template-to-file">Added a metadata template</Link> to at least one file
4. <Link href="/guides/search/quick-start/metadata-query-api">Used the metadata query API</Link> to locate the file(s) from step 3

## Next Steps

We recommend the following resources to learn more:

* <Link href="/guides/metadata/queries">Metadata query guide</Link>
* Review <Link href="/guides/metadata/queries/errors">common errors</Link> and <Link href="/guides/metadata/queries/limitations">limitations</Link>
* Reference documentation for the <Link href="/reference/post-metadata-queries-execute-read">metadata query</Link> API

Our SDKs that support the metadata query API:

* [Python SDK][python]
* [.NET SDK][node]
* [iOS SDK][ios]
* [Java SDK][java]
* [Node][node]

[node]: https://github.com/box/box-node-sdk/blob/3fcc0d8bbd1ca11f1a3a78d741e4572718af53f0/docs/metadata.md#query

[python]: https://github.com/box/box-python-sdk/blob/legacy/docs/usage/search.md#metadata-query

[ios]: https://github.com/box/box-ios-sdk/blob/c5ff8396e28c31fcf3c433f1b9e8f2f0d7a0e0db/docs/usage/search.md#metadata-search

[java]: https://github.com/box/box-java-sdk/blob/5e3a96c903fffa198c97e981ce75765a69bd6cb6/doc/metadata_template.md#execute-metadata-query

[node]: https://github.com/box/box-node-sdk/blob/3fcc0d8bbd1ca11f1a3a78d741e4572718af53f0/docs/metadata.md


# Finding recent shared links
Source: https://developer.box.com/guides/search/shared-links



By default, the search API only returns items that are either owned by the user
or items that the user has been explicitly collaborated on. These search results
do not include any items that a user might have accessed recently through a
shared link.

To enable shared links in the API, the `include_recent_shared_links` query
parameter can be set to `true`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&include_recent_shared_links=true" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```python Python theme={null}
  client.search().query("sales", metadata_filters=metadata_search_filters, include_recent_shared_links=True)
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          include_recent_shared_links: true
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

<Warning>
  Please be aware that this parameter is relatively new and therefore support for
  it in our Java and Windows SDKs is still a work in progress.
</Warning>

<Danger>
  Please be very aware that when this parameter has been set to true, the format
  of the response of this API changes to return a list of
  <Link href="/reference/resources/search-results-with-shared-links">Search Results with Shared Links</Link>
</Danger>


# Searching trash
Source: https://developer.box.com/guides/search/trash



By default, any content in the user's trash is ignored in the search results.
To search the user's trash, the `trash_content` query parameter can be set to
`trashed_only`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&trash_content=trashed_only" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  long offsetValue = 0;
  long limitValue = 10;

  BoxSearch boxSearch = new BoxSearch(api);
  BoxSearchParameters searchParams = new BoxSearchParameters();
  searchParams.setQuery("sales");
  searchParams.setTrashContent("trashed_only");

  PartialCollection<BoxItem.Info> searchResults = boxSearch.searchRange(offsetValue, limitValue, searchParams);
  ```

  ```csharp .NET theme={null}
  BoxCollection<BoxItem> results = await client.SearchManager
      .QueryAsync("sales", mdFilters: filters, trashContent: "trashed_only");
  ```

  ```python Python theme={null}
  client.search().query("sales", metadata_filters=metadata_search_filters, trash_content="trashed_only")
  ```

  ```js Node theme={null}
  client.search.query(
      'sales',
      {
          trash_content: "trashed_only"
      })
      .then(results => {
          // ...
      });
  ```
</CodeGroup>

<Info>
  Currently the API only supports searching for content not in the trash
  (`non_trashed_only`, default) or in the user's trash (`trashed_only`). It is
  currently not possible to search for items in both locations at once.
</Info>


# Webhooks overview
Source: https://developer.box.com/guides/webhooks/index

Monitor Box content for events and get notified at a URL of your choice, and compare V1 and V2 webhooks.

Webhooks allow you to monitor Box content for events, and receive notifications
to a URL of your choice when they occur. For example, a workflow may include
waiting for a file to be downloaded to delete a shared link. A webhook can be
set on the file and upon notification of the download event, a script can launch
to make an API call to delete the shared link.

<Frame>
  <img alt="Webhook developer console" />
</Frame>

## Versions

There are two types of webhooks: V1 and V2, which are compared below.

<Note>
  For the ease of use, better security, more event triggers to choose from,
  and automatic retries we recommend using V2 webhooks.
</Note>

| V1 | V2 |
| - | - |
| Created in the [Developer Console][console]. | Created in the [Developer Console][console] or with an API call. |
| Set at the root level. | Set on specific files/folders, but cannot set at the root. |
| Select from 14 event triggers. | Select from 30+ event triggers. |
| Provides selected callback parameters. | Payload includes full object response & additional context info. |
| No retry mechanism after notification delivery failure. | Retries up to 5 times after notification delivery failure. |
| Does not support payload verification. | Supports payload verification. |
| Notification URL can be HTTP or HTTPS. | Notification URL must be HTTPS. |
| Does not scale well. | Scales well and has increased reliability. |

[console]: https://app.box.com/developers/console

## Quick example

Create a V2 webhook that notifies your endpoint when a file is downloaded:

```bash theme={null}
curl -X POST https://api.box.com/2.0/webhooks \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "id": "FILE_ID", "type": "file" },
    "triggers": ["FILE.DOWNLOADED"],
    "address": "https://example.com/webhook"
  }'
```

<RelatedLinks title="RELATED APIS" />


# Webhook Event Triggers
Source: https://developer.box.com/guides/webhooks/triggers



## V2

### Files and Folders

The following is a list of events that can be configured to trigger a V2
webhook. Some events are only available for files, while others are only
available for folders.

| Event | Triggered | File? | Folder? |
| - | - | - | - |
| `COLLABORATION.CREATED` | A collaboration is created. | No | Yes |
| `COLLABORATION.ACCEPTED` | A collaboration is accepted. | No | Yes |
| `COLLABORATION.REJECTED` | A collaboration is rejected. | No | Yes |
| `COLLABORATION.REMOVED` | A collaboration is removed. | No | Yes |
| `COLLABORATION.UPDATED` | A collaboration is updated. | No | Yes |
| `COMMENT.CREATED` | A comment object is created. | Yes | Yes |
| `COMMENT.UPDATED` | A comment object is edited. | Yes | Yes |
| `COMMENT.DELETED` | A comment object is removed. | Yes | Yes |
| `DOCGEN_DOCUMENT_GENERATION_FAILED` | Doc Gen failed to generate a document. | Yes | No |
| `DOCGEN_DOCUMENT_GENERATION_STARTED` | Doc Gen started to create a document. | Yes | No |
| `DOCGEN_DOCUMENT_GENERATION_SUCCEEDED` | Doc Gen succeeded to create a document. | Yes | No |
| `FILE.UPLOADED` | A file is uploaded or moved to this folder. | No | Yes |
| `FILE.PREVIEWED` | A file is previewed. | Yes | Yes |
| `FILE.DOWNLOADED` | A file is downloaded. | Yes | Yes |
| `FILE.TRASHED` | A file is moved to trash. | Yes | Yes |
| `FILE.DELETED` | A file is permanently deleted. | Yes | Yes |
| `FILE.RESTORED` | A file is restored from trash. | Yes | Yes |
| `FILE.COPIED` | A file is copied. | Yes | Yes |
| `FILE.MOVED` | A file is moved from one folder to another. | Yes | Yes |
| `FILE.LOCKED` | A file is locked. | Yes | Yes |
| `FILE.UNLOCKED` | A file is unlocked. | Yes | Yes |
| `FILE.RENAMED` | A file is renamed. | Yes | Yes |
| `FOLDER.CREATED` | A folder is created. | No | Yes |
| `FOLDER.RENAMED` | A folder is renamed. | No | Yes |
| `FOLDER.DOWNLOADED` | A folder is downloaded. | No | Yes |
| `FOLDER.RESTORED` | A folder is restored from trash. | No | Yes |
| `FOLDER.DELETED` | A folder is permanently removed. | No | Yes |
| `FOLDER.COPIED` | A folder is copied. | No | Yes |
| `FOLDER.MOVED` | A folder is moved to a different folder. | No | Yes |
| `FOLDER.TRASHED` | A folder is moved to trash. | No | Yes |
| `METADATA_INSTANCE.CREATED` | A new metadata template instance is associated with a file or folder. | Yes | Yes |
| `METADATA_INSTANCE.UPDATED` | An attribute (value) is updated/deleted for an existing metadata template instance associated with a file or folder. | Yes | Yes |
| `METADATA_INSTANCE.DELETED` | An existing metadata template instance associated with a file or folder is deleted. | Yes | Yes |
| `SHARED_LINK.DELETED` | A shared link is deleted. | Yes | Yes |
| `SHARED_LINK.CREATED` | A shared link is created. | Yes | Yes |
| `SHARED_LINK.UPDATED` | A shared link is updated. | Yes | Yes |
| `TASK_ASSIGNMENT.CREATED` | A task is created. | Yes | Yes |
| `TASK_ASSIGNMENT.UPDATED` | A task assignment is changed. | Yes | Yes |
| `SIGN_REQUEST.COMPLETED` | A sign request is completed. | Yes | Yes |
| `SIGN_REQUEST.DECLINED` | A sign request is declined. | Yes | Yes |
| `SIGN_REQUEST.EXPIRED` | A sign request is expired. | Yes | Yes |
| `SIGN_REQUEST.SIGNER_EMAIL_BOUNCED` | A signer's email is bounced. | Yes | Yes |
| `SIGN_REQUEST.SIGNER_SIGNED` | A sign request is signed by a particular signer. | Yes | Yes |
| `SIGN_REQUEST.SIGNATURE_REQUESTED` | A signature is requested from a signer. | Yes | Yes |
| `SIGN_REQUEST.ERROR_FINALIZING` | An error occurred while finalizing a sign request. | Yes | Yes |
| `WEBHOOK.DELETED` | A webhook is deleted. | No | No |

## V1

Events that can be configured to trigger a v1 webhook:

* Sent,
* Created,
* Uploaded,
* Commented,
* Downloaded,
* Previewed,
* Moved,
* Copied,
* Task assigned,
* Responded to task,
* Locked,
* Unlocked,
* Deleted,
* Collaborator added.


# Create webhooks (v1)
Source: https://developer.box.com/guides/webhooks/v1/create-v1



<RelatedLinks title="REQUIRED GUIDES" />

V1 webhooks are created in the [Developer Console][devconsole] by following
the steps below.

1. Navigate to your application in the [Developer Console][devconsole].
2. Select the **Webhooks** tab.
3. Click the **Create a new Webhook** button.
4. Fill in the form, including event triggers, an endpoint URL and one or more callback parameters.
5. Click **Save Webhook**.

<Warning>
  **Callback parameters**

  Unlike the V2 Webhooks, these manual webhooks need to be configured with the
  data you'd like. This data will be sent as a query string either in the body
  or as a query parameter, for example `name=Contract.pdf&type=file`.
</Warning>

## Developer Mode

By default V1 webhooks only work for users that are listed as application
collaborators in the **General Settings** tab in the Developer Console. To
enable a webhook for all users, please [contact support][support].

## Enabling a webhook

After creating a webhook, the application must be added to the user's account
to begin use.

To obtain the URL to add the app, follow the directions below for OAuth 2.0
authentication apps:

1. Navigate to the **Integrations** tab for the application in the [Developer Console][devconsole].
2. Click **Submit My App**. Do not worry, you will not be completing the submission process!
3. At the bottom of the page, click **Preview**.
4. Click **Add**.

<Warning>
  For all other authentication types, you will need to contact support to
  obtain this URL.
</Warning>

Webhooks will now trigger for any configured events that occur in the user's
account.

[devconsole]: https://app.box.com/developers/console

[support]: https://support.box.com

<RelatedLinks title="RELATED GUIDES" />


# V1 Webhooks
Source: https://developer.box.com/guides/webhooks/v1/index



Webhooks created using the [Developer Console][console] monitor changes to all
files and folders within a user's account. When creating one of these webhooks
it is not possible to specify a specific object to bind the webhook to. To create
a webhook for a specific file or folder, you will need to leverage
<Link href="/guides/webhooks/v2">v2 webhooks</Link>.

<Warning>
  Webhooks created through this process will not show when listing all
  webhooks for a user via API call. All V1 webhooks are visible in the
  **Webhooks** tab in the [Developer Console][console].
</Warning>

[devconsole]: https://app.box.com/developers/console

[list_webhooks]: /guides/webhooks/v2/list-v2

[console]: https://app.box.com/developers/console


# Build with AI
Source: https://developer.box.com/ai



Build AI-powered applications with Box. Connect AI agents to your content
through MCP and Agent Skills, use the Box AI API for document intelligence, and
integrate Box with popular AI frameworks.

<SignupCTA>
  A free developer account gives you access to the Box AI API, Developer Console, and everything you need to start building AI-powered workflows.
</SignupCTA>

## Connect AI agents to Box

<CardGroup>
  <Card title="Box MCP server" href={localizeLink("/guides/box-mcp/index")} icon="server">
    Connect agents from Claude, Copilot Studio, and other platforms to Box
    through the Model Context Protocol.
  </Card>

  <Card title="Box Agent Skills" href={localizeLink("/ai/agent-skills")} icon="graduation-cap">
    Give your AI agents the context to build Box integrations, work with
    content using MCP tools, configure webhooks, and use Box AI retrieval.
  </Card>

  <Card title="Permission-aware agent access" href={localizeLink("/guides/box-mcp/permission-aware-access")} icon="shield-halved">
    Connect an agent as an authenticated Box identity. Scopes and file
    permissions still apply.
  </Card>
</CardGroup>

The [Box CLI](/guides/cli/index) also works with agentic tools and harnesses.
You can manage content, automate tasks, and integrate Box into scripts and AI agent
workflows from your terminal.

## Build and integrate

<CardGroup>
  <Card title="Box AI API" href={localizeLink("/ai/box-ai-api")} icon="sparkles">
    Summarize documents, answer questions, generate text, and extract metadata
    through a single API. Available to all Business customers and above.
  </Card>

  <Card title="AI integrations" href={localizeLink("/ai/integrations")} icon="puzzle-piece">
    Connect Box to LangChain, LlamaIndex, Pinecone, and other AI frameworks
    for RAG, vector search, and data pipelines.
  </Card>

  <Card title="RAG on Box content" href={localizeLink("/ai/rag")} icon="layer-group">
    Start with Hubs and Box AI Ask for permission-aware retrieval. Export to
    Pinecone, Weaviate, or LangChain when you need your own RAG stack.
  </Card>
</CardGroup>

## Tutorials

End-to-end walkthroughs that combine multiple Box AI capabilities into production-ready solutions.

<CardGroup>
  <Card title="Invoice intake automation" href={localizeLink("/tutorials/invoice-intake")} icon="file-invoice">
    Monitor a folder for new invoices, extract structured fields with Box AI, and write metadata back to each file.
  </Card>

  <Card title="RFP answer bank" href={localizeLink("/tutorials/sales-rfp-answer-bank")} icon="magnifying-glass">
    Build an AI-powered answer bank with Box Hubs and Box AI. Uses a sales RFP library as the example.
  </Card>

  <Card title="Access-controlled knowledge base" href={localizeLink("/guides/hubs-api/access-controlled-knowledge-base")} icon="book">
    Turn an enterprise document repository into a queryable Hub and ask questions with Box AI. Answers inherit Box permissions.
  </Card>
</CardGroup>


# AWS Claude Fable 5.1
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-fable-5-1-model-card



According to Anthropic, **AWS Claude Fable 5.1** extends Claude Fable 5 with stronger long-running agentic coding, multistep research, and document, spreadsheet, and slide work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Fable 5.1** | The name of the model. |
| Model category | **Ultra** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `aws__claude_fable_5_1` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **September 1st, 2026** | The release date for the model. |
| Knowledge cutoff date | **June 2026** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see <Link href="https://platform.claude.com/docs/en/models/fable-5-1/overview">official Anthropic Claude Fable 5.1 documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Fable 5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-fable-5-model-card



According to Anthropic, **AWS Claude Fable 5** is the most capable widely released model, built for the most demanding reasoning and long-horizon agentic work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Fable 5** | The name of the model. |
| Model category | **Ultra** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `aws__claude_fable_5` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **July 1st, 2026** | The release date for the model. |
| Knowledge cutoff date | **January 2026** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see <Link href="https://www.anthropic.com/claude/fable">official Anthropic Claude Fable documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Opus 5.5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-opus-5-5-model-card

Model details for AWS Claude Opus 5.5, a premium Anthropic model hosted on Amazon Web Services and available in Box AI.

**AWS Claude Opus 5.5** is an Anthropic model, hosted on Amazon Web Services, for agentic coding, knowledge work, and long-running tasks.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Opus 5.5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_opus_5_5` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **September 22nd, 2026** | The release date for the model. |
| Knowledge cutoff date | **June 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Opus 5.5 documentation][claude-opus-5-5].

[claude-opus-5-5]: https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-opus-5-5.html

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Opus 5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-opus-5-model-card



According to Anthropic, **AWS Claude Opus 5** is built for complex agentic coding and enterprise work, with the largest gains over Claude Opus 4.8 in deep reasoning, agentic and long-horizon tasks, and test-time compute scaling.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Opus 5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_opus_5` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **July 24th, 2026** | The release date for the model. |
| Knowledge cutoff date | **May 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Opus 5 documentation][claude-opus-5].

[claude-opus-5]: https://platform.claude.com/docs/en/about-claude/models/overview

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Sonnet 5.5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-sonnet-5-5-model-card



According to AWS, **AWS Claude Sonnet 5.5** is a smarter, more efficient Sonnet model that improves on Sonnet 5 for coding and knowledge work, at a lower cost per task for most work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Sonnet 5.5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `aws__claude_sonnet_5_5` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **September 28th, 2026** | The release date for the model. |
| Knowledge cutoff date | **June 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see the [AWS announcement for Claude Sonnet 5.5][aws-claude-sonnet-5-5].

[aws-claude-sonnet-5-5]: https://docs.aws.amazon.com/bedrock/latest/userguide/model-card-anthropic-claude-sonnet-5-5.html

<RelatedLinks title="RELATED GUIDES" />


# Azure text-embedding-ada-002
Source: https://developer.box.com/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card



According to Microsoft Azure, **Azure text-embedding-ada-002** is a multimodal model designed to handle lightweight tasks.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **text-embedding-ada-002** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `azure__openai__text_embedding_ada_002` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate, FedRAMP High, DoD IL2** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Microsoft Azure** | The trusted organization that securely hosts the LLM. |
| Model provider | **Microsoft Azure** | The organization that provides this model. |
| Release date | **December 2022** | The release date for the model. |
| Knowledge cutoff date | **September 2021** | The date after which the model does not get any information updates. |
| Input context window | **8k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **Not applicable** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **1000** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official Azure Embeddings models documentation][azure-ai-embeddings].

[azure-ai-embeddings]: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 2.5 Flash
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-2-5-flash-model-card



According to Google, **Google Gemini 2.5 Flash** is a multimodal model, offering well-rounded capabilities. It features thinking capabilities, which lets you see the thinking process the model goes through when generating its response.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 2.5 Flash** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_2_5_flash` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate, FedRAMP High, DoD IL5** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **June 17th 2025** | The release date for the model. |
| Knowledge cutoff date | **January 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Estimated between 163 - 300** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 2.5 Flash documentation][vertex-ai-gemini-models].

[vertex-ai-gemini-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 2.5 Pro
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-2-5-pro-model-card



According to Google, **Google Gemini 2.5 Pro** is a multimodal model capable of solving complex problems. It can comprehend vast datasets and challenging problems from different information sources, including text, audio, images, video, and even entire code repositories.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 2.5 Pro** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_2_5_pro` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate, FedRAMP High, DoD IL5** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **June 17th 2025** | The release date for the model. |
| Knowledge cutoff date | **January 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **65k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 2.5 Pro documentation][vertex-ai-gemini-2-5-pro].

[vertex-ai-gemini-2-5-pro]: https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-pro

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3.1 Flash Lite
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-1-flash-lite-model-card



According to Google, **Google Gemini 3.1 Flash Lite** is a multimodal model designed for high-speed, cost-efficient tasks like basic summarization, Q\&A, and structured data extraction. It is a standard-tier model suited to high-volume, low-complexity use cases.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3.1 Flash Lite** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_1_flash_lite` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP High** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **March 4th, 2026** | The release date for the model. |
| Knowledge cutoff date | **January 2025** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **65k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For more information, see <Link href="https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-1-flash-lite">official Google Gemini 3.1 Flash Lite documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3.1 Pro
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-1-pro-model-card



## Overview

According to Google, **Google Gemini 3.1 Pro** is designed for complex tasks, with advanced reasoning and a large context window for processing text, audio, images, video, and code.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3.1 Pro** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_1_pro` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **February 19th, 2026** | The release date for the model. |
| Knowledge cutoff date | **January 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **65k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see <Link href="https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-1-pro">official Google Gemini 3.1 Pro documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3.5 Flash Lite
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-5-flash-lite-model-card



According to Google, **Gemini 3.5 Flash Lite** is a cost-efficient and fast model, optimized for high-volume, latency-sensitive tasks like translation and classification, as well as supporting agentic workflows.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3.5 Flash Lite** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_5_flash_lite` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate, FedRAMP High, DoD IL4, DoD IL5** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **July 21st, 2026** | The release date for the model. |
| Knowledge cutoff date | **March 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 3.5 Flash Lite documentation][gemini-3-5-flash-lite].

[gemini-3-5-flash-lite]: https://deepmind.google/models/model-cards/gemini-3-5-flash-lite/

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3.5 Flash
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-5-flash-model-card



According to Google, **Gemini 3.5 Flash** is the next iteration in the Gemini 3 series of highly-capable, natively multimodal, reasoning models. Gemini 3.5 Flash is based on the Gemini 3 Flash reasoning foundation with thinking levels to control the mix of quality, cost and latency.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3.5 Flash** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_5_flash` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate, FedRAMP High, DoD IL4, DoD IL5** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **May 19th, 2026** | The release date for the model. |
| Knowledge cutoff date | **January 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 3.5 Flash documentation][gemini-3-5-flash].

[gemini-3-5-flash]: https://deepmind.google/models/model-cards/gemini-3-5-flash/

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3.6 Flash
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-6-flash-model-card



According to Google, **Gemini 3.6 Flash** is an addition to the Gemini 3 series of highly-capable, natively multimodal, reasoning models. Gemini 3.6 Flash is Google's workhorse model that delivers better coding, knowledge work, and multimodal performance, while providing better token-efficiency than Gemini 3.5 Flash.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3.6 Flash** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_6_flash` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **July 21st, 2026** | The release date for the model. |
| Knowledge cutoff date | **March 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 3.6 Flash documentation][gemini-3-6-flash].

[gemini-3-6-flash]: https://deepmind.google/models/model-cards/gemini-3-6-flash/

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3.7 Flash
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-7-flash-model-card



According to Google, **Gemini 3.7 Flash** is the next iteration in the Gemini 3 model family. It features algorithmic improvements to its core reasoning foundation and support for agentic video understanding.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3.7 Flash** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_7_flash` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate, FedRAMP High, DoD IL4, DoD IL5** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **August 13th, 2026** | The release date for the model. |
| Knowledge cutoff date | **March 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 3.7 Flash documentation][gemini-3-7-flash].

[gemini-3-7-flash]: https://deepmind.google/models/model-cards/gemini-3-7-flash/

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3.8 Flash
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-8-flash-model-card



According to Google, **Gemini 3.8 Flash** is the next iteration in the Gemini 3 model family, building on Gemini 3.7 Flash. It delivers performance advancements across software engineering and agentic knowledge workflows.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3.8 Flash** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_8_flash` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate, FedRAMP High, DoD IL4, DoD IL5** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **September 2nd, 2026** | The release date for the model. |
| Knowledge cutoff date | **March 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 3.8 Flash documentation][gemini-3-8-flash].

[gemini-3-8-flash]: https://deepmind.google/models/model-cards/gemini-3-8-flash/

<RelatedLinks title="RELATED GUIDES" />


# Google Gemini 3 Flash
Source: https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-flash-model-card



According to Google, **Google Gemini 3 Flash** is a natively multimodal model designed for speed and efficiency across a wide range of tasks. Delivers strong performance across text, image, and code generation while maintaining cost-effectiveness.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Google Gemini 3 Flash** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `google__gemini_3_flash` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Google** | The trusted organization that securely hosts the LLM. |
| Model provider | **Google** | The organization that provides this model. |
| Release date | **December 17th, 2025** | The release date for the model. |
| Knowledge cutoff date | **January 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **65k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official Google Gemini 3 Flash documentation][vertex-ai-gemini-3-flash].

[vertex-ai-gemini-3-flash]: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash


# Supported AI models
Source: https://developer.box.com/guides/box-ai/ai-models/index

Core and customer-enabled AI models available in Box AI, with access levels, capability tiers, and API names.

Box supports a variety of AI models, categorized along two dimensions: [access level](#access-levels) and [capability tier](#capability-tiers).

## Access levels

| Level | Description | Configuration Required |
| - | - | - |
| [**Core models**](#core-box-ai-models) | Built into Box AI and available by default for all customers | None |
| [**Customer-enabled models**](#customer-enabled-models) | Require activation by Box admins in the Admin Console or a request to Box. Some models may be subject to additional terms or pricing. | Yes |

## Capability tiers

| Tier | Description | Best For |
| - | - | - |
| **Standard models** | High-speed, cost-efficient performance | Basic summarization, Q\&A, structured data extraction from shorter or simpler documents. High-volume, low-complexity use cases |
| **Premium models** | Advanced reasoning, larger context windows, better performance on complex content | Multi-step reasoning, large taxonomies, lengthy or unstructured documents, domain-specific content |
| **Ultra models** | Highest-tier intelligence for complex, long-running, multi-step content work | Orchestrating long-running, multi-stage workflows, multiple knowledge bases, and deep domain-specific reasoning |

<Note>
  A model can be both customer-enabled and premium, or core and standard. In other words, access level and capability tiers are independent categorizations (for example, models can be either capability tier regardless of access level). The two categorizations are complementary.
</Note>

## Using models

How to use the supported AI models:

* Get the <Link href="/reference/get-ai-agent-default">default AI agent configuration</Link>.
* Override the AI agent configuration used in <Link href="/reference/post-ai-ask">`POST 2.0/ai/ask`</Link>, <Link href="/reference/post-ai-text-gen">`POST 2.0/ai/text_gen`</Link>, <Link href="/reference/post-ai-extract">`POST 2.0/ai/extract`</Link>, <Link href="/reference/post-ai-extract-structured">`POST 2.0/ai/extract_structured`</Link> endpoints.

When using the `model` parameter in your API calls, use the **API Name** visible on each model card listed below.

For example, to get the AI agent configuration for a specific model, use the <Link href="/reference/get-ai-agent-default#param-model">model</Link> parameter and provide the `openai__gpt_5_mini` API name. Make sure you use **two underscores** after the provider name.

<Note>
  The list may change depending on the model availability.
</Note>

<SignupCTA>
  A free developer account gives you access to these AI models through the Box AI API. Start making API calls to test summarization, extraction, and more.
</SignupCTA>

## Core models

Box AI is powered by the following AI models. These models are integrated with Box AI to facilitate various use cases while adhering to enterprise grade standards. Below, you’ll find information about each model, including its capabilities, intended applications, and applicable usage guidelines.

<Warning>
  Models offered in **Preview** mode have not been fully performance-tested at scale. You may experience variability in output quality, availability, and accuracy.
</Warning>

<AccordionGroup>
  <Accordion title="OpenAI">
    <Columns>
      <Card title="openai__gpt_6_1_sol" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-6-1-sol-model-card")}>
        Premium model in the GPT-6 family with near-Astra performance at a lower cost

        <span>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_6_sol" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-6-sol-model-card")}>
        Premium model in the GPT-6 family, built for complex, high-stakes professional work

        <span>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_6_luna" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-6-luna-model-card")}>
        Fast, cost-efficient model in the GPT-6 family for high-volume, general-purpose work

        <span>
          <Badge>Standard</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_6_astra" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-6-astra-model-card")}>
        Ultra model from OpenAI

        <span>
          <Badge>Ultra</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_6_sol" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-6-sol-model-card")}>
        Most capable GPT-5.6 model, built for complex, high-stakes professional work

        <span>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_6_terra" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-6-terra-model-card")}>
        Multimodal model for broad general-purpose work and most coding tasks

        <span>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_5" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-5-model-card")}>
        Advanced model for the most complex professional work

        <span>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_4" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-4-model-card")}>
        Multimodal model for both broad general-purpose work and most coding tasks

        <span>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_4_mini" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-4-mini-model-card")}>
        Faster, more cost-efficient version of GPT-5.4

        <span>
          <Badge>Standard</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_2" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-2-model-card")}>
        Multimodal model for coding and agentic tasks across various industries

        <span>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_1" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-1-model-card")}>
        Multimodal model with enterprise-grade performance and adaptive reasoning

        <span>
          <Badge>Premium</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-model-card")}>
        Multimodal model with advanced reasoning and long-context understanding

        <span>
          <Badge>Premium</Badge>
        </span>
      </Card>

      <Card title="openai__gpt_5_mini" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-5-mini-model-card")}>
        Model designed for well-defined tasks and precise prompts, suitable for lightweight tasks

        <span>
          <Badge>Standard</Badge>
        </span>
      </Card>

      <Card title="azure__openai__text_embedding_ada_002" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/azure-text-embedding-ada-002-model-card")}>
        2nd-generation embedding model for text search, code search, and sentence similarity

        <span>
          <Badge>Embeddings</Badge>
          <Badge>Standard</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>FedRAMP High</Badge>
          <Badge>DoD IL2</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Google">
    <Columns>
      <Card title="google__gemini_3_8_flash" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-8-flash-model-card")}>
        Fast, multimodal model for software engineering and agentic knowledge workflows

        <span>
          <Badge>Standard</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>FedRAMP High</Badge>
          <Badge>DoD IL4</Badge>
          <Badge>DoD IL5</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="google__gemini_3_7_flash" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-7-flash-model-card")}>
        Fast, multimodal model with improved reasoning and agentic video understanding

        <span>
          <Badge>Standard</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>FedRAMP High</Badge>
          <Badge>DoD IL4</Badge>
          <Badge>DoD IL5</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="google__gemini_3_5_flash" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-5-flash-model-card")}>
        Fast, multimodal model with advanced reasoning for demanding enterprise tasks

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>FedRAMP High</Badge>
          <Badge>DoD IL4</Badge>
          <Badge>DoD IL5</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="google__gemini_3_5_flash_lite" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-5-flash-lite-model-card")}>
        Multimodal model for high-speed, cost-efficient tasks

        <span>
          <Badge>Standard</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>FedRAMP High</Badge>
          <Badge>DoD IL4</Badge>
          <Badge>DoD IL5</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="google__gemini_3_1_flash_lite" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-1-flash-lite-model-card")}>
        Gemini multimodal model for high-speed and cost-efficient tasks

        <span>
          <Badge>Standard</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP High</Badge>
        </span>
      </Card>

      <Card title="google__gemini_2_5_pro" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-2-5-pro-model-card")}>
        Multimodal model with a 1 million token context window and advanced reasoning capabilities

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>FedRAMP High</Badge>
          <Badge>DoD IL5</Badge>
        </span>
      </Card>

      <Card title="google__gemini_2_5_flash" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-2-5-flash-model-card")}>
        Multimodal model offering well-rounded capabilities, including thinking capabilities

        <span>
          <Badge>Standard</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>FedRAMP High</Badge>
          <Badge>DoD IL5</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Anthropic">
    <Columns>
      <Card title="aws__claude_sonnet_5_5" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-sonnet-5-5-model-card")}>
        Smarter, more efficient Sonnet model for coding and knowledge work

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_opus_5_5" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-opus-5-5-model-card")}>
        Premium model for coding, knowledge work, and long-running tasks

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_opus_5" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-opus-5-model-card")}>
        Premium model built for complex reasoning and long-horizon agentic work

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_sonnet_5" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-sonnet-5-model-card")}>
        Powerful, versatile model built for daily use, scaled production, and complex tasks

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_4_8_opus" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-4-8-opus-model-card")}>
        Premium model from Anthropic, hosted on Amazon Web Services

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_4_7_opus" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-4-7-opus-model-card")}>
        Multimodal model for coding, enterprise agents, and professional work

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_4_6_opus" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-4-6-opus-model-card")}>
        Multimodal model for complex tasks with a 1 million token context window

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_4_6_sonnet" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-4-6-sonnet-model-card")}>
        Multimodal model for complex tasks with a 1 million token context window

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_4_5_opus" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-4-5-opus-model-card")}>
        Premium model combining maximum intelligence with practical performance

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_4_5_sonnet" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-4-5-sonnet-model-card")}>
        Model that excels at complex agents, coding, and autonomous multi-step workflows

        <span>
          <Badge>Premium</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_4_5_haiku" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-4-5-haiku-model-card")}>
        Fast and cost-efficient model with strong reasoning, best for low-latency applications

        <span>
          <Badge>Standard</Badge>
          <Badge>ISMAP</Badge>
          <Badge>FedRAMP Moderate</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Meta">
    <Columns>
      <Card title="ibm__llama_4_maverick" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/meta.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=f7b4cbde68a60d7c515774808c8d50d1" href={localizeLink("/guides/box-ai/ai-models/ibm-llama-4-maverick-model-card")}>
        Multimodal model with a 1 million token context window and advanced reasoning capabilities

        <span>
          <Badge>Standard</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Mistral AI">
    <Columns>
      <Card title="ibm__mistral_medium_2505" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/mistral.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=f130e27cd17d2cbcce4ad92affe1940b" href={localizeLink("/guides/box-ai/ai-models/ibm-mistral-medium-3-model-card")}>
        High-performance enterprise model for coding and advanced reasoning

        <span>
          <Badge>Preview</Badge>
          <Badge>Standard</Badge>
        </span>
      </Card>

      <Card title="ibm__mistral_small_3_1_24b_instruct_2503" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/mistral.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=f130e27cd17d2cbcce4ad92affe1940b" href={localizeLink("/guides/box-ai/ai-models/ibm-mistral-small-3-1-model-card")}>
        Fast open-source multimodal model with low latency

        <span>
          <Badge>Preview</Badge>
          <Badge>Standard</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>
</AccordionGroup>

## Customer-enabled models

Certain Box AI customers may enable additional AI models upon their request or upon the models otherwise being made available through their Admin Console. Use of these models may be subject to additional terms. By selecting a customer-enabled model, the customer acknowledges that their data may be processed by additional [subprocessors][subprocessors] of their choice.

<Warning>
  Models offered in **Beta** mode are provided on an as-is basis.
</Warning>

<AccordionGroup>
  <Accordion title="OpenAI">
    <Columns>
      <Card title="openai__gpt_o3" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/openai.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=84744284448f6109a9058cef53c3e01c" href={localizeLink("/guides/box-ai/ai-models/openai-gpt-o3-model-card")}>
        Multimodal model, highly efficient in handling complex, multi-step tasks

        <span>
          <Badge>Beta</Badge>
          <Badge>Premium</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Google">
    <Columns>
      <Card title="google__gemini_3_6_flash" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-6-flash-model-card")}>
        Natively multimodal reasoning model in the Gemini 3 Flash series

        <span>
          <Badge>Beta</Badge>
          <Badge>Premium</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="google__gemini_3_1_pro" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-1-pro-model-card")}>
        Model for complex tasks with advanced reasoning and a large context window

        <span>
          <Badge>Beta</Badge>
          <Badge>Premium</Badge>
        </span>
      </Card>

      <Card title="google__gemini_3_flash" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/gemini.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=0d2975259aaa026bd24aa72adedc55f6" href={localizeLink("/guides/box-ai/ai-models/google-gemini-3-flash-model-card")}>
        Multimodal model designed for speed and efficiency across a wide range of tasks

        <span>
          <Badge>Beta</Badge>
          <Badge>Standard</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Anthropic">
    <Columns>
      <Card title="aws__claude_fable_5_1" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-fable-5-1-model-card")}>
        Ultra model from Anthropic, hosted on Amazon Web Services

        <span>
          <Badge>Beta</Badge>
          <Badge>Ultra</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="aws__claude_fable_5" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/claude.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=bd3fefa10e30eac617a43ae7609ac43a" href={localizeLink("/guides/box-ai/ai-models/aws-claude-fable-5-model-card")}>
        Ultra model from Anthropic, hosted on Amazon Web Services

        <span>
          <Badge>Beta</Badge>
          <Badge>Ultra</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>

  <Accordion title="Meta">
    <Columns>
      <Card title="meta__muse_spark_1_3" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/meta.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=f7b4cbde68a60d7c515774808c8d50d1" href={localizeLink("/guides/box-ai/ai-models/meta-muse-spark-1-3-model-card")}>
        Multimodal model for general-purpose text and image understanding

        <span>
          <Badge>Beta</Badge>
          <Badge>Standard</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>

      <Card title="meta__muse_spark_1_2" icon="https://mintcdn.com/box/ZIWJfhT3Dv9f-PF4/static/guides-box-ai-ai-models/meta.svg?fit=max&auto=format&n=ZIWJfhT3Dv9f-PF4&q=85&s=f7b4cbde68a60d7c515774808c8d50d1" href={localizeLink("/guides/box-ai/ai-models/meta-muse-spark-1-2-model-card")}>
        Multimodal model for general-purpose text and image understanding

        <span>
          <Badge>Beta</Badge>
          <Badge>Standard</Badge>
          <Badge>Compatible with Box Agent</Badge>
        </span>
      </Card>
    </Columns>
  </Accordion>
</AccordionGroup>

## Legacy agents

Legacy agents represent the initial generation of Box AI capabilities, designed to handle basic, single-step tasks such as simple Q\&A and document summarization. The table below specifies available models for a particular use case.

| Use case | Provider | Model for Standard Version | Model for Advanced or Enhanced Version |
| - | - | - | - |
| Q\&A for Documents, Notes, and Hubs | OpenAI (Default) | <Link href="/guides/box-ai/ai-models/openai-gpt-5-mini-model-card">GPT-5 mini</Link> | <Link href="/guides/box-ai/ai-models/openai-gpt-5-2-model-card">GPT-5.2</Link> |
| | Claude | <Link href="/guides/box-ai/ai-models/aws-claude-4-5-sonnet-model-card">Claude 4.5 Sonnet</Link> | <Link href="/guides/box-ai/ai-models/aws-claude-4-5-opus-model-card">Claude 4.5 Opus</Link> |
| | Llama | <Link href="/guides/box-ai/ai-models/ibm-llama-4-maverick-model-card">Llama 4 Maverick</Link> | <Link href="/guides/box-ai/ai-models/ibm-llama-4-maverick-model-card">Llama 4 Maverick</Link> |

## Box agents

Box agents are the next generation of intelligent assistants built with advanced reasoning and orchestration, capable of planning and executing complex, multi-step workflows across your entire Box content ecosystem. The table below specifies available models for each specialized agent type.

| Agent | Model for Standard Version | Model for Enhanced Version |
| - | - | - |
| Extract Agent | <Link href="/guides/box-ai/ai-models/google-gemini-3-1-flash-lite-model-card">Gemini 3.1 Flash Lite</Link> | <Link href="/guides/box-ai/ai-models/google-gemini-3-7-flash-model-card">Gemini 3.7 Flash</Link> |
| Security Classification Agent | <Link href="/guides/box-ai/ai-models/google-gemini-3-1-flash-lite-model-card">Gemini 3.1 Flash Lite</Link> | N/A |
| Threat Analysis Agent | <Link href="/guides/box-ai/ai-models/google-gemini-3-5-flash-lite-model-card">Gemini 3.5 Flash Lite</Link> | N/A |

## Retired models

The following models are retired and no longer available in Box AI.

| Model name | API name |
| - | - |
| Azure OpenAI GPT-4.1 | `azure__openai__gpt_4_1` |
| Azure OpenAI GPT-4.1 mini | `azure__openai__gpt_4_1_mini` |
| Azure OpenAI GPT-4o | `azure__openai__gpt_4o` |
| Azure OpenAI GPT-4o mini | `azure__openai__gpt_4o_mini` |
| Claude 4 Opus | `aws__claude_4_opus` |
| Claude 4 Sonnet | `aws__claude_4_sonnet` |
| Titan Text Lite | `aws__titan_text_lite` |
| Gemini 2.0 Flash | `google__gemini_2_0_flash_001` |
| Gemini 2.0 Flash Lite | `google__gemini_2_0_flash_lite_preview` |
| Gemini 3 Pro | `google__gemini_3_pro` |
| Llama 4 Scout | `ibm__llama_4_scout` |
| Llama 3.2 90B Vision | `ibm__llama_3_2_90b_vision_instruct` |
| Grok 3 Beta | `xai__grok_3_beta` |
| Grok 3 mini Beta | `xai__grok_3_mini_beta` |

[azure-ai-mini-4o-model]: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models?tabs=python-secure#gpt-4o-and-gpt-4-turbo

[vertex-ai-model]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#models

[vertex-ai-gemini-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models#gemini-models

[vertex-text-models]: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/text

[azure-ai-embeddings]: https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#embeddings

[aws-claude]: https://aws.amazon.com/bedrock/claude/

[aws-titan]: https://aws.amazon.com/bedrock/titan/

[subprocessors]: https://www.box.com/legal/subprocessors


# OpenAI GPT-5.1
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-1-model-card



According to OpenAI, **OpenAI GPT-5.1** is a multimodal model designed for coding and agentic tasks with configurable reasoning effort.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5.1** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_1` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **November 13th, 2025** | The release date for the model. |
| Knowledge cutoff date | **September 30th, 2024** | The date after which the model does not get any information updates. |
| Input context window | **400k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-5.1 documentation][openai-gpt-5-model].

[openai-gpt-5-model]: https://platform.openai.com/docs/models/gpt-5.1


# OpenAI GPT-5.2
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-2-model-card



According to OpenAI, **OpenAI GPT-5.2** is a multimodal model designed for complex tasks that require broad world knowledge.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5.2** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_2` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **December 11th, 2025** | The release date for the model. |
| Knowledge cutoff date | **August 31st, 2025** | The date after which the model does not get any information updates. |
| Input context window | **400k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-5.2 documentation][openai-gpt-5-model].

[openai-gpt-5-model]: https://platform.openai.com/docs/models/gpt-5.2


# OpenAI GPT-5.4 mini
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-4-mini-model-card



According to OpenAI, **OpenAI GPT-5.4 mini** brings the strengths of GPT-5.4 to a faster, more efficient model designed for high-volume workloads.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5.4 mini** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_4_mini` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **March 17th, 2026** | The release date for the model. |
| Knowledge cutoff date | **August 31st, 2025** | The date after which the model does not get any information updates. |
| Input context window | **400k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-5.4 mini documentation][openai-gpt-5-4-mini].

[openai-gpt-5-4-mini]: https://developers.openai.com/api/docs/models/gpt-5.4-mini

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-5.4
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-4-model-card



According to OpenAI, **OpenAI GPT-5.4** is a frontier model, unifying the Codex and GPT lines into a single system. It features a 1m+ token context window with support for text and image inputs, enabling high-context reasoning, coding, and multimodal analysis within the same workflow.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5.4** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_4` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **March 5th, 2026** | The release date for the model. |
| Knowledge cutoff date | **August 31st, 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see <Link href="https://platform.openai.com/docs/models/gpt-5.4">official OpenAI GPT-5.4 documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-5.5
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-5-model-card



According to OpenAI, **OpenAI GPT-5.5** is a frontier model for the most complex professional work. It raises the baseline for complex production workflows. It is a strong fit for coding use cases, tool-heavy agents, grounded assistants, long-context retrieval, product-spec-to-plan workflows, and customer-facing workflows where execution quality and response polish are critical.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5.5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_5` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **April 23, 2026** | The release date for the model. |
| Knowledge cutoff date | **December 01, 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see <Link href="https://platform.openai.com/docs/models/gpt-5.5">official OpenAI GPT-5.5 documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-5.6 Sol
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-6-sol-model-card



According to OpenAI, **OpenAI GPT-5.6 Sol** is the frontier model in the GPT-5.6 family. It roughly corresponds to the unsuffixed model tier used in earlier GPT-5 families.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5.6 Sol** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_6_sol` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **July 9th, 2026** | The release date for the model. |
| Knowledge cutoff date | **February 16th, 2026** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-5.6 Sol documentation][openai-gpt-5-6-sol].

[openai-gpt-5-6-sol]: https://developers.openai.com/api/docs/models/gpt-5.6-sol

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-5.6 Terra
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-6-terra-model-card



According to OpenAI, **OpenAI GPT-5.6 Terra** is designed for workloads that balance intelligence and cost. It roughly corresponds to the mini model tier used in earlier GPT-5 families.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5.6 Terra** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_6_terra` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **July 9th, 2026** | The release date for the model. |
| Knowledge cutoff date | **February 16th, 2026** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-5.6 Terra documentation][openai-gpt-5-6-terra].

[openai-gpt-5-6-terra]: https://developers.openai.com/api/docs/models/gpt-5.6-terra

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-5 mini
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-mini-model-card



According to OpenAI, **OpenAI GPT-5 mini** is a faster, more cost-efficient version of GPT-5 ideal for well-defined tasks and precise prompts.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5 mini** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5_mini` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **August 7th, 2025** | The release date for the model. |
| Knowledge cutoff date | **May 31st, 2024** | The date after which the model does not get any information updates. |
| Input context window | **400k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-5 mini documentation][openai-gpt-5-mini-model].

[openai-gpt-5-mini-model]: https://platform.openai.com/docs/models/gpt-5-mini


# OpenAI GPT-5
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-model-card



According to OpenAI, **OpenAI GPT-5** is a multimodal model with advanced reasoning and long-context understanding.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_5` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **August 7th, 2025** | The release date for the model. |
| Knowledge cutoff date | **October 2024** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **100k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-5 documentation][openai-gpt-5-model].

[openai-gpt-5-model]: https://openai.com/index/introducing-gpt-5/

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-6.1 Sol
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-6-1-sol-model-card

Model card for OpenAI GPT-6.1 Sol, including API name, context window, and Box AI override details.

According to OpenAI, **OpenAI GPT-6.1 Sol** offers near-Astra performance for complex coding, computer use, and professional work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-6.1 Sol** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `openai__gpt_6_1_sol` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **September 29th, 2026** | The release date for the model. |
| Knowledge cutoff date | **April 30th, 2026** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI models documentation][openai-models].

[openai-models]: https://developers.openai.com/api/docs/models

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-6 Astra
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-6-astra-model-card

Model card for OpenAI GPT-6 Astra, including API name, context window, and Box AI override details.

According to OpenAI, **OpenAI GPT-6 Astra** is their most capable model, built for the hardest end-to-end work. It is designed for complex reasoning, coding, computer use, research, and document creation.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-6 Astra** | The name of the model. |
| Model category | **Ultra** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `openai__gpt_6_astra` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **September 4th, 2026** | The release date for the model. |
| Knowledge cutoff date | **April 30th, 2026** | The date after which the model does not receive information updates. |
| Input context window | **1,050,000 tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-6 Astra documentation][openai-gpt-6-astra].

[openai-gpt-6-astra]: https://developers.openai.com/api/docs/models/gpt-6-astra

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-6 Luna
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-6-luna-model-card

Model card for OpenAI GPT-6 Luna, including API name, context window, and Box AI override details.

According to OpenAI, **OpenAI GPT-6 Luna** is a fast, cost-efficient model in the GPT-6 family, designed for high-volume, general-purpose work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-6 Luna** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `openai__gpt_6_luna` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **September 22nd, 2026** | The release date for the model. |
| Knowledge cutoff date | **May 18th, 2026** | The date after which the model does not receive information updates. |
| Input context window | **1,050,000 tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-6 Luna documentation][openai-gpt-6-luna].

[openai-gpt-6-luna]: https://developers.openai.com/api/docs/models/gpt-6-luna

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT-6 Sol
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-6-sol-model-card

Model card for OpenAI GPT-6 Sol, including API name, context window, and Box AI override details.

According to OpenAI, **OpenAI GPT-6 Sol** is a premium model in the GPT-6 family, built for complex, high-stakes professional work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT-6 Sol** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `openai__gpt_6_sol` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **September 22nd, 2026** | The release date for the model. |
| Knowledge cutoff date | **April 20th, 2026** | The date after which the model does not receive information updates. |
| Input context window | **1,050,000 tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT-6 Sol documentation][openai-gpt-6-sol].

[openai-gpt-6-sol]: https://developers.openai.com/api/docs/models/gpt-6-sol

<RelatedLinks title="RELATED GUIDES" />


# OpenAI GPT o3
Source: https://developer.box.com/guides/box-ai/ai-models/openai-gpt-o3-model-card



According to OpenAI, **OpenAI GPT o3** is specifically designed to tackle reasoning and problem-solving tasks with increased focus and capability. It spends more time processing and understanding the user's request, making it exceptionally strong in areas like science, coding, and math compared to previous iterations.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **GPT o3** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `openai__gpt_o3` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **OpenAI** | The trusted organization that securely hosts the LLM. |
| Model provider | **OpenAI** | The organization that provides this model. |
| Release date | **April 16th, 2025** | The release date for the model. |
| Knowledge cutoff date | **May 2024** | The date after which the model does not get any information updates. |
| Input context window | **200k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **100k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official OpenAI GPT o3 documentation][openai-o3-model].

[openai-o3-model]: https://openai.com/index/introducing-o3-and-o4-mini/


# Get started with Box Automate
Source: https://developer.box.com/guides/box-automate/getting-started-box-automate



## Enable Box Automate

Your Box admin must <Link href="https://support.box.com/hc/en-us/articles/51190675028499-Enabling-Box-Automate"> enable Box Automate </Link> (and any add-on products you use in flows,
such as Box AI Studio) for the enterprise to begin using Automate. If a scope or
feature is not available in the Developer Console, contact Box Support or your
account team with the user or app context you plan to use.

## Manual Start API

You can trigger Manual Start workflows programmatically using the Box API.

| Endpoint | Method | Description |
| - | - | - |
| List workflows with Manual Start trigger | GET | Retrieve all Automate workflows with a Manual Start trigger set for a given folder. Returns a workflow list. Folder ID is required. |
| Trigger a Manual Start workflow | POST | Trigger a specific workflow with chosen files. |

### Request Parameters:

* `files` - provide file IDs in the request body (optional if triggering on a folder; max 20 files per request)
* `fields defined at start` - when a workflow requires runtime fields (for example, task assignees, notification recipients), include them in the API call. Missing required fields return an error.

Use the Custom HTTP Request outcome to connect your Box Automate workflows to external apps and APIs.

The HTTPS request outcome is available for all Enterprise Advanced users with Automate enabled.
However, your Admin needs to either add Connectors to the allow-list in settings or enable you
to add your own from the builder.

<Note>
  Note: If your admin has turned off the option to add your own connectors,
  you can only select from pre-approved connectors in the dropdown.
</Note>

**To add a Custom HTTP request outcome:**

1. Open Workflow Builder.
2. Add the Custom HTTP request outcome.
3. Fill in the fields:

* URL: Choose a connector, or add a new one if allowed.
* Method: Select GET, POST, DELETE, PUT, or PATCH.
* Query Parameters: Add any key-value pairs you need.
* Authentication: Choose an auth type and enter the required info.
* Headers: Add optional headers.
* Body: Enter the JSON request body.
* Description: Briefly say what the request does.

**Authentication options:**

* OAuth 2.0 Client Credentials: Client ID, Client Secret, Authorization URL, Token URL, Scopes
* Basic Auth: Username and password
* Bearer Token: Token
* API Key: API key
* Custom Header: Header name and value

**Test Your Connection**

1. After configuring your outcome, click the Test button.
2. Review the test response code to confirm the connection works.
3. The builder automatically captures response properties and creates variables for you.
4. Use the JSON path: [https://jsonpath.com/](https://jsonpath.com/) to verify and see the variables from the test response.

<RelatedLinks title="RELATED GUIDES" />


# Box Automate
Source: https://developer.box.com/guides/box-automate/index



<Note>
  Box Automate availability depends on your Box plan and how your organization
  enables the product. Work with your Box admin or account team before building
  integrations against production content.
</Note>

Box Automate is a workflow automation platform built natively on the Box content
platform. You can use it to design, build, and run automated workflows with a
visual builder that supports conditional branching, loops, and a broad set of
triggers and actions. This overview summarizes what the platform can do, how
developers can integrate with it, and which Box APIs and scopes
you are to use alongside workflows.

## Capabilities

* **Triggers** — File, folder, task, File Request, Box Sign, metadata triggers, Forms submissions manual, webhook events can start workflows.
* **Outcomes** — File and folder outcomes, collaborations, task assignments, Workflows can assign tasks, send notifications, AI outcomes, Integrations, and metadata.
* **Logic** — Branching, variables, JSONPath, and structured AI output help route work and pass data between steps.
* **AI** — Custom agents can use knowledge sources, citations, and reasoning traces where those features are enabled for your enterprise.

## Use cases

Box Automate fits document-centric processes that combine content, people, and
policy. Common examples include:

* **Approvals and reviews** — Route files for review, capture outcomes, and notify stakeholders.
* **Case and project folders** — React to uploads or metadata changes and kick off the next step automatically.
* **AI-assisted triage** — Classify or summarize incoming content, then branch on the result.
* **Cross-product flows** — Combine uploads (for example, File Request), metadata, Doc Gen, or Sign in one automation.

## Developer integrations

Automations run on Box content. Most integrations use a
<Link href="/guides/applications/platform-apps">platform application</Link>,
standard OAuth or JWT auth, and a mix of workflow APIs plus the content and
collaboration endpoints.
Start with
<Link href="/guides/box-automate/getting-started-box-automate">Get started with Box Automate</Link>.

## Rate limits

Workflow and content API calls are subject to Box rate limits. See the
<Link href="/guides/api-calls/permissions-and-errors/rate-limits">rate limits guide</Link>
for details.

<RelatedLinks title="RELATED GUIDES" />


# Triggers, outcomes, and logic in Box Automate
Source: https://developer.box.com/guides/box-automate/triggers-and-logic



Box Automate runs **workflows**: directed graphs of steps that start from a
**trigger** and run **outcomes** until an end state is reached. In the workflow
builder, you place **triggers** and **outcomes** on a canvas; outcomes are the
automated steps the workflow performs (this guide uses **outcomes** for the same
idea when talking about integration). Triggers are content-aware and can be scoped
to folders or metadata. Exact trigger and action types available in your tenant
depend on product configuration.

## Triggers

A trigger defines when a new **run** of a workflow should begin.

### Common trigger types

* **File events** — When a file is uploaded, moved, copied, downloaded, or deleted; also preview, lock, unlock, watermark removed, add collaborator, classification applied, or file-with-metadata scenarios.
* **Folder events** — When a folder is created, moved, copied, downloaded, or deleted, or when a collaborator is added.
* **Tasks** — When a general task or an approval task completes (including accepted or rejected approval outcomes).
* **File Request** — When someone completes a File Request form and submits content to the designated Box folder.
* **Box Sign** — Sign events such as completed, declined, expired, or cancelled.
* **Metadata** — When a specific metadata template is applied to a specific file or folder.
* **Manual start** — A user starts the flow from the file or folder in the Box web app.
* **Form submissions** — If enabled for your plan (for example Enterprise Advanced+), a workflow starts when a designated Box Form is submitted.
* **HTTPS request** — An external system starts a run by sending an HTTP request to a **unique URL** that Box Automate assigns to the workflow.

## Outcomes

**Outcomes** are the steps that run after a trigger fires (called **outcomes** in
the builder). You can chain multiple outcomes and pass data between steps with
variables.

**Key outcome capabilities**

* **File outcomes** — Move, copy, rename, delete, lock, unlock, add or remove watermark, add or remove collaborators, apply classification, and related file operations.
* **Folder outcomes** — Create, move, copy, rename, delete, restore, add or remove collaborators, apply classification, and related folder operations.
* **Collaboration** — Add or remove collaborators on files or folders dynamically.
* **Task assignments** — Assign approval tasks or general tasks to users or groups, with instructions and due dates.
* **Notifications** — Send email to recipients; subject and body can use variables (for example the person who started the workflow).
* **AI and advanced** — Box AI for metadata extraction, summarization, or Q\&A; options such as document generation (DocGen) and requesting signatures (Box Sign). Prefer an approval or review step after AI steps when results must be verified.
* **Metadata** — Apply, update, or extract metadata (including with AI) for files and folders. Treat agent output as potentially unpredictable and add human review before critical next steps when needed.

## Logic

Workflow logic controls branching and data flow between steps.

* **Branching** — Route the workflow on conditions (for example, if an approval task is rejected, move content to a different folder than if it were approved).
* **Loops**
  * **For each** — Iterate over a list of users, files, or all files in a folder.
  * **Loop back (go back)** — Return the flow to a previous step, with a configurable maximum loop count.
* **Variables** — Reuse information from earlier steps in later outcomes (for example, a rename step can use a metadata value from a prior AI step or the name of the user who uploaded the file).
* **Merging** — After parallel branches, merge back to a single path before a final outcome.

When integrating through an HTTPS request,
you may also use **conditions** on field values, metadata, or structured AI
output; **JSONPath** or similar approaches to read nested payload fields; and
**AI outputs** as inputs to conditions or downstream outcomes where supported.

<RelatedLinks title="RELATED GUIDES" />


# Get Workflows
Source: https://developer.box.com/guides/box-relay/get-workflows



The <Link href="/reference/get-workflows">get workflows</Link> endpoint can be used to grab all workflows on a
particular folder. It will return all workflows regardless of if there is a
flow of type `WORKFLOW_MANUAL_START`.

<Note>
  For more information on how to use these endpoints, refer to our [blog][blog]
  post.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/workflows?folder_id=324234" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await adminClient.workflows.getWorkflows({
    folderId: workflowFolderId,
  } satisfies GetWorkflowsQueryParams);
  ```

  ```python Python v10 theme={null}
  admin_client.workflows.get_workflows(workflow_folder_id)
  ```

  ```cs .NET v10 theme={null}
  await adminClient.Workflows.GetWorkflowsAsync(queryParams: new GetWorkflowsQueryParams(folderId: workflowFolderId));
  ```

  ```swift Swift v10 theme={null}
  try await adminClient.workflows.getWorkflows(queryParams: GetWorkflowsQueryParams(folderId: workflowFolderId))
  ```

  ```java Java v10 theme={null}
  adminClient.getWorkflows().getWorkflows(new GetWorkflowsQueryParams(workflowFolderId))
  ```
</CodeGroup>

[blog]: https://medium.com/box-developer-blog/manual-start-workflow-api-box-relay-4f8d0f51b7a4


# Box Relay
Source: https://developer.box.com/guides/box-relay/index



[Box Relay][boxrelay] is a workflow automation application that enables Box
power users to automate and accelerate business processes centered
around content. Currently, there are two API <Link href="/reference/resources/workflow">endpoints</Link> developers
can use with more planned to be released in the future. Both were created to
work directly with [manual start flows][manualstart].

<Note>
  For more information on how to use these endpoints, refer to our [blog][blog]
  post.
</Note>

## Required Scopes

The following <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link> must be enabled for an application before use of
Box Relay's endpoints.

* <Link href="/guides/api-calls/permissions-and-errors/scopes/#read-all-files-and-folders">Read all files and folders stored in Box</Link>
* <Link href="/guides/api-calls/permissions-and-errors/scopes/#read-and-write-all-files-and-folders">Write all files and folders stored in Box</Link>
* <Link href="/guides/api-calls/permissions-and-errors/scopes/#manage-box-relay">Manage Box Relay</Link>

<Warning>
  Depending on the selected authentication method and enterprise's settings,
  your application may require Admin authorization or re-authorization before
  successful use of any newly selected scopes.
</Warning>

## Rate Limits

Please see our <Link href="/guides/api-calls/permissions-and-errors/rate-limits/#per-api-rate-limits">rate limit guide</Link> for more information.

## Testing

Due to the feature parity, it may be useful to familiarize yourself with
[Box Relay functionality using the Box web app][webapp] before leveraging the
API. As with all API endpoints, we recommend testing via
[developer sandbox environment][sandbox] to eliminate the risk of impacting
production content.

[webapp]: https://support.box.com/hc/en-us/articles/360044628853-Creating-and-Running-a-Manual-Start-Workflow

[sandbox]: https://support.box.com/hc/en-us/articles/360043697274-Managing-developer-sandboxes-for-Box-admins

[boxrelay]: https://support.box.com/hc/en-us/articles/360044196213-Introducing-Box-Relay

[manualstart]: https://support.box.com/hc/en-us/articles/360044628853-Creating-and-Running-a-Manual-Start-Workflow

[blog]: https://medium.com/box-developer-blog/manual-start-workflow-api-box-relay-4f8d0f51b7a4


# Start Workflow
Source: https://developer.box.com/guides/box-relay/start-workflow



The <Link href="/reference/post-workflows-id-start">start workflow endpoint</Link> can be used to start a flow within a
workflow of type `WORKFLOW_MANUAL_START`. Other flow types cannot be started.
If you have the flow set up to accept configurations at runtime, you must send
in the optional `outcomes` array object.

<Note>
  For more information on how to use this endpoint, refer to our [blog][blog]
  post.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/workflows/42037322/start" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
         "type": "workflow_parameters",
         "flow": {
          "id": "8937625",
          "type": "flow"
         },
         "files": [{
            "type": "file",
            "id": "389047572"
          },
          {
            "type": "file",
            "id": "389047578"
          }],
         "folder": {
           "id": "2233212",
           "type": "folder"
         },
         "outcomes": [
            {
              "id": "34895783",
              "type": "outcome",
              "task_collaborators": {
                  "type": "variable",
                  "variable_type": "user_list",
                  "variable_value": [{ "type": "user", "id": "890273642" }]
              },
              "completion_rule": {
                  "type": "variable",
                  "variable_type": "task_completion_rule",
                  "variable_value": "all_assignees"
              },
              "file_collaborator_role": {
                  "type": "variable",
                  "variable_type": "collaborator_role",
                  "variable_value": "viewer"
              }
            }
          ]
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await adminClient.workflows.startWorkflow(workflowToRun.id!, {
    type: 'workflow_parameters' as StartWorkflowRequestBodyTypeField,
    flow: {
      type: 'flow',
      id: workflowToRun.flows![0].id!,
    } satisfies StartWorkflowRequestBodyFlowField,
    files: [
      {
        type: 'file' as StartWorkflowRequestBodyFilesTypeField,
        id: workflowFileId,
      } satisfies StartWorkflowRequestBodyFilesField,
    ],
    folder: {
      type: 'folder' as StartWorkflowRequestBodyFolderTypeField,
      id: workflowFolderId,
    } satisfies StartWorkflowRequestBodyFolderField,
  } satisfies StartWorkflowRequestBody);
  ```

  ```python Python v10 theme={null}
  admin_client.workflows.start_workflow(
      workflow_to_run.id,
      StartWorkflowFlow(type="flow", id=workflow_to_run.flows[0].id),
      [StartWorkflowFiles(type=StartWorkflowFilesTypeField.FILE, id=workflow_file_id)],
      StartWorkflowFolder(
          type=StartWorkflowFolderTypeField.FOLDER, id=workflow_folder_id
      ),
      type=StartWorkflowType.WORKFLOW_PARAMETERS,
  )
  ```

  ```cs .NET v10 theme={null}
  await adminClient.Workflows.StartWorkflowAsync(workflowId: NullableUtils.Unwrap(workflowToRun.Id), requestBody: new StartWorkflowRequestBody(flow: new StartWorkflowRequestBodyFlowField() { Type = "flow", Id = NullableUtils.Unwrap(NullableUtils.Unwrap(workflowToRun.Flows)[0].Id) }, files: Array.AsReadOnly(new [] {new StartWorkflowRequestBodyFilesField() { Type = StartWorkflowRequestBodyFilesTypeField.File, Id = workflowFileId }}), folder: new StartWorkflowRequestBodyFolderField() { Type = StartWorkflowRequestBodyFolderTypeField.Folder, Id = workflowFolderId }) { Type = StartWorkflowRequestBodyTypeField.WorkflowParameters });
  ```

  ```swift Swift v10 theme={null}
  try await adminClient.workflows.startWorkflow(workflowId: workflowToRun.id!, requestBody: StartWorkflowRequestBody(type: StartWorkflowRequestBodyTypeField.workflowParameters, flow: StartWorkflowRequestBodyFlowField(type: "flow", id: workflowToRun.flows![0].id!), files: [StartWorkflowRequestBodyFilesField(type: StartWorkflowRequestBodyFilesTypeField.file, id: workflowFileId)], folder: StartWorkflowRequestBodyFolderField(type: StartWorkflowRequestBodyFolderTypeField.folder, id: workflowFolderId)))
  ```

  ```java Java v10 theme={null}
  adminClient.getWorkflows().startWorkflow(workflowToRun.getId(), new StartWorkflowRequestBody.Builder(new StartWorkflowRequestBodyFlowField.Builder().type("flow").id(workflowToRun.getFlows().get(0).getId()).build(), Arrays.asList(new StartWorkflowRequestBodyFilesField.Builder().type(StartWorkflowRequestBodyFilesTypeField.FILE).id(workflowFileId).build()), new StartWorkflowRequestBodyFolderField.Builder().type(StartWorkflowRequestBodyFolderTypeField.FOLDER).id(workflowFolderId).build()).type(StartWorkflowRequestBodyTypeField.WORKFLOW_PARAMETERS).build())
  ```
</CodeGroup>

[blog]: https://medium.com/box-developer-blog/manual-start-workflow-api-box-relay-4f8d0f51b7a4


# Box Sign endpoints
Source: https://developer.box.com/guides/box-sign/api-endpoints

A map of the Box Sign request and template endpoints, and what each one does.

Use this page to see the whole Box Sign API surface at a glance. For request
and response parameters, follow the link to the full reference for each
endpoint.

## Sign requests

The sign request endpoint creates and manages signature requests. You can
create, resend, and cancel signature requests. You can also list all signature
requests and get the details of a specific one.

The base endpoint is `https://api.box.com/2.0/sign_requests`.

| Operation | Endpoint | Description |
| - | - | - |
| `GET` | `/sign_requests` | [List all signature requests](/reference/get-sign-requests) |
| `GET` | `/sign_requests/:id` | [Get a specific signature request](/reference/get-sign-requests-id) |
| `POST` | `/sign_requests` | [Create a signature request](/reference/post-sign-requests) |
| `POST` | `/sign_requests/:id/resend` | [Resend a signature request](/reference/post-sign-requests-id-resend) |
| `POST` | `/sign_requests/:id/cancel` | [Cancel a signature request](/reference/post-sign-requests-id-cancel) |

For the full resource schema, see the [Box Sign request](/reference/sign-requests-resources) reference.

## Sign templates

The sign templates endpoint lists templates and gets the details of a single
template.

<Note>
  You cannot create, edit, or delete templates through the API. Templates are
  managed in the Box web app. See
  [Create a sign request with a template](/guides/box-sign/document-types/sign-templates).
</Note>

The base endpoint is `https://api.box.com/2.0/sign_templates`.

| Operation | Endpoint | Description |
| - | - | - |
| `GET` | `/sign_templates` | [List all templates](/reference/get-sign-templates) |
| `GET` | `/sign_templates/:id` | [Get a specific template](/reference/get-sign-templates-id) |

For the full resource schema, see the [Box Sign template](/reference/sign-templates-resources) reference.

## Webhooks

Sign events are delivered through the standard Box webhooks endpoint rather
than a Sign-specific one. See [Box Sign webhooks](/guides/box-sign/webhooks).

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Cancel a Box Sign request
Source: https://developer.box.com/guides/box-sign/cancel-sign-request

Cancel an unsigned Box Sign request and optionally provide a cancellation reason.

A Box Sign request that has not yet been signed or declined can be cancelled
using the [cancel Box Sign request endpoint](/reference/post-sign-requests-id-cancel). Any outstanding signers cannot sign the document.

Only the requester (the user who created the request) can cancel it. You can't
cancel a request that was declined, fully signed, or where the document is
still converting.

## Cancel a request

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>/cancel" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.signRequests.cancelSignRequest(createdSignRequest.id!);
  ```

  ```python Python v10 theme={null}
  client.sign_requests.cancel_sign_request(created_sign_request.id)
  ```

  ```cs .NET v10 theme={null}
  await client.SignRequests.CancelSignRequestAsync(signRequestId: NullableUtils.Unwrap(createdSignRequest.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.signRequests.cancelSignRequest(signRequestId: createdSignRequest.id!)
  ```

  ```java Java v10 theme={null}
  client.getSignRequests().cancelSignRequest(createdSignRequest.getId())
  ```

  ```java Java v5 theme={null}
  BoxSignRequest signRequest = new BoxSignRequest(api, id);
  BoxSignRequest.Info signRequestInfo = signRequest.getInfo();

  signRequestInfo.cancel();
  ```

  ```python Python v4 theme={null}
  sign_request = client.sign_request(sign_request_id='12345')
  cancelled_sign_request = sign_request.cancel()
  print(f'Cancelled Sign Request status is {cancelled_sign_request.status}')
  ```

  ```cs .NET v6 theme={null}
  BoxSignRequest cancelledSignRequest = await client.SignRequestsManager.CancelSignRequestAsync("12345");
  ```

  ```javascript Node v4 theme={null}
  const signRequest = await client.signRequests.cancelById({
  	sign_request_id: 12345,
  });
  console.log(`Sign request id ${sr.id} cancelled`);
  ```
</CodeGroup>

## Provide a cancellation reason

The request body accepts an optional `reason` field describing why the request was cancelled.

```sh cURL theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>/cancel" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{ "reason": "Project cancelled" }'
```

<Note>
  The v10 SDK methods shown above cancel a request without sending a body, so call the
  endpoint directly to set a cancellation reason.
</Note>

## Control signer notifications

Signer notifications are configured per signer when the request is created, not when it is cancelled, so the cancel endpoint takes no notification parameters. To turn the
default emails off and send your own, see
[How signers get the request](/guides/box-sign/how-signers-get-the-request#send-your-own-notifications).

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# 21 CFR Part 11 requests
Source: https://developer.box.com/guides/box-sign/cfr-part-11

Send GxP signature requests through the Box Sign API with request_flow set to cfr11, and handle the extra validation rules.

[21 CFR Part 11][cfr] is a US FDA regulation for electronic records and
signatures (often called GxP). You can send both `cfr11` and `standard`
requests through the API, Box Automate, and Box for Salesforce, not only the
Box web app.

<Note>
  21 CFR Part 11 in Box Sign requires GxP Validation. An enterprise admin must also enable
  it for specific users and groups before those users can create `cfr11`
  requests. See [21 CFR Part 11 compliance support][cfr].
</Note>

## Choose a request flow

| Value | Description |
| - | - |
| `cfr11` | Enforces 21 CFR Part 11 requirements. |
| `standard` | The default Box Sign flow. |

`request_flow` is optional. If you omit it, Box Sign uses the enterprise admin
default. A value your account cannot use returns a `403 Forbidden` error. The field is
also returned when you create, get, or list requests and templates.

When `request_flow` is `cfr11`:

* Each signer must log in (`login_required` is always `true`). Setting it to
  `false` returns a `400 Bad Request` error.
* `signature_color` cannot be `red`. Use `blue` or `black`.
* Each recipient must have no signature properties, or at least one required signature or
  initials field. A request with only text fields fails.

## Create from a template

Pass `template_id` and `request_flow: "cfr11"`. Box Sign validates the template
signature and initials placeholders when you create the request.

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "request_flow": "cfr11",
       "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb",
       "signers": [
         {
           "role": "signer",
           "email": "signer@example.com"
         }
       ],
       "parent_folder": {
         "type": "folder",
         "id": "0987654321"
       }
     }'
```

A template that has only non-signature fields returns a `400 Bad Request` error.

## Create from source files

Box Sign extracts [document tags][tags] during conversion, so it cannot validate
placeholders at request time. For `cfr11` requests from `source_files`,
`is_document_preparation_needed` must be `true`:

| `is_document_preparation_needed` | When validation runs |
| - | - |
| `true` | On the prepare page, before the request is sent. Box Sign can adjust signature and initials placeholders and warn you if any are resized. |
| `false` | During conversion after send. If validation fails, the status is `error` with `error_code` `cfr11_validation_failed`, and Box Sign emails the requester. Create a new request after you fix the file. |

If you pass both `template_id` and `source_files`, the files replace the template document. Validation follows the source-file rules, so `is_document_preparation_needed` must be `true`.

## Read CFR Part 11 fields

| Field | Description |
| - | - |
| `request_flow` | `cfr11` or `standard`. |
| `signers[].login_required` | Always `true` for `cfr11`. |
| `signers[].signature_fields[].reason` | Signing reason for applicable `cfr11` signature fields. Otherwise `null`. |
| `signers[].signature_fields[].is_validated` | `true` after re-authentication, `false` if the field is filled but not re-authenticated, `null` when it does not apply. |

You can get, list, cancel, and resend a `cfr11` request even if 21 CFR Part 11
is not enabled for your account. Box checks template permission when you
create a request from it, not when you retrieve the template.

Requests and templates created before API support for 21 CFR Part 11 still return a `request_flow` based on the user's permissions.

## Error responses

| Scenario | Status | Reason |
| - | - | - |
| `login_required` is `false` on a `cfr11` request | `400` | `invalid_parameter` |
| `signature_color` is `red` on a `cfr11` request | `400` | `invalid_parameter` |
| A `cfr11` request has only non-signature fields | `400` | `invalid_template` |
| The `template_id` does not exist or you cannot use it | `404` | `not_found` |
| You cannot use the specified `request_flow` | `403` | `forbidden_by_policy` |

Tag errors on source-file requests are not returned at create time. They display in the [signing log][log] as `error` / `cfr11_validation_failed`.

[cfr]: https://docs.box.com/en/box-sign/sending-a-document-for-signature/21-cfr-part-11-compliance-support

[tags]: https://docs.box.com/en/box-sign/templates/creating-templates-using-tags

[log]: https://support.box.com/hc/en-us/articles/4404095202579-Viewing-the-signing-log

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create a Box Sign request
Source: https://developer.box.com/guides/box-sign/create-sign-request

Create a Box Sign request with files, signers, templates, and document preparation.

To [create a Box Sign request](/reference/post-sign-requests) you need a file you want signed, a destination folder for the signed
document, a [signing log][log], and at least one signer. Use this page for
every option you set when you create a request.

<Tabs>
  <Tab title="cURL">
    ```sh theme={null}
    curl -i -X POST "https://api.box.com/2.0/sign_requests" \
         -H "authorization: Bearer <ACCESS_TOKEN>" \
         -d '{
           "signers": [
              {
                "role": "signer",
                "email": "example_email@box.com"
              }
            ],
           "source_files": [
              {
                "type": "file",
                "id": "123456789"
              }
           ],
           "parent_folder":
              {
                "type": "folder",
                "id": "0987654321"
              }
         }'
    ```
  </Tab>

  <Tab title="Node">
    <CodeGroup>
      ```typescript Node/TypeScript v10 theme={null}
      await client.signRequests.createSignRequest({
        signers: [
          {
            email: signerEmail,
            suppressNotifications: true,
            declinedRedirectUrl: 'https://www.box.com',
            embedUrlExternalUserId: '123',
            isInPerson: false,
            loginRequired: false,
            password: 'password',
            role: 'signer' as SignRequestCreateSignerRoleField,
          } satisfies SignRequestCreateSigner,
        ],
        areRemindersEnabled: true,
        areTextSignaturesEnabled: true,
        daysValid: 30,
        declinedRedirectUrl: 'https://www.box.com',
        emailMessage: 'Please sign this document',
        emailSubject: 'Sign this document',
        externalId: '123',
        externalSystemName: 'BoxSignIntegration',
        isDocumentPreparationNeeded: false,
        name: 'Sign Request',
        parentFolder: new FolderMini({ id: destinationFolder.id }),
        redirectUrl: 'https://www.box.com',
        prefillTags: [
          {
            dateValue: dateFromString('2035-01-01'),
            documentTagId: '0',
          } satisfies SignRequestPrefillTag,
        ],
        sourceFiles: [new FileBase({ id: fileToSign.id })],
      } satisfies SignRequestCreateRequest);
      ```

      ```javascript Node v4 theme={null}
      const signRequest = await client.signRequests.create({
      	signers: [
      		{
      			role: 'signer',
      			email: 'user@example.com',
      		},
      	],
      	source_files: [
      		{
      			type: 'file',
      			id: '12345',
      		},
      	],
      	parent_folder: {
      		type: 'folder',
      		id: '1234567',
      	},
      });
      console.log(`Created a new sign request id ${signRequest.id}`);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Python">
    <CodeGroup>
      ```python Python v10 theme={null}
      client.sign_requests.create_sign_request(
          [
              SignRequestCreateSigner(
                  email=signer_email,
                  suppress_notifications=True,
                  declined_redirect_url="https://www.box.com",
                  embed_url_external_user_id="123",
                  is_in_person=False,
                  login_required=False,
                  password="password",
                  role=SignRequestCreateSignerRoleField.SIGNER,
              )
          ],
          source_files=[FileBase(id=file_to_sign.id)],
          parent_folder=FolderMini(id=destination_folder.id),
          is_document_preparation_needed=False,
          redirect_url="https://www.box.com",
          declined_redirect_url="https://www.box.com",
          are_text_signatures_enabled=True,
          email_subject="Sign this document",
          email_message="Please sign this document",
          are_reminders_enabled=True,
          name="Sign Request",
          prefill_tags=[
              SignRequestPrefillTag(
                  date_value=date_from_string("2035-01-01"), document_tag_id="0"
              )
          ],
          days_valid=30,
          external_id="123",
          external_system_name="BoxSignIntegration",
      )
      ```

      ```python Python v4 theme={null}
      source_file = {
          'id': '12345',
          'type': 'file'
      }
      files = [source_file]

      signer = {
          'name': 'John Doe',
          'email': 'signer@mail.com'
      }
      signers = [signer]
      parent_folder_id = '123456789'

      new_sign_request = client.create_sign_request_v2(signers, files=files, parent_folder_id=parent_folder_id)
      print(f'(Sign Request ID: {new_sign_request.id})')
      ```
    </CodeGroup>
  </Tab>

  <Tab title=".NET">
    <CodeGroup>
      ```cs .NET v10 theme={null}
      await client.SignRequests.CreateSignRequestAsync(requestBody: new SignRequestCreateRequest(signers: Array.AsReadOnly(new [] {new SignRequestCreateSigner() { Email = signerEmail, SuppressNotifications = true, DeclinedRedirectUrl = "https://www.box.com", EmbedUrlExternalUserId = "123", IsInPerson = false, LoginRequired = false, Password = "password", Role = SignRequestCreateSignerRoleField.Signer }}), areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: 30, declinedRedirectUrl: "https://www.box.com", emailMessage: "Please sign this document", emailSubject: "Sign this document", externalId: "123", externalSystemName: "BoxSignIntegration", isDocumentPreparationNeeded: false, name: "Sign Request", parentFolder: new FolderMini(id: destinationFolder.Id), redirectUrl: "https://www.box.com", prefillTags: Array.AsReadOnly(new [] {new SignRequestPrefillTag() { DateValue = Utils.DateFromString(date: "2035-01-01"), DocumentTagId = "0" }}), sourceFiles: Array.AsReadOnly(new [] {new FileBase(id: fileToSign.Id)})));
      ```

      ```cs .NET v6 theme={null}
      var sourceFiles = new List<BoxSignRequestCreateSourceFile>
      {
          new BoxSignRequestCreateSourceFile()
          {
              Id = "12345"
          }
      };

      var signers = new List<BoxSignRequestSignerCreate>
      {
          new BoxSignRequestSignerCreate()
          {
              Email = "example@gmail.com"
          }
      };

      var parentFolder = new BoxRequestEntity()
      {
          Id = "12345",
          Type = BoxType.folder
      };

      var request = new BoxSignRequestCreateRequest
      {
          SourceFiles = sourceFiles,
          Signers = signers,
          ParentFolder = parentFolder
      };

      BoxSignRequest signRequest = await client.SignRequestsManager.CreateSignRequestAsync(request);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Swift">
    ```swift theme={null}
    try await client.signRequests.createSignRequest(requestBody: SignRequestCreateRequest(signers: [SignRequestCreateSigner(email: signerEmail, suppressNotifications: true, declinedRedirectUrl: "https://www.box.com", embedUrlExternalUserId: "123", isInPerson: false, loginRequired: false, password: "password", role: SignRequestCreateSignerRoleField.signer)], areRemindersEnabled: true, areTextSignaturesEnabled: true, daysValid: Int64(30), declinedRedirectUrl: "https://www.box.com", emailMessage: "Please sign this document", emailSubject: "Sign this document", externalId: "123", externalSystemName: "BoxSignIntegration", isDocumentPreparationNeeded: false, name: "Sign Request", parentFolder: FolderMini(id: destinationFolder.id), redirectUrl: "https://www.box.com", prefillTags: [SignRequestPrefillTag(dateValue: try Utils.Dates.dateFromString(date: "2035-01-01"), documentTagId: "0")], sourceFiles: [FileBase(id: fileToSign.id)]))
    ```
  </Tab>

  <Tab title="Java">
    <CodeGroup>
      ```java Java v10 theme={null}
      client.getSignRequests().createSignRequest(new SignRequestCreateRequest.Builder(Arrays.asList(new SignRequestCreateSigner.Builder().email(signerEmail).role(SignRequestCreateSignerRoleField.SIGNER).isInPerson(false).embedUrlExternalUserId("123").declinedRedirectUrl("https://www.box.com").loginRequired(false).password("password").suppressNotifications(true).build())).sourceFiles(Arrays.asList(new FileBase(fileToSign.getId()))).parentFolder(new FolderMini(destinationFolder.getId())).isDocumentPreparationNeeded(false).redirectUrl("https://www.box.com").declinedRedirectUrl("https://www.box.com").areTextSignaturesEnabled(true).emailSubject("Sign this document").emailMessage("Please sign this document").areRemindersEnabled(true).name("Sign Request").prefillTags(Arrays.asList(new SignRequestPrefillTag.Builder().documentTagId("0").dateValue(dateFromString("2035-01-01")).build())).daysValid(30L).externalId("123").externalSystemName("BoxSignIntegration").build())
      ```

      ```java Java v5 theme={null}
      List<BoxSignRequestFile> files = new ArrayList<BoxSignRequestFile>();
      BoxSignRequestFile file = new BoxSignRequestFile("12345");
      files.add(file);
              
      // you can also use specific version of the file
      BoxFile file = new BoxFile(api, "12345");
      List<BoxFileVersion> versions = file.getVersions();
      BoxFileVersion firstVersion = versions.get(0);
      BoxSignRequestFile file = new BoxSignRequestFile(firstVersion.getFileID(), firstVersion.getVersionID());

      List<BoxSignRequestSigner> signers = new ArrayList<BoxSignRequestSigner>();
      BoxSignRequestSigner newSigner = new BoxSignRequestSigner("signer@mail.com");
      signers.add(newSigner);

      String destinationParentFolderId = "55555";

      BoxSignRequest.Info signRequestInfo = BoxSignRequest.createSignRequest(api, files,
              signers, destinationParentFolderId);
      ```
    </CodeGroup>
  </Tab>
</Tabs>

Creating a request is asynchronous. Check the
[request status](#request-status) before you treat the request
as sent, and handle conversion or sending errors.

## Choose a document type

How you create the request depends on whether Box Sign already knows where to
place signatures and other fields.

* **Unstructured document**: The file has no tags or templates. Set
  `is_document_preparation_needed` to `true` so the sender can place fields
  before anyone signs. See
  [Signing unstructured documents](/guides/box-sign/document-types/unstructured).
* **Structured document**: The file already contains [document tags][tags].
  You can skip preparation. See
  [Signing structured documents](/guides/box-sign/document-types/structured).
* **Template**: Pass `template_id` instead of, or in addition to,
  `source_files`. See [Templates](/guides/box-sign/document-types/sign-templates).

## Files

Each Box Sign request begins with a file that needs to be signed. If the file
does not already exist in Box, it must be [uploaded](/guides/uploads/direct) in a separate
API call, before you create the request. Multiple files can be signed in one
request. The file ID of the first file in a request is specified in the
`source_files` body parameter.

<Warning>
  The requester must have download permissions to the file in Box. Review
  the [collaboration levels][collab] to ensure this requirement is met.
</Warning>

Supported file types include:

* All [documents](/guides/representations/supported-file-types#documents)
* All [presentations](/guides/representations/supported-file-types#presentation)
* Images: `png`, `jpg`, `jpeg`, `tiff`
* Text-based files: `.csv`, `.txt`

All file types are converted to `.pdf` for the signature process. This converted
document is stored in the `parent_folder` after the request is sent. The final
signed document is always a `.pdf`, regardless of the original file type. As
each signer completes the request, Box Sign adds a new file version.

File size limits are determined by your account type. See the [uploads guide](/guides/uploads/direct) for more information.

## Parent folder

The folder ID specified in the `parent_folder` body parameter determines the
destination of the final signed document and [signing log][log]. This folder
cannot be the All Files or root level, which is represented by folder ID `0`.

## Document preparation

Preparing a document before you send a Box Sign request lets you add date,
text, checkbox, and signature placeholders for signers. You can do this in the
prepare UI or with [tags](/guides/box-sign/document-types/structured#anatomy-of-a-structured-document) in the document.

If you skip preparation, signers receive an unprepared document and can place
signatures and fields themselves. You can still turn unprepared document
features on or off in the request.

Set `is_document_preparation_needed` to `true` to get a `prepare_url` in the response. Open that URL in a browser to place fields and send the request.
Until someone visits `prepare_url`, the request stays in the `created` status. Once someone visits `prepare_url`, the request status changes to `sent`.

For unstructured files, always set `is_document_preparation_needed` to `true`
so the requester can place fields before the signer receives the request. Structured
documents and templates already define field placement, so you can skip the preparation
step.

<Warning>
  Prefill tags created in a template with the Box web app cannot be accessed through
  the API.
</Warning>

<Frame>
  <div>
    <img alt="Prepare options" />
  </div>
</Frame>

## Signers

Each signer must have a role (`signer`, `approver`, or `final_copy_reader`)
and can have a signing `order`. For what each role can do, how ordering works,
and a multi-signer example, see
[Multiple signers and signing order](/guides/box-sign/multiple-signers).

Signers do not need a Box account. Invite them by email address, not by Box's
`user_id`.

<Warning>
  Box Sign sends signing emails only to the addresses you provide. For Box users, that does not include email aliases unless you specify them. Confirm that every signer email is valid.
</Warning>

### Signer verification

To require a CAC/PIV smart card, SMS, Box login, or a password before a signer
can sign, see [Verify signer identity](/guides/box-sign/signer-verification).

### Signer language

Set `language` on a signer to force emails and the signing page to that
language, regardless of the signer's Box account or browser. If you omit
`language`, Box Sign uses the signer's Box account language when they are
logged in, or English when they are not.

Use a supported code from the [language codes](/guides/api-calls/language-codes) page, for example `en`, `nl`, `fr`, `de`, `es`, or `ja`. An unsupported code returns a `400 Bad Request` error. If the signer has an account, they can change their language in their account settings.

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "signers": [
          {
            "role": "signer",
            "email": "signer@example.com",
            "language": "nl"
          }
        ],
       "source_files": [
          {
            "type": "file",
            "id": "123456789"
          }
       ],
       "parent_folder": {
          "type": "folder",
          "id": "0987654321"
       }
     }'
```

### In-person signatures

To collect a signature on the requester's device, set `is_in_person` to `true`
and see [In-person signing](/guides/box-sign/in-person-signing).

### Signature properties and prefill tags

Signature properties are the fields a signer can interact with. Use
`prefill_tags` with `document_tag_id` to populate signature properties when you
create the request. Signers can still change prefilled values they own. For more information, see [Signature properties and prefill tags](/guides/box-sign/document-types/structured#pre-populate-the-signature-attributes).

When you use a template, keep signer order in the `POST` body the same as the order on the template so the correct person gets each field.

```json theme={null}
{
  "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
  "parent_folder": {
    "id": "123456789000",
    "type": "folder"
  },
  "signers": [
    {
      "email": "signer1@example.com",
      "role": "signer"
    },
    {
      "email": "signer2@example.com",
      "role": "signer"
    }
  ],
  "prefill_tags": [
    {
      "document_tag_id": "signer1_full_name",
      "text_value": "Ebenezer Scrooge"
    },
    {
      "document_tag_id": "signer2_full_name",
      "text_value": "Bob Cratchit"
    }
  ]
}
```

For listing templates, tag IDs, and a full walkthrough, see [Create a sign request with a template](/guides/box-sign/document-types/sign-templates).

## Redirects

Set `redirect_url` and `declined_redirect_url` to send signers to a custom
page after they sign or decline. You can set these URLs on the request for each signer, and override them on individual signers. If you omit both, Box Sign uses the default completion page.

<Warning>
  The default completion page tells signers that a limited-time link to the finalized copy is emailed to them, and that a copy is available in Box if they have an account. A custom redirect URL does not include that message.
</Warning>

<Frame>
  <img alt="Custom completion pages after sign or decline" />
</Frame>

## Email and notifications

To customize Box Sign email, send the signing link yourself, or embed the
client, see [How signers get the request](/guides/box-sign/how-signers-get-the-request).

## Request expiration

Set `days_valid` to expire the request after that many days. After expiration,
the request status is `expired` and remaining signers cannot complete it.

## Request flow

Set `request_flow` to `cfr11` for a 21 CFR Part 11 (GxP) request, or `standard`
for the default flow. See [21 CFR Part 11 requests](/guides/box-sign/cfr-part-11).

## Request status

Creating a request is asynchronous, so the response returns a `status` that
changes as the file converts, signers are notified, and the document is
completed. For what each value means and which actions each one allows, see
[Box Sign request status](/guides/box-sign/request-status).

[tags]: https://support.box.com/hc/en-us/articles/4404085855251-Creating-templates-using-tags

[log]: https://support.box.com/hc/en-us/articles/4404095202579-Viewing-the-signing-log

[collab]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Document types
Source: https://developer.box.com/guides/box-sign/document-types/index

Choose how to send a Box Sign request for unstructured documents, templates, or structured tagged files.

In your application, you sign different documents from many sources.
How can your application process these documents so the Box Sign service
recognizes them?

A signature request can have multiple requirements, or inputs, beyond the traditional signature, such as name, date, and initials. These inputs are called signature properties. The Box Sign service needs to know where to place these inputs in the document, and how to recognize them.

The first step is to consider if the document has the necessary information for the Box Sign service to recognize the signature properties. If not, then the [document is unstructured][unstructured-docs], and should be prepared before sending the signature request. This is called document preparation, and is an extra step automatically created by the Box Sign service.

There are two other types of documents that already have the necessary
information for the Box Sign service to recognize the signature properties.
These are [sign templates][sign-templates], managed in the Box application, and
[structured documents][sign-structured-docs], which are dynamically generated
documents that contain specific tags representing the signature properties.

<Next>Signing unstructured docs</Next>

[unstructured-docs]: /guides/box-sign/document-types/unstructured

[sign-templates]: /guides/box-sign/document-types/sign-templates

[sign-structured-docs]: /guides/box-sign/document-types/structured


# Create a sign request with a template
Source: https://developer.box.com/guides/box-sign/document-types/sign-templates

Create a Box Sign template in the web app, list it through the API, and send a request with template_id and prefill tags.

A Box Sign template is a document that already has signature and initials fields, signer
roles, and optional email settings. You create and manage templates in the Box
web app. The API can list templates and create sign requests from them. It
cannot create, edit, or delete templates.

Signature and initials fields on a template belong to a specific signer. They can be required or
optional. Your app can prefill them when you create a request from the template, but the signer who owns a field can still change it when they open the request.

You can also [verify signer identity](/guides/box-sign/signer-verification) for a template recipient.

For every create-time option, see [Create a Box Sign request](/guides/box-sign/create-sign-request).

## Create a template

In Box Sign, open **Sign** and select **Templates**. Select **New Template**, then
choose or upload a document.

<Frame>
  <img alt="Navigating to templates under Box Sign" />
</Frame>

<Frame>
  <img alt="Selecting a document when creating a template" />
</Frame>

Place the signature and initials fields you need, such as date, name, and signature, then save the
template.

<Frame>
  <img alt="Adding the signature, name, and date to the template" />
</Frame>

See the [Creating templates in Box Sign](https://support.box.com/hc/en-us/articles/4404094944915-Creating-templates) support article for UI details.

## Get the template ID

Use the [list Box Sign templates](/reference/get-sign-templates) endpoint to find the `template_id`.

```sh theme={null}
curl -i -X GET "https://api.box.com/2.0/sign_templates" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
```

The response is similar to this abbreviated example. For the full schema, see the [List Box Sign templates](/reference/get-sign-templates) endpoint.

```json theme={null}
{
  "entries": [
    {
      "id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
      "name": "Contract.pdf",
      "parent_folder": {
        "id": "157064745449",
        "type": "folder",
        "name": "My Sign Requests"
      },
      "signers": [
        {
          "email": "",
          "label": "reader",
          "role": "final_copy_reader"
        },
        {
          "email": "",
          "label": "signer1",
          "role": "signer"
        },
        {
          "email": "",
          "label": "signer2",
          "role": "signer",
          "inputs": [
            {
              "document_tag_id": "signer2_full_name",
              "type": "text",
              "content_type": "full_name"
            },
            {
              "document_tag_id": null,
              "type": "signature"
            },
            {
              "document_tag_id": null,
              "type": "date"
            }
          ]
        }
      ]
    }
  ]
}
```

To inspect one template, including every input and `document_tag_id`, use the [get Box Sign template by ID](/reference/get-sign-templates-id) endpoint.

```sh theme={null}
curl -i -X GET "https://api.box.com/2.0/sign_templates/6ae28666-03c4-4ac1-80db-06a90d3b1361" \
     -H "authorization: Bearer <ACCESS_TOKEN>"
```

## Create the sign request

Pass `template_id`, `parent_folder`, and signer emails when you create the request. You do not need
`source_files` when the template already references the document. Keep signer
order in the `POST` body the same as the order on the template.

In the template editor, assign a tag ID to any signature or initials field you want to prefill, then
send `prefill_tags` with that `document_tag_id`.

<Frame>
  <img alt="Assigning a tag id to a signature property input" />
</Frame>

```json theme={null}
{
  "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
  "parent_folder": {
    "id": "123456789000",
    "type": "folder"
  },
  "signers": [
    {
      "email": "signer1@example.com",
      "role": "signer"
    },
    {
      "email": "signer2@example.com",
      "role": "signer"
    }
  ],
  "prefill_tags": [
    {
      "document_tag_id": "signer1_full_name",
      "text_value": "Ebenezer Scrooge"
    },
    {
      "document_tag_id": "signer2_full_name",
      "text_value": "Bob Cratchit"
    }
  ]
}
```

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "template_id": "6ae28666-03c4-4ac1-80db-06a90d3b1361",
       "parent_folder": {
         "type": "folder",
         "id": "123456789000"
       },
       "signers": [
         {
           "email": "signer1@example.com",
           "role": "signer"
         },
         {
           "email": "signer2@example.com",
           "role": "signer"
         }
       ],
       "prefill_tags": [
         {
           "document_tag_id": "signer1_full_name",
           "text_value": "Ebenezer Scrooge"
         },
         {
           "document_tag_id": "signer2_full_name",
           "text_value": "Bob Cratchit"
         }
       ]
     }'
```

The response includes the new request `id`, `template_id`, and the prefill
values. Preparation is not needed when the template already placed the signature and initials fields.
The date field, if present, is populated with the current date. Signers can still
change values they own.

<Frame>
  <img alt="Signing the document with a prefilled name" />
</Frame>

If the document already includes signature and initials tags and you do not want to manage a
template in the web app, see [Signing structured docs](/guides/box-sign/document-types/structured).

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Signing structured docs
Source: https://developer.box.com/guides/box-sign/document-types/structured

Send a Box Sign request for a document that already includes signature tags.

A structured document in the context of Box Sign is a document that includes
specific tags that can be recognized by the Box Sign API. These tags are used
to place the signature properties associated with a specific signer in the
document, such as name, date, and signature.

This allows your app to handle a dynamically generated document that is ready to be
signed, which has a couple of advantages:

* The document can be dynamically generated, and the signature properties can be added to the document before creating the signature request, effectively bypassing the document preparation step.

* The document format can be handled outside of Box Sign templates, allowing higher flexibility and integration with external document management systems.

## Anatomy of a structured document

Here is an example of a structured document, showing the formatting used to
place tags in a Microsoft Word document:

<Frame>
  <img alt="Using tags in a Microsoft Word document" />
</Frame>

In the sample above `[[c|1]]` means a checkbox assigned to signer 1, and `[[s|1]]` means a signature pad assigned to signer 1. Notice how the signature pad
is using font size 48 to reserve space vertically for the signature.

The `[[t|1|id:tag_full_name|n:enter your complete name]]` means a name tag
assigned to signer 1, with the label `enter your complete name`, and using an
id of `tag_full_name`.

Check out the list of [available tags][support-tags] for a complete description of all
the tags.

Setting the tags to the same `color` as the background makes them
invisible, but they still exist.

### Recipient numbering

The number in the tags refers to the signer number, not the signing order.
`[[c|1]]` is the checkbox for signer 1, `[[c|2]]` is the checkbox for signer 2,
and so on. Box Sign assigns tags based on the order of signers in the
`signers[]` array of your request.

* Tag `0` is reserved for the sender. Start numbering with `0` only if the sender signs the document.
* If the sender doesn't sign, start numbering with `1`. Your document must not contain `|0` tags.
* If you use signer groups, don't place a signer group that includes the sender in the first position of `signers[]`.

<Warning>
  Assign tags only to signers with the `signer` role. Don't assign tags to
  signers with other roles, such as `approver` or `final_copy_reader`.
</Warning>

For example, if the sender doesn't sign, you can create a document with these
tags:

* `[[s|1]]` for signature
* `[[s|2]]` for signature

Your request then contains:

```json theme={null}
"signers": [
  {
    "role": "signer",
    "email": "alice@example.com"
  },
  {
    "role": "signer",
    "email": "bob@example.com"
  }
]
```

Box Sign assigns `alice@example.com` to the `[[s|1]]` tags and
`bob@example.com` to the `[[s|2]]` tags.

## Create a signature request from a structured document

This is the same as creating a signature request from an unstructured document.
At minimum, you need to specify the document, the receiving folder and
the email of the `signer`.

Since the structured document already contains the signature properties details
and location, you can bypass the document preparation.

This is how the flow looks, from the generated document to the signed
request:

<Frame>
  <img alt="Signing a structured document" />
</Frame>

Consider this method:

<CodeGroup>
  ```sh cURL theme={null}
  curl --location 'https://api.box.com/2.0/sign_requests' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer nQ...xY' \
      --data-raw '{
        "source_files": [
          {
            "type": "file",
            "id": "1363379762284"
          }
        ],
        "parent_folder": {
          "id": "234102987614",
          "type": "folder"
        },
        "signers": [
          {
            "email": "signer@example.com",
            "role": "signer"
          }
        ]
      }'
  ```

  ```python Python v10 theme={null}
  sign_request = client.sign_requests.create_sign_request(
      [SignRequestCreateSigner(email=signer_email)],
      source_files=[FileBase(id=file_id)],
      parent_folder=FolderMini(id=destination_folder_id),
  )
  ```
</CodeGroup>

Resulting in (simplified):

<CodeGroup>
  ```json cURL theme={null}
  {
    "is_document_preparation_needed": false,
    "signers": [
      {
        "email": "sender@example.com",
        "role": "final_copy_reader",
      },
      {
        "email": "signer@example.com",
        "role": "signer",
      }
    ],
    "id": "28199d6c-4662-471e-8426-4cbba9affcf1",
    "source_files": [
      {
        "id": "1363379762284",
        "type": "file",
        "name": "Box-Dive-Waiver.docx",
      }
    ],
    "parent_folder": {
      "id": "234102987614",
      "type": "folder",
      "name": "signed docs"
    },
    "name": "Box-Dive-Waiver.pdf",
    "type": "sign-request",
    "status": "converting",
    "sign_files": {
      "files": [
        {
          "id": "1393138856442",
          "type": "file",
          "name": "Box-Dive-Waiver.pdf",
        }
      ],
    },
  }
  ```

  ```yaml theme={null}
  Simple sign request: 6878e048-e9bd-4fb1-88c6-8e502783e8d0
    Status: converting
    Signers: 2
      final_copy_reader: sender@example.com
      signer: signer@example.com
    Prepare url: None
  ```
</CodeGroup>

If you go to the **signer** email inbox, open the email from Box Sign, and
select **Review Document**, you see the document with the signature
properties in place:

<Frame>
  <img alt="Document with the properties in place" />
</Frame>

After completing the process the signed document looks like this:

<Frame>
  <img alt="Signed document" />
</Frame>

## Pre-populate the signature attributes

If you have an external ID in the document tags, you can use it to pre-populate
their values. For example, you can use the `tag_full_name` to pre-populate the
name of the signer.

See the example:

<CodeGroup>
  ```sh cURL theme={null}
  curl --location 'https://api.box.com/2.0/sign_requests' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer nQ...xY' \
      --data-raw '{
        "prefill_tags": [
          {
            "document_tag_id": "tag_full_name",
            "text_value": "Signer A"
          }
        ],
        "source_files": [
          {
            "type": "file",
            "id": "1363379762284"
          }
        ],
        "parent_folder": {
          "id": "234102987614",
          "type": "folder"
        },
        "signers": [
          {
            "email": "signer@example.com",
            "role": "signer"
          }
        ]
      }'
  ```

  ```python Python v10 theme={null}
  sign_request = client.sign_requests.create_sign_request(
      [SignRequestCreateSigner(email=signer_email)],
      source_files=[FileBase(id=file_id)],
      parent_folder=FolderMini(id=destination_folder_id),
      prefill_tags=[
          SignRequestPrefillTag(
              document_tag_id="tag_full_name",
              text_value=signer_name,
          )
      ],
  )
  ```
</CodeGroup>

Resulting in (simplified):

<CodeGroup>
  ```json cURL theme={null}
  {
    "is_document_preparation_needed": false,
    "redirect_url": null,
    "declined_redirect_url": null,
    "are_text_signatures_enabled": true,
    "signature_color": null,
    "is_phone_verification_required_to_view": false,
    "email_subject": null,
    "email_message": null,
    "are_reminders_enabled": false,
    "signers": [
      {
        "email": "sender@example.com",
        "role": "final_copy_reader",
      },
      {
        "email": "signer@example.com",
        "role": "signer",
      }
    ],
    "id": "11ecebc0-a2b2-4c14-a892-3f56333cc4fa",
    "prefill_tags": [
      {
        "document_tag_id": "tag_full_name",
        "text_value": "Signer A",
      }
    ],
    "source_files": [
      {
        "id": "1363379762284",
        "type": "file",
        "name": "Box-Dive-Waiver.docx",
      }
    ],
    "parent_folder": {
      "id": "234102987614",
      "type": "folder",
      "name": "signed docs"
    },
    "name": "Box-Dive-Waiver (1).pdf",
    "type": "sign-request",
    "status": "converting",
    "sign_files": {
      "files": [
        {
          "id": "1393142670032",
          "type": "file",
          "name": "Box-Dive-Waiver (1).pdf",
        }
      ],
    },
  }
  ```

  ```yaml theme={null}
  Simple sign request: 7b86e46c-72ba-4568-a6ff-787077cca007
    Status: converting
    Signers: 2
      final_copy_reader: sender@example.com
      signer: signer@example.com
    Prepare url: None
  ```
</CodeGroup>

The document now has the name pre-populated:

<Frame>
  <img alt="Document ready for signing with the name pre-populated" />
</Frame>

## Extract information from a signed document

Say you want to extract the name of the signer and the other properties
from the signed document. This is useful if you need to tie the information
from the signature request back into your systems.

Create a method to extract the information from the signed request:

<CodeGroup>
  ```sh cURL theme={null}
  curl --location 'https://api.box.com/2.0/sign_requests/
  11ecebc0-a2b2-4c14-a892-3f56333cc4fa' \
      --header 'Authorization: Bearer nQ...xY'
  ```

  ```python Python v10 theme={null}
  sign_request = client.sign_requests.get_sign_request_by_id(sign_request_id)

  print(f"Simple sign request: {sign_request.id}")
  print(f"  Status: {sign_request.status.value}")
  print(f"  Signers: {len(sign_request.signers)}")
  for signer in sign_request.signers:
      print(f"    {signer.role.value}: {signer.email}")
      for input in signer.inputs:
          content_type = input.content_type
          value = None

          if content_type == SignRequestSignerInputTypeField.CHECKBOX:
              value = input.checkbox_value
          elif content_type == SignRequestSignerInputTypeField.TEXT:
              value = input.text_value
          elif content_type == SignRequestSignerInputTypeField.DATE:
              value = input.date_value

          print(
              f"      {input.type.value}: {value if value is not None else '<other>'}"
          )

  print(f"  Prepare url: {sign_request.prepare_url}")
  ```
</CodeGroup>

Resulting in (simplified):

<CodeGroup>
  ```json cURL theme={null}
  {
    "signers": [
      {
        "email": "sender@example.com",
        "role": "final_copy_reader",
      },
      {
        "email": "signer@example.com",
        "role": "signer",
        "signer_decision": {
          "type": "signed",
          "finalized_at": "2023-12-19T14:53:10.547Z",
        },
        "inputs": [
          {
            "document_tag_id": null,
            "checkbox_value": true,
            "type": "checkbox",
            "content_type": "checkbox",
          },
          {
            "document_tag_id": "tag_full_name",
            "text_value": "Signer A",
            "type": "text",
            "content_type": "text",
          },
          {
            "document_tag_id": null,
            "text_value": "Dec 19, 2023",
            "date_value": "2023-12-19",
            "type": "date",
            "content_type": "date",
          },
          {
            "document_tag_id": null,
            "type": "signature",
            "content_type": "signature",
          }
        ],
      }
    ],
    "id": "11ecebc0-a2b2-4c14-a892-3f56333cc4fa",
    "prefill_tags": [
      {
        "document_tag_id": "tag_full_name",
        "text_value": "Signer A",
      }
    ],
    "source_files": [
      {
        "id": "1363379762284",
        "type": "file",
        "name": "Box-Dive-Waiver.docx",
      }
    ],
    "parent_folder": {
      "id": "234102987614",
      "type": "folder",
      "name": "signed docs"
    },
    "name": "Box-Dive-Waiver (1).pdf",
    "type": "sign-request",
    "signing_log": {
      "id": "1393140642252",
      "type": "file",
      "name": "Box-Dive-Waiver (1) Signing Log.pdf",
    },
    "status": "signed",
    "sign_files": {
      "files": [
        {
          "id": "1393142670032",
          "type": "file",
          "name": "Box-Dive-Waiver (1).pdf",
        }
      ],
    },
  }
  ```

  ```yaml theme={null}
  Simple sign request: 7b86e46c-72ba-4568-a6ff-787077cca007
    Status: signed
    Signers: 2
      final_copy_reader: sender@example.com
      signer: signer@example.com
        checkbox: True
        text: Rui Barbosa
        date: 2023-11-15
        signature: <other>
    Prepare url: None
  ```
</CodeGroup>

## Summary

Structured documents are a great way to integrate with external document
management systems, creating dynamic documents that are ready for signing.

If your document signature requirements have a lot of options, you can
pre-populate these from another data source and save the user time, but
remember that the user who owns these properties can always change them.

After the document is signed you can extract the information from the signature
request, which is useful if you need to tie it back into your systems.

[support-tags]: https://support.box.com/hc/en-us/articles/4404085855251-Creating-templates-using-tags


# Signing unstructured docs
Source: https://developer.box.com/guides/box-sign/document-types/unstructured

Prepare an unstructured document in Box Sign before you send it to a signer.

<Note>
  Set `is_document_preparation_needed` when you
  [create a sign request](/guides/box-sign/create-sign-request#document-preparation).
  This page is the unstructured document walkthrough.
</Note>

Imagine a document management app, where users can upload a document and ask
anyone to sign it. In this case, your app knows what document to sign and
who needs to sign, but it has no idea where to put the signature or its
properties like name, date, initial, and so on.

This contrasts with [using templates][sign-templates] or
[structured documents][sign-structured-docs] where your
app knows what they are, and where the
signature properties are.

In these cases, and because each document can have a different structure, it is
a good idea to always set the `is_document_preparation_needed` flag to
`true`, so that the sender has a chance to select and place the signature
properties in the document before the signer gets the request.

There are three steps to this flow: create the signature request, prepare
the document, and sign it.

<Frame>
  <img alt="Sign unstructured docs flow" />
</Frame>

Consider the example:

<CodeGroup>
  ```sh cURL theme={null}
  curl --location 'https://api.box.com/2.0/sign_requests' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <access token>' \
      --data-raw '{
        "is_document_preparation_needed": true,
        "parent_folder": {
          "id": "234102987614",
          "type": "folder"
        },
        "source_files": [
          {
            "id": "1355143830404",
            "type": "file"
          }
        ],
        "signers": [
          {
            "email": "signer@example.com",
            "role": "signer"
          }
        ]
      }'
  ```

  ```python Python v10 theme={null}
  sign_request = client.sign_requests.create_sign_request(
      [SignRequestCreateSigner(email=signer_email)],
      source_files=[FileBase(id=document_id)],
      parent_folder=FolderMini(id=destination_folder_id),
      is_document_preparation_needed=True,
  )

  if sign_request.prepare_url is not None:
      print(sign_request.prepare_url)
  ```
</CodeGroup>

This results in a signature request with a prepare document URL (simplified):

<CodeGroup>
  ```json cURL theme={null}
  {
    "is_document_preparation_needed": true,
    "signers": [
      {
        "email": "requester@example.com",
        "role": "final_copy_reader",
      },
      {
        "email": "signer@example.com",
        "role": "signer",
      }
    ],
    "id": "348decab-48a8-4f2c-9436-8967afebf7bb",
    "prepare_url": "https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/",
    "source_files": [
      {
        "id": "1355143830404",
        "type": "file",
      }
    ],
    "parent_folder": {
      "id": "234102987614",
      "type": "folder",
    },
    "name": "Simple-PDF.pdf",
    "type": "sign-request",
    "status": "converting",
    "sign_files": {
      "files": [
        {
          "id": "1381301154812",
          "type": "file",
        }
      ],
      "is_ready_for_download": true
    },
    "template_id": null
  }
  ```

  ```yaml theme={null}
  Simple sign request with prep: xyz-abc-123
    Status: converting
    Signers: signer@example.com
  Prepare url: https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/
  ```
</CodeGroup>

Notice in the above script that, if a prepare document URL was generated by the
signature request, the app opens a browser for it. The requester can
then apply the different signature properties, for example:

<Frame>
  <img alt="Preparing the document using drag and drop on the template editor" />
</Frame>

Once the document is prepared, the requester can send the signature request to
the signer.

Back in the Box app, you see the status `In Progress`.

<Frame>
  <img alt="Pending signature request" />
</Frame>

The signer receives an email from Box with a link to the signature
request.

<Frame>
  <img alt="Signing the document" />
</Frame>

When the process is complete, both a signature log containing metadata and
the signed document are stored in the destination folder.

<Frame>
  <img alt="Log and signed document" />
</Frame>

[sign-templates]: /guides/box-sign/document-types/sign-templates

[sign-structured-docs]: /guides/box-sign/document-types/structured


# Deliver the request to signers
Source: https://developer.box.com/guides/box-sign/how-signers-get-the-request

Customize Box Sign email, send your own notifications, or embed the signing client so signers can complete a request in your app.

After you
[create a sign request](/guides/box-sign/create-sign-request),
each signer needs a way to open the request. You can:

* Let Box email the signer, and optionally customize the subject and body
* Turn off Box email and send the signing link yourself
* Embed the signing client in your website

Set these options when you create the request. You cannot change them when you
[cancel a request](/guides/box-sign/cancel-sign-request).

## Customize Box email

By default, Box Sign emails each signer from a `box.com` address with a generic
subject and body. Set `email_subject` and `email_message` when you create the request to
change that copy. Both accept strings. `email_message` also accepts the following HTML
tags: `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`,
`li`, `ol`, `strong`. Custom styles are not allowed. A high text-to-HTML ratio can send the email to spam or cause clipping.

If you create the request from a template, the template can already define the subject and body.

Set `are_reminders_enabled` to `true` to email unsigned signers after 3, 8, 13, and 18 days. To resend immediately, see [Resend a Box Sign request](/guides/box-sign/resend-sign-request).

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "email_subject": "All we need is your signature to get started",
       "email_message": "Please review and sign the attached agreement.",
       "parent_folder": {
         "type": "folder",
         "id": "0987654321"
       },
       "source_files": [
         {
           "type": "file",
           "id": "123456789"
         }
       ],
       "signers": [
         {
           "email": "signer@example.com",
           "role": "signer"
         }
       ]
     }'
```

## Send your own notifications

To take over delivery, set both of these on the signer when you create the request:

1. `suppress_notifications` to `true`
2. `embed_url_external_user_id` to an ID you choose for that person

Box Sign then skips the default signing email for that signer. The response includes
`embed_url`, which you can put in your own email, push notification, or text message.

You can send the notice from your own domain and use any channel you already operate.
The signing log records that you suppressed Box notifications and
stores the signer ID you passed in `embed_url_external_user_id`.

<Note>
  When you suppress Box email, your organization is responsible for delivering
  every required notice to signers at the right time, with the right content, and
  in line with applicable law, including consent to the delivery method when that applies.
</Note>

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "parent_folder": {
         "type": "folder",
         "id": "0987654321"
       },
       "source_files": [
         {
           "type": "file",
           "id": "123456789"
         }
       ],
       "signers": [
         {
           "role": "signer",
           "email": "signer@example.com",
           "suppress_notifications": true,
           "embed_url_external_user_id": "1234"
         }
       ]
     }'
```

A simplified response includes both the `embed_url` and `iframeable_embed_url` for that signer:

```json theme={null}
{
  "id": "22a990ce-4e24-463b-b2f4-124820fe161a",
  "signers": [
    {
      "email": "signer@example.com",
      "role": "signer",
      "embed_url_external_user_id": "1234",
      "embed_url": "https://app.box.com/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/",
      "iframeable_embed_url": "https://app.box.com/embed/sign/document/22a990ce-4e24-463b-b2f4-124820fe161a/9331fe9ac85650d61645d4b0fd30fe3e0ebee7921720ab6ecca587654d3cd875/"
    }
  ]
}
```

Use `embed_url` in your own notification. Use `iframeable_embed_url` to embed the client, as described next.

## Embed the signing client

[Box Embed](/guides/embed/box-embed) lets signers complete the request inside your website, instead of leaving for Box Sign and coming back.

Pass `embed_url_external_user_id` for each signer when you create the request.
The response includes a unique `iframeable_embed_url` for that signer:

```text theme={null}
https://app.box.com/embed/sign/document/f14d7098-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4
```

Put that URL in an `iframe`:

```html theme={null}
<iframe
  src="https://app.box.com/embed/sign/document/f14d7098-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4"
  width="{pixels}"
  height="{pixels}"
  frameborder="0"
  allowfullscreen
  webkitallowfullscreen
  msallowfullscreen
></iframe>
```

For in-person signing on the requester's device, also set `is_in_person` to
`true`. For more information, see [In-person signing](/guides/box-sign/in-person-signing).

For more information on Box Embed, see [Embed Box elements programmatically](/guides/embed/box-embed#programmatically).

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# In-person signing
Source: https://developer.box.com/guides/box-sign/in-person-signing

Let a signer complete a Box Sign request on the requester's device, and cycle through several in-person signers in one session.

Set `is_in_person` to `true` when the requester and signer are together and the
signer should complete the request on the requester's device. Set this on the
signer when you
[create the request](/guides/box-sign/create-sign-request).

Also set `embed_url_external_user_id` so the response includes `embed_url` and
`iframeable_embed_url`. Your app opens or embeds that URL to start the signing
session. For more information, see
[Embed the signing client](/guides/box-sign/how-signers-get-the-request#embed-the-signing-client).

<Frame>
  <img alt="In-person signing cycles through each signer" />
</Frame>

## Create an in-person request

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "template_id": "ee9a689e-96b6-4076-92a0-b9b765eb09ca",
       "parent_folder": {
         "type": "folder",
         "id": "0987654321"
       },
       "signers": [
         {
           "email": "signer-a@example.com",
           "role": "signer",
           "is_in_person": true,
           "embed_url_external_user_id": "1234"
         },
         {
           "email": "signer-b@example.com",
           "role": "signer",
           "is_in_person": true
         }
       ]
     }'
```

The first in-person signer gets the `embed_url` and `iframeable_embed_url`.
Later in-person signers in the same session do not need their own
`embed_url_external_user_id`.

## Several signers in one session

After the first in-person signer finishes, the interface moves to the next
in-person signer. The completed document is emailed to each signer.

<Frame>
  <img alt="First in-person signer in the Box Sign client" />
</Frame>

<Frame>
  <img alt="Second in-person signer after the first signer finishes" />
</Frame>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box Sign
Source: https://developer.box.com/guides/box-sign/index

Send documents for electronic signature from your own app using the Box Sign API, and track them through to a signed file in Box.

Box Sign brings the full Box Sign web app experience to your application
through the API. Your app chooses the document, decides who signs it and in
what order, and receives the signed file and a signing log back in a Box
folder.

## How a signature request works

Every integration follows the same path:

1. **Pick a document.** It can be a plain file that needs preparation, a file
   that already carries signature tags, or a template you built in the Box web
   app. See [document types](/guides/box-sign/document-types).
2. **Create the request.** Name the file, a destination folder, and at least
   one signer, along with any options you need. See
   [create a Box Sign request](/guides/box-sign/create-sign-request).
3. **Get the request to the signers.** Let Box email them, send the link
   yourself, or embed the signing client in your app. See
   [deliver the request to signers](/guides/box-sign/how-signers-get-the-request).
4. **Track it to completion.** Requests are asynchronous, so watch the
   [request status](/guides/box-sign/request-status) or subscribe to
   [webhooks](/guides/box-sign/webhooks).

When everyone has signed, Box stores the signed `.pdf` and the signing log in
the destination folder.

## Where to start

If you are new to Box Sign, [set up your account and scopes](/guides/box-sign/setup),
then send one request end to end with the
[quick start](/guides/box-sign/quick-start).

If you are scoping an integration, the
[endpoints page](/guides/box-sign/api-endpoints) shows the whole API surface on
one screen.

## What you can configure

Most of what makes a signature request specific to your use case is set when
you create it:

* [Multiple signers and signing order](/guides/box-sign/multiple-signers) for
  approvals and sequential signing
* [Signer verification](/guides/box-sign/signer-verification) for smart card,
  SMS, login, or password checks
* [In-person signing](/guides/box-sign/in-person-signing) when the signer is
  standing next to the requester
* [21 CFR Part 11 requests](/guides/box-sign/cfr-part-11) for GxP workflows

Language, expiration, and redirect options are covered on the
[create a Box Sign request](/guides/box-sign/create-sign-request) page.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# List and get Box Sign requests
Source: https://developer.box.com/guides/box-sign/list-sign-requests

List all Box Sign requests for the current user, or get a single request by ID.

## List all requests

Use the [get sign requests endpoint](/reference/get-sign-requests) to view a list of all Box
Sign requests created by the user associated with the passed Access Token.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/sign_requests" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.signRequests.getSignRequests();
  ```

  ```python Python v10 theme={null}
  client.sign_requests.get_sign_requests()
  ```

  ```cs .NET v10 theme={null}
  await client.SignRequests.GetSignRequestsAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.signRequests.getSignRequests()
  ```

  ```java Java v10 theme={null}
  client.getSignRequests().getSignRequests()
  ```

  ```java Java v5 theme={null}
  Iterable<BoxSignRequest.Info> signRequests = BoxSignRequest.getAll(api);
  for (BoxSignRequest.Info signRequestInfo : signRequests) {
  	// Do something with each `signRequestInfo`.
  }
  ```

  ```python Python v4 theme={null}
  sign_requests = client.get_sign_requests()
  for sign_request in sign_requests:
      print(f'(Sign Request ID: {sign_request.id})')
  ```

  ```cs .NET v6 theme={null}
  BoxCollectionMarkerBased<BoxSignRequest> signRequests = await client.SignRequestsManager.GetSignRequestsAsync();
  ```

  ```javascript Node v4 theme={null}
  const result = await client.signRequests.getAll();
  console.log(`There are ${result.count} sign requests`);
  ```
</CodeGroup>

## Get a request by ID

Use the [get sign requests by ID endpoint](/reference/get-sign-requests-id) to view
information about a specific Box Sign request. This endpoint requires the sign
request's ID, which can be obtained by using the [get all Box Sign requests endpoint](/reference/get-sign-requests) or in the response when [creating a Box Sign request](/reference/post-sign-requests).

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.signRequests.getSignRequestById(createdSignRequest.id!);
  ```

  ```python Python v10 theme={null}
  client.sign_requests.get_sign_request_by_id(created_sign_request.id)
  ```

  ```cs .NET v10 theme={null}
  await client.SignRequests.GetSignRequestByIdAsync(signRequestId: NullableUtils.Unwrap(createdSignRequest.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.signRequests.getSignRequestById(signRequestId: createdSignRequest.id!)
  ```

  ```java Java v10 theme={null}
  client.getSignRequests().getSignRequestById(createdSignRequest.getId())
  ```

  ```java Java v5 theme={null}
  BoxSignRequest signRequest = new BoxSignRequest(api, id);
  BoxSignRequest.Info signRequestInfo = signRequest.getInfo();

  //using `fields` parameter
  BoxSignRequest.Info signRequestInfoWithFields = signRequest.getInfo("status")
  ```

  ```python Python v4 theme={null}
  sign_request = client.sign_request(sign_request_id='12345').get()
  print(f'Sign Request ID is {sign_request.id}')
  ```

  ```cs .NET v6 theme={null}
  BoxSignRequest signRequest = await client.SignRequestsManager.GetSignRequestByIdAsync("12345");
  ```

  ```javascript Node v4 theme={null}
  const sr = await client.signRequests.getById({
  	sign_request_id: 12345,
  });
  console.log(
  	`Sign request id ${sr.id} contains ${sr.source_files.length} files`
  );
  ```
</CodeGroup>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Multiple signers and signing order
Source: https://developer.box.com/guides/box-sign/multiple-signers

Assign signer, approver, and final copy reader roles, and control the order in which Box Sign notifies each person.

A Box Sign request can include several people, each with a different job. Set a
role for every person, and use `order` when they need to act one after another.
Set both when you
[create the request](/guides/box-sign/create-sign-request).

## Signer roles

Each person needs a role: `signer`, `approver`, or `final_copy_reader`.

| Role | What they do |
| - | - |
| `signer` | Adds data to the document: signature, initials, date, text, checkboxes, or radio buttons. |
| `approver` | Approves the request before preparation (if enabled) and before any signer is notified. |
| `final_copy_reader` | Does not sign. Receives a copy of the signed document and [signing log][log]. |

If you do not give the requester a role, Box Sign adds them as
`final_copy_reader`.

Approvers and final copy readers cannot have signature properties. If you assign
signature properties to them, Box Sign changes their role to `signer`. In the
prepare UI, each signer has a color so you can see which fields belong to which
person.

For more detail on what each role can do, see the [roles for signers][roles]
support article.

## Signing order

If you omit `order`, Box Sign notifies every signer at the same time. If you set
`order`, only the lowest number is notified first. After they sign, the next
group is notified. Signers that share an `order` value receive the request at the
same time.

Box Sign adds a new file version to `parent_folder` as each signer completes. A
decline stops the request for everyone who has not signed yet, and the request
status becomes `declined`.

<Frame>
  <div>
    <img alt="Multiple signer flow" />
  </div>
</Frame>

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "is_document_preparation_needed": true,
       "parent_folder": {
         "type": "folder",
         "id": "0987654321"
       },
       "source_files": [
         {
           "type": "file",
           "id": "123456789"
         }
       ],
       "signers": [
         {
           "email": "institution@example.com",
           "role": "signer",
           "order": 1
         },
         {
           "email": "student@example.com",
           "role": "signer",
           "order": 2
         },
         {
           "email": "dean@example.com",
           "role": "approver"
         },
         {
           "email": "legal@example.com",
           "role": "final_copy_reader"
         }
       ]
     }'
```

<Frame>
  <img alt="Flow with an approver, two signers, and a final copy reader" />
</Frame>

In this example, the dean approves first, then the institution signs, then the
student signs, and legal receives the final copy.

<Note>
  When you create the request from a template, keep signer order in the `POST`
  body the same as the order on the template so the correct person gets each
  field. See [Create a sign request with a template](/guides/box-sign/document-types/sign-templates).
</Note>

[roles]: https://support.box.com/hc/en-us/articles/4404105660947-Roles-for-signers

[log]: https://support.box.com/hc/en-us/articles/4404095202579-Viewing-the-signing-log

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Quick start
Source: https://developer.box.com/guides/box-sign/quick-start

Send your first Box Sign request with a file, destination folder, and signer email.

<Note>
  This walkthrough creates a basic request. For every creation option, see
  [Create a Box Sign request](/guides/box-sign/create-sign-request).
</Note>

Imagine that you have a document stored in Box and you want to send it to a
customer for signature. At a minimum your app needs to know what document
to sign, where to store the signed document, and the signer email.

## Creating a signature request

Use the [Box Sign API](/reference/post-sign-requests) or one of the available [SDKs](/guides/tooling/sdks) to create a
signature request. See the example:

<CodeGroup>
  ```sh cURL theme={null}
  curl --location 'https://api.box.com/2.0/sign_requests' \
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <access token>' \
      --data-raw '{
        "is_document_preparation_needed": true,
        "parent_folder": {
          "id": "234102987614",
          "type": "folder"
        },
        "source_files": [
          {
            "id": "1355143830404",
            "type": "file"
          }
        ],
        "signers": [
          {
            "email": "signer@example.com",
            "role": "signer"
          }
        ]
      }'
  ```

  ```python Python v10 theme={null}
  sign_request = client.sign_requests.create_sign_request(
      [SignRequestCreateSigner(email=signer_email)],
      source_files=[FileBase(id=document_id)],
      parent_folder=FolderMini(id=destination_folder_id),
      is_document_preparation_needed=True,
  )

  if sign_request.prepare_url is not None:
      print(sign_request.prepare_url)
  ```
</CodeGroup>

This results in a signature request with a prepare document URL
(simplified):

<CodeGroup>
  ```json cURL theme={null}
  {
    "is_document_preparation_needed": true,
    "signers": [
      {
        "email": "requester@example.com",
        "role": "final_copy_reader",
      },
      {
        "email": "signer@example.com",
        "role": "signer",
      }
    ],
    "id": "348decab-48a8-4f2c-9436-8967afebf7bb",
    "prepare_url": "https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/",
    "source_files": [
      {
        "id": "1355143830404",
        "type": "file",
      }
    ],
    "parent_folder": {
      "id": "234102987614",
      "type": "folder",
    },
    "name": "Simple-PDF.pdf",
    "type": "sign-request",
    "status": "converting",
    "sign_files": {
      "files": [
        {
          "id": "1381301154812",
          "type": "file",
        }
      ],
      "is_ready_for_download": true
    },
    "template_id": null
  }
  ```

  ```yaml theme={null}
  Simple sign request with prep: xyz-abc-123
    Status: converting
    Signers: signer@example.com
  Prepare url: https://app.box.com/sign/document/xyz-abc-123/.../prepare_doc/
  ```
</CodeGroup>

## Check the status of the signature request

Creating the signature request is an asynchronous process, and can generate
errors. Your application needs to check the status of the request before
proceeding, and handle any errors.

A signature request can have the following statuses:

<Frame>
  <img alt="Signature flow" />
</Frame>

For the full status list, see
[Box Sign request status](/guides/box-sign/request-status).

## Preparing the document

In this example, we are signing a PDF, and the Box Sign engine has no
idea where to place the signature pad field or any other inputs. This is why we
used the `is_document_preparation_needed` flag.

If a prepare URL is present, your application opens the prepare
URL in a browser, where the requester can add the signature pad field and any
other inputs needed for the signer to complete the document.

Once the document is prepared, the requester can send the signature request to
the signer.

This preparation step is not always necessary. Take a look at
[document types][technical-use-cases] for more information.

## Completing the signature request

The signer then receives an email from Box with a link to the signature
request. The signer can select the link and sign the document.

When the process is completed, both a signature log containing metadata and
the signed document are stored in the destination folder.

Congratulations! You have successfully created your first signature request.

<Note>
  This is the basic Box Sign create flow. For every creation option, see
  [Create a Box Sign request](/guides/box-sign/create-sign-request).
  For document types and other scenarios, see
  [Document types](/guides/box-sign/document-types).
</Note>

[technical-use-cases]: /guides/box-sign/document-types


# Box Sign request status
Source: https://developer.box.com/guides/box-sign/request-status

What each Box Sign request status means, and which statuses let you resend or cancel a request.

Creating a signature request is asynchronous, so check the status before you
treat a request as sent. The status is returned when you
[create](/guides/box-sign/create-sign-request),
[get, or list](/guides/box-sign/list-sign-requests) a request.

## Status values

* `converting`: The file is converted to a `.pdf` after you send the request.
* `error_converting`: Conversion to `.pdf` failed.
* `created`: `is_document_preparation_needed` is `true` and no one has visited the prepare URL yet.
* `sent`: The request was sent and no signer has interacted with it.
* `viewed`: The first signer selected **Review document** in the email or opened the signing URL.
* `signed`: All signers completed the request.
* `declined`: A signer declined the request.
* `cancelled`: The request was cancelled in the UI or API. For more information, see [Cancel a Box Sign request](/guides/box-sign/cancel-sign-request).
* `expired`: `days_valid` passed with incomplete signatures. For more information, see [Request expiration](/guides/box-sign/create-sign-request#request-expiration).

An error status means you need a new sign request to retry.

<Frame>
  <div>
    <img alt="Status diagram" />
  </div>
</Frame>

<Note>
  The [Box Sign request resource](/reference/sign-requests-resources) lists the
  complete set of values the `status` field can return, including states that
  this guide does not describe individually.
</Note>

## What you can do in each status

| Action | Allowed when the status is |
| - | - |
| [Resend](/guides/box-sign/resend-sign-request) | The request is still open and was last sent more than 10 minutes ago |
| [Cancel](/guides/box-sign/cancel-sign-request) | The request has not been signed or declined, and the document is not still converting |

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Resend a Box Sign request
Source: https://developer.box.com/guides/box-sign/resend-sign-request

Resend a Box Sign request email to remaining signers, or enable automatic reminders when you create the request.

You can send the signing email again to anyone who has not signed yet, or turn on automatic reminders when you create the request.

## Manual resend

Use the [resend a Box Sign request](/reference/post-sign-requests-id-resend) endpoint to email remaining signers.

You cannot resend a request when the [status](/guides/box-sign/request-status) is `signed`, `cancelled`, `declined`, `expired`, `error_sending`, or `error_converting`.

Wait 10 minutes after the last send before you resend. A resend inside that window returns a `400 Bad Request` error. You can resend a request when the status is `created`, `sent`, `viewed`, or `error`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/sign_requests/<SIGN_REQUEST_ID>/resend" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```java Java v5 theme={null}
  BoxSignRequest signRequest = new BoxSignRequest(api, id);
  BoxSignRequest.Info signRequestInfo = signRequest.getInfo();

  signRequestInfo.resend();
  ```

  ```python Python v4 theme={null}
  sign_request = client.sign_request(sign_request_id='12345')
  sign_request.resend()
  ```

  ```cs .NET v6 theme={null}
  await client.SignRequestsManager.ResendSignRequestAsync("12345");
  ```

  ```javascript Node v4 theme={null}
  const id = 12345;
  await client.signRequests.resendById({ sign_request_id: id });
  console.log(`Sign request id ${sr.id} resent`);
  ```
</CodeGroup>

## Automatic reminders

When you create a request, set `are_reminders_enabled` to `true`. Box Sign emails signers who have not signed yet after 3, 8, 13, and 18 days.

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "are_reminders_enabled": true,
       "parent_folder": {
         "type": "folder",
         "id": "0987654321"
       },
       "source_files": [
         {
           "type": "file",
           "id": "123456789"
         }
       ],
       "signers": [
         {
           "email": "signer@example.com",
           "role": "signer"
         }
       ]
     }'
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Set up Box Sign
Source: https://developer.box.com/guides/box-sign/setup

Check your account type, enable the required scopes, and set up a safe place to test before you call the Box Sign API.

Complete these steps once before you send your first signature request. When
you are set up, go to the [quick start](/guides/box-sign/quick-start).

## Supported account types

The following account types support requests through the Box Sign API:
Business, Business Plus, Enterprise, Enterprise Suites, Enterprise Plus, and
Enterprise Advanced.

To locate your account type, navigate to **Account Settings** and scroll down
to the **Account Details** section of the **Account** tab. For Admin details on
restricting access, see the [support article][restrict].

## Required scopes

The following [scopes](/guides/api-calls/permissions-and-errors/scopes) must be enabled for an application before use of
Box Sign's endpoints.

* [Read all files and folders stored in Box](/guides/api-calls/permissions-and-errors/scopes#read-all-files-and-folders)
* [Write all files and folders stored in Box](/guides/api-calls/permissions-and-errors/scopes#read-and-write-all-files-and-folders)
* [Manage signature requests](/guides/api-calls/permissions-and-errors/scopes#manage-signature-requests)

<Warning>
  Depending on the selected authentication method and enterprise's settings,
  your application can require admin authorization or re-authorization before
  successful use of any newly selected scopes.
</Warning>

To create webhooks for Sign events, your application also needs the **Manage
Webhooks** scope. See [Box Sign webhooks](/guides/box-sign/webhooks).

## Rate limits

See the [rate limit guide](/guides/api-calls/permissions-and-errors/rate-limits#per-api-rate-limits) for more information.

## Events

Box Sign activity appears in the Box event stream. See the
[events guide](/guides/events/event-triggers/sign-events) for more information.

## Testing

Due to feature parity, familiarize yourself with
[Box Sign functionality using the Box web app][webapp] before leveraging the
API. As with all API endpoints, we recommend testing through the
[developer sandbox environment][sandbox] to eliminate the risk of impacting
production content.

[restrict]: https://support.box.com/hc/en-us/articles/4404076971155-Enabling-Box-Sign

[webapp]: https://support.box.com/hc/en-us/articles/4404105810195-Sending-a-document-for-signature

[sandbox]: https://support.box.com/hc/en-us/articles/360043697274-Managing-developer-sandboxes-for-Box-admins

<RelatedLinks title="RELATED GUIDES" />


# Verify signer identity
Source: https://developer.box.com/guides/box-sign/signer-verification

Require a signer to verify their identity with a smart card, SMS, or Box login, and add a password to a Box Sign request.

You can require a signer to verify their identity with a CAC/PIV smart card,
SMS, or Box login. You can also add a `password`. Set these on the signer when
you [create the request](/guides/box-sign/create-sign-request), or on a
template.

<Frame>
  <img alt="Signer verification options on a signature request" />
</Frame>

## Verification methods

Use `verification_method` on the signer when you create the request. This is the
recommended approach for new integrations.

| Type | Description |
| - | - |
| `cac_piv` | CAC/PIV smart card. Your enterprise must allow this method or the API returns `403 Forbidden`. Multiple signers who use this method must have a signing `order`. |
| `phone` | SMS verification. Include `phone_number` with a country code prefixed by `+` or `00`, for example `+15551232190`. |
| `login` | The signer must log in to a Box account. If they do not have an account, they can create a free one. |

When you get a request or template, `verification_method` is `null` if that
signer has no verification. If you set both `verification_method` and a legacy
property such as `login_required` or `verification_phone_number`,
`verification_method` takes precedence.

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/sign_requests" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "parent_folder": {
         "type": "folder",
         "id": "0987654321"
       },
       "source_files": [
         {
           "type": "file",
           "id": "123456789"
         }
       ],
       "signers": [
         {
           "email": "signer@example.com",
           "role": "signer",
           "password": "example-password",
           "verification_method": {
             "type": "phone",
             "phone_number": "+15551232190"
           }
         }
       ]
     }'
```

## Password protection

You can add a `password` alongside any verification method. Password
verification happens before the signer can open the request.

<Frame>
  <img alt="Password prompt before the signer opens the request" />
</Frame>

## SMS verification (legacy)

`verification_phone_number` is still supported. Prefer `verification_method`
when you create the request.

By default, SMS verification happens at the signing step, so the signer can view
the request first. Set `is_phone_verification_required_to_view` to `true` to
require SMS before view.

<Frame>
  <img alt="SMS verification prompt" />
</Frame>

<Frame>
  <img alt="Entering the SMS code" />
</Frame>

For more background on signer authentication, see the [additional signer
authentication][2fa] support article.

[2fa]: https://support.box.com/hc/en-us/articles/4406861109907-Additional-Signer-Authentication

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box Sign webhooks
Source: https://developer.box.com/guides/box-sign/webhooks

Listen for Box Sign request events on a folder, create a webhook, and handle the notification payload.

Signature requests are asynchronous. Signers can complete, decline, or ignore a
request at any time, including outside your app. A webhook on the destination
folder notifies your app when those events happen.

## Sign-related events

Set the listener on a folder or a document. The usual approach is the folder
where you create signature requests, so one webhook covers every request in
that folder.

Examples of events you can listen for:

* `SIGN_REQUEST.COMPLETED`, when a signature request is completed
* `SIGN_REQUEST.DECLINED`, when a signature request is declined
* `SIGN_REQUEST.EXPIRED`, when a signature request expires
* `SIGN_REQUEST.SIGNER_EMAIL_BOUNCED`, when a signer's email is bounced
* `SIGN_REQUEST.SIGNER_SIGNED`, when a particular signer signs the request
* `SIGN_REQUEST.SIGNATURE_REQUESTED`, when a signature is requested from a signer
* `SIGN_REQUEST.ERROR_FINALIZING`, when the signature request could not be processed

For the full list of triggers, see [webhook triggers](/guides/webhooks/triggers).

## Create a Sign webhook

Sign webhooks use the standard Box webhooks infrastructure.
To receive Box Sign events, call the [create webhook](/reference/post-webhooks) endpoint.
Set the `target` to the folder where you create signature requests, and list the
`SIGN_REQUEST.*` triggers you want to receive.

<Warning>
  This API requires the application to have the **Manage Webhooks** scope enabled.
</Warning>

```sh theme={null}
curl -i -X POST "https://api.box.com/2.0/webhooks" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -H "content-type: application/json" \
     -d '{
       "target": {
         "id": "12345",
         "type": "folder"
       },
       "address": "https://example.com/sign-webhooks",
       "triggers": [
         "SIGN_REQUEST.COMPLETED",
         "SIGN_REQUEST.DECLINED",
         "SIGN_REQUEST.EXPIRED"
       ]
     }'
```

For more ways to create webhooks, including the Developer Console and SDK examples, see [Create webhooks (v2)](/guides/webhooks/v2/create-v2).

## Receive Sign event notifications

When a Box Sign event occurs, Box sends an HTTP `POST` request to the `address` you configured.
The payload includes the trigger and Sign-specific `additional_info`, such as the sign request ID and signer emails.
It can also include a `source` file for the signature request.

For example, when a signature request is completed, Box sends a payload similar to the following:

```json theme={null}
{
  "type": "webhook_event",
  "id": "eb0c4e06-751f-442c-86f8-fd5bb404dbec",
  "created_at": "2024-05-22T08:28:56-07:00",
  "trigger": "SIGN_REQUEST.COMPLETED",
  "webhook": {
    "id": "53",
    "type": "webhook"
  },
  "created_by": {
    "type": "user",
    "id": "226067247",
    "name": "John Q. Developer",
    "login": "johnq@dev.name"
  },
  "source": {
    "id": "73835521473",
    "type": "file",
    "name": "Contract.pdf",
    "item_status": "active"
  },
  "additional_info": {
    "sign_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "signer_emails": [
      "johnq@dev.name",
      "signer@example.com"
    ],
    "external_id": ""
  }
}
```

Your endpoint must respond with an HTTP status code in the `200` to `299` range within 30 seconds to acknowledge the notification.
For the full payload format and delivery details, see [webhooks (v2)](/guides/webhooks/v2).
To verify that a notification was sent by Box, see [Verify Box webhook signatures](/guides/webhooks/v2/signatures-v2).

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box Doc Split
Source: https://developer.box.com/guides/docgen/doc-split

Use the Box API to break a multi-page PDF stored in Box into smaller sub-documents and save the results to a Box folder.

Box Doc Split breaks a multi-page PDF stored in Box into smaller sub-documents and saves the results to a Box folder.

Use Box Doc Split when you need to:

* Break a multi-page PDF into page-range segments you define yourself, using a <Link href="/guides/docgen/manual-split">manual split</Link>.
* Let Box interpret natural language instructions to determine how pages are grouped, using a <Link href="/guides/docgen/smart-split">smart split</Link>.

## Example use cases

| Team | Example |
| - | - |
| Sales | Split multi-deal packets into individual quotes |
| Legal | Isolate signatures and ID proofs from contract packages |
| Finance | Extract invoices from a multi-invoice PDF |
| Operations | Split scan batches at QR code separators |
| HR | Separate onboarding packet sections |

## Prerequisites

Before you start, follow the steps in the <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> guide to create a platform app and generate an access token.

You also need:

* A source PDF already stored in Box.
* A destination folder in Box that your app can write to.

## API version

All requests to Box Doc Split endpoints must specify a valid API version by setting the `box-version` header to `2026.0`.

For more details, see <Link href="/guides/api-calls/api-versioning-strategy">Box API versioning</Link>.

## Split types

The `split_type` you send determines the rest of the request body.

| Split type | Best for | You provide |
| - | - | - |
| <Link href="/guides/docgen/manual-split">`manual`</Link> | Known page ranges | A `split_definition` array of start and end pages |
| <Link href="/guides/docgen/smart-split">`smart`</Link> | Content-based or marker-based boundaries | A natural language `prompt` |

<Tip>
  Use `manual` when the page numbers are known, because the results are deterministic. Use `smart` when the boundaries are easier to describe than to calculate.
</Tip>

<Note>
  A smart split consumes AI Units. Box consumes 1 AI Unit for every 4 pages processed.
</Note>

## How Box Doc Split works

Box Doc Split runs asynchronously in two steps:

1. Send a `POST` request to `/2.0/document_splits` to create a split job. The response contains a job ID.
2. Send a `GET` request to `/2.0/document_splits/{document_split_id}` with that ID to retrieve the status and the generated files.

### Create a split job

The request body has the same shape for both split types. Only the contents of `split_input` differ.

| Parameter | Description |
| - | - |
| `source_file_id` | The Box file ID of the PDF to split |
| `destination_folder_id` | The Box folder ID where Box stores the output documents |
| `input_source` | The source of the input. Use `api` for all API-based requests |
| `split_input.split_type` | Either `manual` or `smart` |
| `split_input.split_definition` | The page ranges for a manual split |
| `split_input.prompt` | The natural language prompt for a smart split |

For a complete request example, see the <Link href="/guides/docgen/manual-split">manual split</Link> or <Link href="/guides/docgen/smart-split">smart split</Link> guide.

The response contains the ID of the split job:

```json theme={null}
{
  "id": "11678",
  "type": "document_split"
}
```

### Get the status and results of a split job

Use the job ID from the `POST` response to retrieve the details of the split.

```sh cURL theme={null}
curl -L 'https://api.box.com/2.0/document_splits/128445' \
     -H 'box-version: 2026.0' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>'
```

The response lists the generated files, the split definition Box applied, the destination folder, and other details of the request.

```json theme={null}
{
  "output": {
    "generated_files": [
      { "id": "2404332574822", "type": "file" },
      { "id": "2404326035290", "type": "file" }
    ],
    "split_definition": [
      { "start": 1, "end": 5 },
      { "start": 7, "end": 9 }
    ]
  },
  "destination_folder": {
    "id": "408521968626",
    "type": "folder"
  },
  "created_by": {
    "id": "36302517035",
    "type": "user"
  },
  "enterprise": {
    "id": "1217301449",
    "type": "enterprise"
  }
}
```

For a smart split, the `split_definition` in the response shows the ranges Box derived from your prompt. Use it to confirm that the prompt produced the grouping you expected.

<RelatedLinks title="RELATED GUIDES" />


# Get started with Box Doc Gen
Source: https://developer.box.com/guides/docgen/docgen-getting-started



To start generating documents with Box Doc Gen API you will need a platform application and a developer token to
authenticate your calls. You also need a Doc Gen template that will serve as an input source for your document.

## Enable Box Doc Gen

To use Box Doc Gen, make sure it is enabled by an
admin in the Admin Console.
If you are a Box Admin, you will find the necessary information in
[Enterprise Settings: Content & Sharing Tab][settings] documentation.

## Create and upload a Box Doc Gen template

To use Box Doc Gen API to generate documents, a Box Doc Gen template must already exist in Box. You have the following options to create a template:

* Install the [Box Doc Gen Template Creator add-in for Microsoft Word][template-addin].
* Create a Box Doc Gen template [using a JSON file][json-template] or manually create [template tags][template-tags].

## Create a platform application

First you need to create a platform application
you will use to make calls. To create
an application, follow the guide
on <Link href="/guides/applications/platform-apps/create">creating platform apps</Link>.

## Generate a developer token

You need a developer token
to authenticate your app when sending requests.

To generate a token:

1. Go to **Developer Console** > **My Platform Apps**.
2. Click the **Options menu** button (…) on the right.
3. Select **Generate Developer Token**. The token will be automatically generated and saved to clipboard.

<Frame>
  <img alt="generate token" />
</Frame>

You can also open your app, go to
**Configuration** > **Developer Token**
and generate the token.

<Note>
  A developer token is only valid for one hour.
</Note>

For additional details, see <Link href="/guides/authentication/tokens/developer-tokens">developer token</Link>.
After you generate the token, you can use it in cURL
or other clients, such as <Link href="/guides/tooling/postman">Postman</Link>, to make
calls.

## Use webhooks

You can create webhooks to monitor Doc Gen events and automate your business process or workflow.

Follow the instructions for <Link href="/guides/webhooks/v2/create-v2/">adding webhooks</Link>. Your content type is your Doc Gen template file or folder.

The supported <Link href="/guides/webhooks/triggers">events</Link> are:

* `DOCGEN_DOCUMENT_GENERATION_STARTED`
* `DOCGEN_DOCUMENT_GENERATION_SUCCEEDED`
* `DOCGEN_DOCUMENT_GENERATION_FAILED`

<Frame>
  <img alt="Doc Gen event triggers" />
</Frame>

Information that is posted in a notification:

* Trigger name.
* Webhook trigger timestamp.
* Template file ID.
* Template file version ID.
* Template file name.
* Destination folder.
* Generated file ID (if the document generation process succeeds).
* Output type (DOCX or PDF).
* Reason (if the document generation process fails).

[settings]: https://support.box.com/hc/en-us/articles/4404822772755-Enterprise-Settings-Content-Sharing-Tab#h_01FYQGK5RW42T07GV985MQ9E9A

[template-addin]: https://support.box.com/hc/en-us/articles/36587535449747-Installing-Box-Doc-Gen-Add-in

[template-tags]: https://support.box.com/hc/en-us/articles/36151895655059-Creating-A-Box-Doc-Gen-Template-Manually

[json-template]: https://support.box.com/hc/en-us/articles/36148012877843-Creating-a-Box-Doc-Gen-Template-using-JSON-data

<RelatedLinks title="RELATED GUIDES" />


# Box Doc Gen jobs
Source: https://developer.box.com/guides/docgen/docgen-jobs



A Box Doc Gen job runs when you make a request to generate a document.
The `document_generation_data` parameter in the `POST` request is an array of entries that represent Box Doc Gen jobs run to generate a document.

<CodeGroup>
  ```sh cURL theme={null}
  curl -L 'https://api.box.com/2.0/docgen_batches' \
       -H 'box-version: 2025.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>' \
       -D '{
          "file": {
              "id": "12345678",
              "type": "file"
          },
          "input_source": "api",
          "destination_folder": {
              "id": "12345678",
              "type": "folder"
          },
          "output_type": "docx",
          "document_generation_data": [
              {
                  "generated_file_name": "Image test",
                  "user_input": {
                      "order": {
                          "id": "12305",
                          "date": "18-08-2023",
                          "country": "US",
                          "expiryDate": "18-08-2024",
                          "currency": "$",
                          "amount": 5060.5,
                          "taxRate": 10,
                          "requester": "John",
                          "approver": "Smith",
                          "department": "Procurement",
                          "paymentTerms": "30 days",
                          "deliveryTerms": "30 days",
                          "deliveryDate": "18-09-2023",
                          "vendor": {
                              "company": "Example company",
                              "address": {
                                  "street": "Example street",
                                  "city": "Example city",
                                  "zip": "EX-456"
                              }
                          },
                          "products": [
                              {
                                  "id": 1,
                                  "name": "A4 Papers",
                                  "type": "non-fragile",
                                  "quantity": 100,
                                  "price": 29,
                                  "amount": 2900
                              },
                              {
                                  "id": 2,
                                  "name": "Ink  Cartridge",
                                  "type": "non-fragile",
                                  "quantity": 40,
                                  "price": 39,
                                  "amount": 1560
                              },
                              {
                                  "id": 3,
                                  "name": "Adhesive tape",
                                  "type": "non-fragile",
                                  "quantity": 20,
                                  "price": 30,
                                  "amount": 600.5
                              }
                          ]
                      }
                  }
              }
          ]`
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgen.createDocgenBatchV2025R0({
    file: new FileReferenceV2025R0({ id: uploadedFile.id }),
    inputSource: 'api',
    destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField({
      id: folder.id,
    }),
    outputType: 'pdf',
    documentGenerationData: [
      {
        generatedFileName: 'test',
        userInput: { ['abc']: 'xyz' },
      } satisfies DocGenDocumentGenerationDataV2025R0,
    ],
  } satisfies DocGenBatchCreateRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.docgen.create_docgen_batch_v2025_r0(
      FileReferenceV2025R0(id=uploaded_file.id),
      "api",
      CreateDocgenBatchV2025R0DestinationFolder(id=folder.id),
      "pdf",
      [
          DocGenDocumentGenerationDataV2025R0(
              generated_file_name="test", user_input={"abc": "xyz"}
          )
      ],
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Docgen.CreateDocgenBatchV2025R0Async(requestBody: new DocGenBatchCreateRequestV2025R0(file: new FileReferenceV2025R0(id: uploadedFile.Id), inputSource: "api", destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField(id: folder.Id), outputType: "pdf", documentGenerationData: Array.AsReadOnly(new [] {new DocGenDocumentGenerationDataV2025R0(generatedFileName: "test", userInput: new Dictionary<string, object>() { { "abc", "xyz" } })})));
  ```

  ```swift Swift v10 theme={null}
  try await client.docgen.createDocgenBatchV2025R0(requestBody: DocGenBatchCreateRequestV2025R0(file: FileReferenceV2025R0(id: uploadedFile.id), inputSource: "api", destinationFolder: DocGenBatchCreateRequestV2025R0DestinationFolderField(id: folder.id), outputType: "pdf", documentGenerationData: [DocGenDocumentGenerationDataV2025R0(generatedFileName: "test", userInput: ["abc": "xyz"])]))
  ```

  ```java Java v10 theme={null}
  client.getDocgen().createDocgenBatchV2025R0(new DocGenBatchCreateRequestV2025R0(new FileReferenceV2025R0(uploadedFile.getId()), "api", new DocGenBatchCreateRequestV2025R0DestinationFolderField(folder.getId()), "pdf", Arrays.asList(new DocGenDocumentGenerationDataV2025R0("test", mapOf(entryOf("abc", "xyz"))))))
  ```
</CodeGroup>

Box Doc Gen API allows you to get information about the Box Doc Gen jobs.

## Prerequisites

Before you start using Box Doc Gen API, follow the steps listed in the <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> guide to create a platform app and a Box Doc Gen template.

## List all Box Doc Gen jobs

To get a list of all Box Doc Gen jobs that were run,
use the `GET /2.0/docgen_jobs` endpoint. You don't have to provide any additional parameters.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/docgen_jobs" \
       -H 'box-version: 2025.0' \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgen.getDocgenJobsV2025R0({
    limit: 10000,
  } satisfies GetDocgenJobsV2025R0QueryParams);
  ```

  ```python Python v10 theme={null}
  client.docgen.get_docgen_jobs_v2025_r0(limit=10000)
  ```

  ```cs .NET v10 theme={null}
  await client.Docgen.GetDocgenJobsV2025R0Async(queryParams: new GetDocgenJobsV2025R0QueryParams() { Limit = 10000 });
  ```

  ```swift Swift v10 theme={null}
  try await client.docgen.getDocgenJobsV2025R0(queryParams: GetDocgenJobsV2025R0QueryParams(limit: Int64(10000)))
  ```

  ```java Java v10 theme={null}
  client.getDocgen().getDocgenJobsV2025R0(new GetDocgenJobsV2025R0QueryParams.Builder().limit(10000L).build())
  ```
</CodeGroup>

## Get a Box Doc Gen job by ID

To get a specific Box Doc Gen job,
use the `GET /2.0/docgen_jobs_id` endpoint and provide the `job_id`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/docgen_jobs/12345" \
       -H 'box-version: 2025.0' \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgen.getDocgenJobByIdV2025R0(docgenJobItemFromList.id);
  ```

  ```python Python v10 theme={null}
  client.docgen.get_docgen_job_by_id_v2025_r0(docgen_job_item_from_list.id)
  ```

  ```cs .NET v10 theme={null}
  await client.Docgen.GetDocgenJobByIdV2025R0Async(jobId: docgenJobItemFromList.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.docgen.getDocgenJobByIdV2025R0(jobId: docgenJobItemFromList.id)
  ```

  ```java Java v10 theme={null}
  client.getDocgen().getDocgenJobByIdV2025R0(docgenJobItemFromList.getId())
  ```
</CodeGroup>

## Get Box Doc Gen jobs in batch with a specific ID

A single request can generate several documents. In such a case, a separate generation job is run for each document and all these jobs are included in one "batch" meaning a request.
To get all jobs performed within one request, use the `GET /2.0/docgen_batch_jobs_id` endpoint and provide the `batch_id`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/docgen_jobs/12345" \
       -H 'box-version: 2025.0' \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgen.getDocgenJobByIdV2025R0(docgenJobItemFromList.id);
  ```

  ```python Python v10 theme={null}
  client.docgen.get_docgen_job_by_id_v2025_r0(docgen_job_item_from_list.id)
  ```

  ```cs .NET v10 theme={null}
  await client.Docgen.GetDocgenJobByIdV2025R0Async(jobId: docgenJobItemFromList.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.docgen.getDocgenJobByIdV2025R0(jobId: docgenJobItemFromList.id)
  ```

  ```java Java v10 theme={null}
  client.getDocgen().getDocgenJobByIdV2025R0(docgenJobItemFromList.getId())
  ```
</CodeGroup>

<RelatedLinks title="RELATED GUIDES" />


# Box Doc Gen templates
Source: https://developer.box.com/guides/docgen/docgen-templates



Box Doc Gen API allows you to retrieve information related to Box Doc Gen templates.

## Prerequisites

Before you start using Box Doc Gen API, follow the steps listed in the <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> guide to create a platform app and a Box Doc Gen template.

## List Box Doc Gen templates

To get a list of all created Box Doc Gen templates,
use the `GET /2.0/docgen_templates` endpoint. You don't have to provide any additional parameters.

<CodeGroup>
  ```sh cURL theme={null}
  curl -L 'https://api.box.com/2.0/docgen_templates' \
       -H 'box-version: 2025.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgenTemplate.getDocgenTemplatesV2025R0();
  ```

  ```python Python v10 theme={null}
  client.docgen_template.get_docgen_templates_v2025_r0()
  ```

  ```cs .NET v10 theme={null}
  await client.DocgenTemplate.GetDocgenTemplatesV2025R0Async();
  ```

  ```swift Swift v10 theme={null}
  try await client.docgenTemplate.getDocgenTemplatesV2025R0()
  ```

  ```java Java v10 theme={null}
  client.getDocgenTemplate().getDocgenTemplatesV2025R0()
  ```
</CodeGroup>

The response will contain an `entries` array listing the already created Box Doc Gen templates.

## Get a Box Doc Gen template by ID

To get a specific Box Doc Gen template,
use the `GET /2.0/docgen_templates_id` endpoint and provide the `template_id`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -L 'https://api.box.com/2.0/docgen_templates/12345678' \
       -H 'box-version: 2025.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgenTemplate.getDocgenTemplateByIdV2025R0(
    createdDocgenTemplate.file!.id,
  );
  ```

  ```python Python v10 theme={null}
  client.docgen_template.get_docgen_template_by_id_v2025_r0(
      created_docgen_template.file.id
  )
  ```

  ```cs .NET v10 theme={null}
  await client.DocgenTemplate.GetDocgenTemplateByIdV2025R0Async(templateId: NullableUtils.Unwrap(createdDocgenTemplate.File).Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.docgenTemplate.getDocgenTemplateByIdV2025R0(templateId: createdDocgenTemplate.file!.id)
  ```

  ```java Java v10 theme={null}
  client.getDocgenTemplate().getDocgenTemplateByIdV2025R0(createdDocgenTemplate.getFile().getId())
  ```
</CodeGroup>

The response will contain details of a file that was used as a Box Doc Gen template.

## List all document generation jobs for a template

To get a list of all created Box Doc Gen templates,
use the `GET /2.0/docgen_template_jobs_id` endpoint and provide the `template_id`.

<CodeGroup>
  ```sh cURL theme={null}
  curl -L 'https://api.box.com/2.0/docgen_template_jobs/12345678' \
       -H 'box-version: 2025.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgenTemplate.getDocgenTemplateJobByIdV2025R0(
    fetchedDocgenTemplate.file!.id,
  );
  ```

  ```python Python v10 theme={null}
  client.docgen_template.get_docgen_template_job_by_id_v2025_r0(
      fetched_docgen_template.file.id
  )
  ```

  ```cs .NET v10 theme={null}
  await client.DocgenTemplate.GetDocgenTemplateJobByIdV2025R0Async(templateId: NullableUtils.Unwrap(fetchedDocgenTemplate.File).Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.docgenTemplate.getDocgenTemplateJobByIdV2025R0(templateId: fetchedDocgenTemplate.file!.id)
  ```

  ```java Java v10 theme={null}
  client.getDocgenTemplate().getDocgenTemplateJobByIdV2025R0(fetchedDocgenTemplate.getFile().getId())
  ```
</CodeGroup>

The response will contain a list of Box Doc Gen jobs that were run to generate
documents.

<RelatedLinks title="RELATED GUIDES" />


# Generate documents
Source: https://developer.box.com/guides/docgen/generate-document



The `POST /2.0/docgen_batches` endpoint allows you to generate a document using Box Doc Gen template as input.

## Prerequisites

Before you start using Box Doc Gen API, follow the steps listed in the <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> guide to create a platform app and a Box Doc Gen template.

## Send a request

To generate a document or a set of documents,
use the `POST /2.0/docgen_batches` endpoint.

### Parameters

To make a call, you need to pass the following parameters.
Mandatory parameters are in **bold**.

| Parameter | Description | Example |
| - | - | - |
| **`file.id`** | ID of the file to be marked as Box Doc Gen template. | `12345678` |
| **`file.type`** | The type of provided input. The value is always **`file`**. | `file` |
| `file_version` | The file version of a template. | `12345` |
| **`input_source`** | The input source for generated document. The value has to be `api` for all the API-based document generation requests. | `api` |
| **`output_type`** | The output file type. | `docx`, `pdf` |
| **`destination_folder.id`** | The ID of the folder where the generated document will be stored. | `12345678` |
| **`destination_folder.type`** | The type of the destination item. Since the generated files are stored in folders, the value is always **`folder`**. | `file` |
| **`document_generation_data.generated_file_name`** | The name of the generated file. | `New_Template` |
| **`document_generation_data.user_input`** | The JSON data to be used to generate document. | `{"id": 2, "name": "Ink  Cartridge", "type": "non-fragile"}` |

## Use case

When your Box Doc Gen template and JSON data is ready, you can make a request to Box Doc Gen API to generate documents.

A sample call looks as follows:

<CodeGroup>
  ```sh cURL theme={null}
  curl -L 'https://api.box.com/2.0/docgen_batches' \
       -H 'box-version: 2025.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>' \
       -D '{
          "file": {
              "id": "12345678",
              "type": "file"
          },
          "input_source": "api",
          "destination_folder": {
              "id": "12345678",
              "type": "folder"
          },
          "output_type": "docx",
          "document_generation_data": [
              {
                  "generated_file_name": "Image test",
                  "user_input": {
                      "order": {
                          "id": "12305",
                          "date": "18-08-2023",
                          "country": "US",
                          "expiryDate": "18-08-2024",
                          "currency": "$",
                          "amount": 5060.5,
                          "taxRate": 10,
                          "requester": "John",
                          "approver": "Smith",
                          "department": "Procurement",
                          "paymentTerms": "30 days",
                          "deliveryTerms": "30 days",
                          "deliveryDate": "18-09-2023",
                          "vendor": {
                              "company": "Example company",
                              "address": {
                                  "street": "Example street",
                                  "city": "Example city",
                                  "zip": "EX-456"
                              }
                          },
                          "products": [
                              {
                                  "id": 1,
                                  "name": "A4 Papers",
                                  "type": "non-fragile",
                                  "quantity": 100,
                                  "price": 29,
                                  "amount": 2900
                              },
                              {
                                  "id": 2,
                                  "name": "Ink  Cartridge",
                                  "type": "non-fragile",
                                  "quantity": 40,
                                  "price": 39,
                                  "amount": 1560
                              },
                              {
                                  "id": 3,
                                  "name": "Adhesive tape",
                                  "type": "non-fragile",
                                  "quantity": 20,
                                  "price": 30,
                                  "amount": 600.5
                              }
                          ]
                      }
                  }
              }
          ]`
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgen.createDocgenBatchV2025R0({
    file: new FileReferenceV2025R0({ id: uploadedFile.id }),
    inputSource: 'api',
    destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField({
      id: folder.id,
    }),
    outputType: 'pdf',
    documentGenerationData: [
      {
        generatedFileName: 'test',
        userInput: { ['abc']: 'xyz' },
      } satisfies DocGenDocumentGenerationDataV2025R0,
    ],
  } satisfies DocGenBatchCreateRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.docgen.create_docgen_batch_v2025_r0(
      FileReferenceV2025R0(id=uploaded_file.id),
      "api",
      CreateDocgenBatchV2025R0DestinationFolder(id=folder.id),
      "pdf",
      [
          DocGenDocumentGenerationDataV2025R0(
              generated_file_name="test", user_input={"abc": "xyz"}
          )
      ],
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Docgen.CreateDocgenBatchV2025R0Async(requestBody: new DocGenBatchCreateRequestV2025R0(file: new FileReferenceV2025R0(id: uploadedFile.Id), inputSource: "api", destinationFolder: new DocGenBatchCreateRequestV2025R0DestinationFolderField(id: folder.Id), outputType: "pdf", documentGenerationData: Array.AsReadOnly(new [] {new DocGenDocumentGenerationDataV2025R0(generatedFileName: "test", userInput: new Dictionary<string, object>() { { "abc", "xyz" } })})));
  ```

  ```swift Swift v10 theme={null}
  try await client.docgen.createDocgenBatchV2025R0(requestBody: DocGenBatchCreateRequestV2025R0(file: FileReferenceV2025R0(id: uploadedFile.id), inputSource: "api", destinationFolder: DocGenBatchCreateRequestV2025R0DestinationFolderField(id: folder.id), outputType: "pdf", documentGenerationData: [DocGenDocumentGenerationDataV2025R0(generatedFileName: "test", userInput: ["abc": "xyz"])]))
  ```

  ```java Java v10 theme={null}
  client.getDocgen().createDocgenBatchV2025R0(new DocGenBatchCreateRequestV2025R0(new FileReferenceV2025R0(uploadedFile.getId()), "api", new DocGenBatchCreateRequestV2025R0DestinationFolderField(folder.getId()), "pdf", Arrays.asList(new DocGenDocumentGenerationDataV2025R0("test", mapOf(entryOf("abc", "xyz"))))))
  ```
</CodeGroup>

When the request is being processed, each entry in the `document_generation_data` array is treated as a separate document generation job that Box Doc Gen adds to the document generation queue.

Generated documents will be saved in the designated folder.

<RelatedLinks title="RELATED GUIDES" />


# Box Doc Gen
Source: https://developer.box.com/guides/docgen/index



<Warning>
  Box Doc Gen API is available only for Enterprise Advanced accounts.
</Warning>

Box Doc Gen allows you to generate business documents such as offer letters, sales contracts, invoices or agreements.
You can generate documents based on Box Doc Gen templates uploaded to Box, with data fields that can be dynamically filled using Box Doc Gen API.

<Note>
  Box Doc Gen only supports the ability to leverage English template tags when
  using Box Doc Gen templates. We recommend that customers test and review that Box Doc Gen supports their desired language requirements.
</Note>

## Prerequisites

To use Box Doc Gen, you must have access to Microsoft Word, as it is required
for creating and authoring your document templates. You can utilize the Box Doc
Gen Add-in for a code-free experience or apply tagging scripts within Word to
prepare your documents.

<Note>
  Box Doc Gen is designed to facilitate the dynamic generation of business
  documents, but it is important to note that Box does not have control over
  users’ access to Microsoft Word. Users must ensure they have the necessary
  permissions and access to Microsoft Word to create and author document
  templates effectively.
</Note>

## Box Doc Gen API capabilities

Box Doc Gen API allows you to:

* mark documents as Box Doc Gen templates,
* generate documents based on Box Doc Gen templates you store in Box,
* examine the details of Box Doc Gen templates and document generation jobs.

## Box Doc Gen API version

Box Doc Gen API was released in Box API version `2025.0`. All API requests to Box Doc Gen API endpoints must specify a valid API version by setting the `box-version` header to `2025.0`.

For more details, see <Link href="/guides/api-calls/api-versioning-strategy">Box API versioning</Link>.

## Box Doc Gen workflow

<Frame>
  <img alt="A flow diagram representing Box Doc Gen workflow" />
</Frame>

1. Author your Doc Gen Template
   * Use [Doc Gen Add-in for Microsoft Word][template-addin] to create a template without any code.
   * You can also leverage [Doc Gen's tagging script][tagging-script] to author the template.

2. [Add the template to Box][upload-template] using the Box Doc Gen UI. At this point, you can:
   * Mark an existing file in Box as Doc Gen template.
   * Create or Upload a document and mark it as a Box Doc Gen template.

3. <Link href="/guides/docgen/generate-document">Generate the document</Link> using Box Doc Gen API.

[template-addin]: https://support.box.com/hc/en-us/articles/36587535449747-Installing-Box-Doc-Gen-Add-in

[template-tags]: https://support.box.com/hc/en-us/articles/36151895655059-Creating-A-Box-Doc-Gen-Template-Manually

[json-template]: https://support.box.com/hc/en-us/articles/36148012877843-Creating-a-Box-Doc-Gen-Template-using-JSON-data

[tagging-script]: https://support.box.com/hc/en-us/articles/36149723736723-Template-tags-reference

[upload-template]: https://support.box.com/hc/en-us/articles/36587432368275-Managing-Box-Doc-Gen-Templates-in-Relay

<RelatedLinks title="RELATED GUIDES" />


# Manual split
Source: https://developer.box.com/guides/docgen/manual-split

Divide a PDF stored in Box into sub-documents using the exact page ranges you define.

A manual split divides a PDF into sub-documents using the exact page ranges you define.

Use this split type when you already know which pages belong together, such as a standard packet layout, a file an operator has reviewed, or page ranges supplied by an upstream system.

## Prerequisites

Before you start, follow the steps in the <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> guide to create a platform app and generate an access token.

You also need:

* A source PDF already stored in Box.
* A destination folder in Box that your app can write to.
* The page ranges for each output document.

If the boundaries depend on content or markers rather than fixed page numbers, use a <Link href="/guides/docgen/smart-split">smart split</Link> instead.

## What you configure

| Parameter | Description |
| - | - |
| `source_file_id` | The Box file ID of the PDF to split |
| `destination_folder_id` | The Box folder ID where Box stores the output documents |
| `split_input.split_type` | `manual` |
| `split_input.split_definition` | One or more page ranges, each with a `start` and an `end` |

Each `{ start, end }` pair creates one output document. Page numbers are 1-based and ranges are inclusive.

## Example

You have a 14-page sales packet and want two files, one for the order summary on pages 1 to 5 and one for the exhibits and terms on pages 6 to 14. The corresponding `split_definition` is:

```json theme={null}
[
  { "start": 1, "end": 5 },
  { "start": 6, "end": 14 }
]
```

## Create a manual split job

```sh cURL theme={null}
curl -L 'https://api.box.com/2.0/document_splits' \
     -H 'Accept: application/json; version=1' \
     -H 'box-version: 2026.0' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
       "source_file_id": "21040505661",
       "destination_folder_id": "10720019396",
       "input_source": "api",
       "split_input": {
         "split_type": "manual",
         "split_definition": [
           { "start": 1, "end": 5 },
           { "start": 7, "end": 9 }
         ]
       }
     }'
```

The response contains the ID of the split job:

```json theme={null}
{
  "id": "11678",
  "type": "document_split"
}
```

Use this ID to <Link href="/guides/docgen/doc-split">retrieve the status and the generated files</Link>.

## Best practices

* Use page ranges that do not overlap, so no page appears in more than one output document.
* Order your ranges by page number to match the reading order of the source PDF.
* Choose a manual split whenever the page numbers are already known, because the results are deterministic.
* Give destination folders meaningful names, such as `Splits / Customer A / 2026-07`, so reviewers can find the output quickly.

## When to use a smart split instead

Choose a <Link href="/guides/docgen/smart-split">smart split</Link> when:

* Break points are marked by QR codes or separator pages.
* You need to keep only certain types of content, such as signatures and ID proofs.
* Page ranges vary from file to file and are easier to describe than to calculate.

<RelatedLinks title="RELATED GUIDES" />


# Mark file as Box Doc Gen template
Source: https://developer.box.com/guides/docgen/mark-template



You can mark an existing document as a Box Doc Gen template and use it to generate documents.

## Before you start

Before you start using Box Doc Gen API, follow the steps listed in the <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> guide to create a platform app and a Box Doc Gen template.

## Send a request

To send a request containing your question,
use the `POST /2.0/docgen_templates` endpoint and
provide the mandatory parameters.

### Parameters

To make a call you need to pass the following parameters.
Mandatory parameters are in **bold**.

| Parameter | Description | Example |
| - | - | - |
| **`file.id`** | ID of the file to be marked as the Box Doc Gen template. | `12345678` |
| **`file.type`** | The type of provided input. The value is always **`file`**. | `file` |

## Use cases

### Mark a file as Box Doc Gen template

The following sample shows you how to mark a file to ensure it is recognized as a Box Doc Gen template.

<Note>
  The file must be in `.docx` format.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -L 'https://api.box.com/2.0/docgen_templates' \
       -H 'box-version: 2025.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>' \
       -H 'Content-Type: application/json' \
       -D '{
          "file": {
              "id": "12345678",
              "type": "file"
          }
  }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgenTemplate.createDocgenTemplateV2025R0({
    file: new FileReferenceV2025R0({ id: file.id }),
  } satisfies DocGenTemplateCreateRequestV2025R0);
  ```

  ```python Python v10 theme={null}
  client.docgen_template.create_docgen_template_v2025_r0(FileReferenceV2025R0(id=file.id))
  ```

  ```cs .NET v10 theme={null}
  await client.DocgenTemplate.CreateDocgenTemplateV2025R0Async(requestBody: new DocGenTemplateCreateRequestV2025R0(file: new FileReferenceV2025R0(id: file.Id)));
  ```

  ```swift Swift v10 theme={null}
  try await client.docgenTemplate.createDocgenTemplateV2025R0(requestBody: DocGenTemplateCreateRequestV2025R0(file: FileReferenceV2025R0(id: file.id)))
  ```

  ```java Java v10 theme={null}
  client.getDocgenTemplate().createDocgenTemplateV2025R0(new DocGenTemplateCreateRequestV2025R0(new FileReferenceV2025R0(file.getId())))
  ```
</CodeGroup>

### Remove Box Doc Gen template marking from a file

To make sure a file is no longer marked as a Box Doc Gen template,
use the `DELETE 2.0/docgen_templates/:template_id` request.

<CodeGroup>
  ```sh cURL theme={null}
  curl -L -X DELETE 'https://api.box.com/2.0/docgen_templates/12345678' \
       -H 'box-version: 2025.0' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.docgenTemplate.deleteDocgenTemplateByIdV2025R0(
    createdDocgenTemplate.file!.id,
  );
  ```

  ```python Python v10 theme={null}
  client.docgen_template.delete_docgen_template_by_id_v2025_r0(
      created_docgen_template.file.id
  )
  ```

  ```cs .NET v10 theme={null}
  await client.DocgenTemplate.DeleteDocgenTemplateByIdV2025R0Async(templateId: NullableUtils.Unwrap(createdDocgenTemplate.File).Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.docgenTemplate.deleteDocgenTemplateByIdV2025R0(templateId: createdDocgenTemplate.file!.id)
  ```

  ```java Java v10 theme={null}
  client.getDocgenTemplate().deleteDocgenTemplateByIdV2025R0(createdDocgenTemplate.getFile().getId())
  ```
</CodeGroup>

<RelatedLinks title="RELATED GUIDES" />


# Smart split
Source: https://developer.box.com/guides/docgen/smart-split

Use a natural language prompt to let Box decide how to group the pages of a PDF into output documents.

When `split_type` is `smart`, Box Doc Split uses your `prompt` to decide how to group and split pages into output documents. Clear, specific prompts produce more reliable splits.

<Note>
  A smart split consumes AI Units. Box consumes 1 AI Unit for every 4 pages processed.
</Note>

## Prerequisites

Before you start, follow the steps in the <Link href="/guides/docgen/docgen-getting-started">get started with Box Doc Gen</Link> guide to create a platform app and generate an access token.

You also need:

* A source PDF already stored in Box.
* A destination folder in Box that your app can write to.
* A prompt that describes how to group the pages.

## What you configure

| Parameter | Description |
| - | - |
| `source_file_id` | The Box file ID of the PDF to split |
| `destination_folder_id` | The Box folder ID where Box stores the output documents |
| `split_input.split_type` | `smart` |
| `split_input.prompt` | A natural language prompt that tells Box how to analyze the source PDF and identify the splits |

## Prompt guidelines

* State that the Box file you supply is the source document.
* Describe the splitting rule, such as a page count, a marker like a QR code, or a content criterion.
* Prefer sequential ranges when order matters, such as contract exhibits followed by signature pages.
* Call out the pages or sections to include, and where it helps, the ones to skip.
* Avoid ambiguous language such as "split somehow" or "use whatever makes sense."

## Example prompts

### Explicit page groups

Split a file into two documents whose ranges you describe in natural language.

```text theme={null}
Use this document as the source, and split the documents into 2 parts.
Pages 1-3 should be the first document, and pages 5-8 should be the second document.
```

This produces two outputs, corresponding to pages 1 to 3 and pages 5 to 8.

<Tip>
  If you already know the exact ranges, use `split_type: "manual"` with a `split_definition` instead. See <Link href="/guides/docgen/manual-split">manual split</Link> for deterministic results.
</Tip>

### QR code as a break point

Treat each QR code page as a separator between documents. Pages before a QR code form one split, and the QR code page itself is excluded unless you specify otherwise.

```text theme={null}
Use this document as the source. Identify individual pages that contain
a QR code, and use each QR code page as a breaking point between document
splits. Build the split definition so that if a QR code appears on page 5,
pages 1-4 are the first document. If the next QR code appears on page 11, 
pages 6-10 are the second document. Continue this pattern through the rest of the file.
```

This produces sequential ranges bounded by the marker pages. With markers on pages 5 and 11, the outputs cover pages 1 to 4 and pages 6 to 10.

### Content-based contractual pages

Keep only the pages with substantive contractual content, such as ID proofs, signatures, and executed terms, and skip the boilerplate terms and conditions. Split the retained sections sequentially.

```text theme={null}
Use this document as the source. Identify all pages that contain
real contractual details, such as ID proofs of the signers, signatures
of the signers, and other executed contractual details. Skip pages 
that only contain terms and conditions. Split the retained sections sequentially.
For example, if ID proofs are on pages 1-3 and executed signatures are on
pages 4-6, produce two documents: pages 1-3 and pages 4-6.
```

This produces one output for each contiguous block of content that matches the criteria, such as pages 1 to 3 and pages 4 to 6.

## Create a smart split job

```sh cURL theme={null}
curl -L 'https://api.box.com/2.0/document_splits' \
     -H 'Accept: application/json; version=1' \
     -H 'box-version: 2026.0' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
       "source_file_id": "2390226613215",
       "destination_folder_id": "406457672606",
       "input_source": "api",
       "split_input": {
         "split_type": "smart",
         "prompt": "Identify pages with QR codes in the source file, use each one as a breaking point, and split the document. For example, if there is a QR code on page 5, followed by a QR code on page 11, followed by a QR code on page 18, the result is 2 split documents. The first covers pages 5 to 11 and the second covers pages 12 to 18."
       }
     }'
```

The response contains the ID of the split job:

```json theme={null}
{
  "id": "11678",
  "type": "document_split"
}
```

Use this ID to <Link href="/guides/docgen/doc-split">retrieve the status and the generated files</Link>. The `split_definition` in that response shows the ranges Box derived from your prompt, so you can confirm the prompt produced the grouping you expected.

<RelatedLinks title="RELATED GUIDES" />


# Intelligent workflow
Source: https://developer.box.com/guides/intelligent-workflow/index

Build governed, agentic content workflows without running your own automation infrastructure.

Box is built for content-centric intelligent workflows. Box Automate orchestrates triggers, AI agents, people, and document steps on files and folders that already inherit Box permissions, collaboration, retention, and audit. Box Doc Gen produces business documents from templates and writes them back into that same governed content layer. Learn how to design work around the documents people already use, instead of copying content into a separate automation or AI system.

<Note>
  [Box Automate](https://developer.box.com/guides/box-automate/index) and
  [Box Doc Gen](https://developer.box.com/guides/docgen) are not included in
  the Free Developer Plan.
</Note>

## Why Box for intelligent workflows

Choose Box when the workflow's source of truth is **enterprise content** and you need automation, AI, and document production without leaving that content layer.

* **Content stays governed** — Workflows operate on Box files and folders. Access tokens and collaborations still apply; you do not bypass waterfall permissions by using the API. See the <Link href="/guides/security">security overview</Link>.
* **Event-driven and human-driven triggers** — Box Automate workflows can start from file/folder events, metadata, tasks, File Request, Box Sign, forms, manual start, or HTTPS.
* **AI as a workflow step** — Use Box AI in Automate to extract metadata, summarize content, or answer questions, then route the workflow based on that result.
* **Document production** — Box Doc Gen fills Microsoft Word templates from API JSON (or Box Automate outcomes) and writes generated `docx` or `pdf` files back into Box.
* **Cross-product handoffs** — One Box Automate flow can combine uploads, metadata, Box Doc Gen, Sign, tasks, notifications, and external HTTPS connectors.
* **Developer control** — Platform apps authenticate with standard Box auth, call content APIs, start manual workflows, and (where enabled) call Box Automate and Box Doc Gen endpoints.

<Tip>
  Box is **not** a general-purpose iPaaS for arbitrary SaaS-to-SaaS glue that never touches files. It is strongest when the process is document-centric: intake, classification, generation, review, signature, routing, and archival of content that must remain permissioned and auditable.
</Tip>

### Intelligent workflow capabilities

<CardGroup>
  <Card title="Box Automate" icon="gears" href={localizeLink("/guides/box-automate/index")}>
    Native, agentic workflow automation on Box content — triggers, AI agents, outcomes, branching, loops, and variables. Best for new intelligent workflows.
  </Card>

  <Card title="Box Doc Gen" icon="file-lines" href={localizeLink("/guides/docgen/index")}>
    Template-based document generation from templates and structured data.
  </Card>

  <Card title="Box Relay" icon="bolt" href={localizeLink("/guides/box-relay/index")}>
    List and start existing manual-start Box Relay workflows from your app with `GET /workflows` and `POST /workflows/:id/start`.
  </Card>
</CardGroup>

<Note>
  For **new** builds, use **Box Automate**. Existing applications that still list or start manual-start <Link href="/guides/box-relay/index">Box Relay</Link> workflows can keep using those APIs; prefer Automate for new projects.
</Note>

### Choose the right capability

<AccordionGroup>
  <Accordion title="Design a multi-step, agentic content process" icon="gears">
    Start with <Link href="/guides/box-automate/index">Box Automate</Link>. You get agentic orchestration with triggers, AI, branching, and human review in one runtime. See <Link href="/guides/box-automate/triggers-and-logic">triggers, outcomes, and logic</Link>.
  </Accordion>

  <Accordion title="React to uploads, metadata, Sign, File Request, or HTTPS" icon="bell">
    Start with <Link href="/guides/box-automate/index">Box Automate</Link>. Content-aware and external triggers start governed runs without custom workers. See <Link href="/guides/box-automate/triggers-and-logic">triggers, outcomes, and logic</Link>.
  </Accordion>

  <Accordion title="Start a workflow from your application with selected files" icon="play">
    Use <Link href="/guides/box-automate/getting-started-box-automate">Box Automate Manual Start</Link> or <Link href="/guides/box-relay/start-workflow">Box Relay manual start flows</Link>. Both support programmatic start; prefer Box Automate for new builds when it is enabled.
  </Accordion>

  <Accordion title="Generate PDFs or Word docs from a template and JSON" icon="file-lines">
    Start with <Link href="/guides/docgen/index">Box Doc Gen</Link>. It is a purpose-built generation API, and output lands in a Box folder. See <Link href="/guides/docgen/generate-document">generate documents</Link>.
  </Accordion>

  <Accordion title="Generate documents as one step inside a larger automation" icon="diagram-project">
    Use <Link href="/guides/box-automate/index">Box Automate</Link> + <Link href="/guides/docgen/index">Box Doc Gen</Link>. Automate can include document generation as an outcome; the Doc Gen API remains available for <Link href="/guides/docgen/generate-document">direct calls</Link>.
  </Accordion>

  <Accordion title="Only list and start existing Box Relay manual-start workflows" icon="bolt">
    Use <Link href="/guides/box-relay/index">Box Relay</Link>. List workflows with <Link href="/guides/box-relay/get-workflows">`GET /workflows`</Link> and start them with <Link href="/guides/box-relay/start-workflow">`POST /workflows/:id/start`</Link>.
  </Accordion>
</AccordionGroup>

## End-to-end intelligent content workflows

<Frame>
  <img alt="Diagram showing triggers, AI agents, and outcomes running inside Box Automate as the foundation layer on Box, with an HTTP connector" />
</Frame>

**Box Automate is the foundation layer** for intelligent content workflows. Triggers, AI agents, and outcomes are Automate workflow steps that run on governed Box content.

* **Triggers** — Folder and file events, plus Box Forms, start an Automate run when content or form input arrives.
* **AI agents** — Custom agents, Box Extract, and Box AI triage and enrich content inside the same Automate workflow.
* **Outcomes** — Add metadata, assign tasks, run file and folder actions, request signatures with Box Sign, generate documents with Box Doc Gen, or call external systems through the HTTP connector.

Automate itself sits on **Box**, while security and compliance, the content platform, collaboration, and integrations stay underneath every run.

Related capabilities often appear in the same solution design:

<CardGroup>
  <Card title="Box Sign" icon="pen-nib" href={localizeLink("/guides/box-sign/index")}>
    E-signature requests inside or after a workflow.
  </Card>

  <Card title="File Requests" icon="inbox" href={localizeLink("/guides/file-requests/index")}>
    Intake that can trigger Box Automate.
  </Card>

  <Card title="Box AI Studio" icon="robot" href={localizeLink("/guides/ai-studio/index")}>
    Custom agents used where Box Automate AI features are enabled.
  </Card>

  <Card title="Metadata" icon="tags" href={localizeLink("/guides/metadata/index")}>
    Structure used for triggers, branching, and extraction.
  </Card>

  <Card title="Webhooks and events" icon="bell" href={localizeLink("/guides/webhooks/index")}>
    Alternative or complementary event delivery for custom apps outside the builder.
  </Card>
</CardGroup>

## Box Automate

Box Automate is a workflow automation platform built natively on Box. You design **workflows** as directed graphs: a **trigger** starts a run, then **outcomes** execute until the flow ends. The builder supports conditional branching, loops, variables, and data passed between steps — including AI agent output.

### Why build on Box Automate

You can stitch the same outcomes together with webhooks, custom workers, and direct Box API calls. Box Automate is the better default when you want **governed automation** rather than another system to operate.

<Columns>
  <Card title="If you build it yourself" icon="server">
    * Host workers, queues, retries, and scheduling
    * Re-implement permission checks on every step
    * Assemble your own audit story across services
    * Wire AI, routing, tasks, and Doc Gen by hand
    * Add custom glue for every new content event
  </Card>

  <Card title="If you build on Box Automate" icon="gears">
    * Box runs the workflow runtime, without any automation infrastructure to manage
    * Steps inherit existing permissions and collaborations
    * Activity stays on Box content with enterprise audit and governance
    * Agentic and human steps live in one visual workflow
    * Content-aware triggers start runs for you
  </Card>
</Columns>

Use the Platform APIs when you need fine-grained, app-owned control of a single action. Use Automate when the product is the **process**: multi-step, content-centric work that must stay secure, observable, and maintainable without a private orchestration stack.

### Agentic orchestration with Box Automate

Box Automate's strategic differentiation is **agentic orchestration**: workflows that do not only move files on fixed rules, but also invoke AI agents, act on their output, and hand off to people or systems when judgment is required.

In practice, that means you can:

* **Run custom agents in-flow** — Where enabled for your enterprise, Automate AI capabilities work with custom agents that use knowledge sources, citations, and reasoning traces. See <Link href="/guides/ai-studio/index">Box AI Studio</Link> and the <Link href="/guides/box-automate/index">Box Automate overview</Link>.
* **Ground agents on Box content** — Extraction, summarization, and Q\&A run against the files and folders in the workflow, not a disconnected copy of the data.
* **Branch on agent output** — Structured AI results become variables and conditions for later outcomes (route, enrich metadata, generate a document, assign a task, or call an external API).
* **Keep humans in the loop** — Approval and general tasks sit beside agent steps so irreversible actions (delete, external share, legal send) can require review. Prefer a review step after AI when results must be verified.
* **Orchestrate the full content lifecycle** — One workflow can combine intake, agent triage, Doc Gen, Sign, collaboration, notifications, and HTTPS connectors under Box governance.

<Info>
  That combination of agents, content permissions, and durable workflow logic is what makes up a powerful platform for intelligent, agentic workflows. One workflow can also combine intake, agent triage, Doc Gen, Sign, collaboration, notifications, and HTTPS connectors under Box governance.
</Info>

### Triggers, outcomes, and logic

Exact trigger and outcome types depend on plan and configuration.

<Tabs>
  <Tab title="Triggers">
    * **File events** — Upload, move, copy, download, delete, preview, lock/unlock, watermark removed, collaborator added, classification applied, and file-with-metadata scenarios.
    * **Folder events** — Create, move, copy, download, delete, or collaborator added.
    * **Tasks** — General or approval task completion (including accepted/rejected).
    * **File Request** — Form completion that deposits content into a folder.
    * **Box Sign** — Completed, declined, expired, or cancelled.
    * **Metadata** — Template applied or field changes on a file or folder.
    * **Manual start** — User starts from the Box web app (also startable via API).
    * **Form submissions** — When Box Forms are enabled for your plan.
    * **HTTPS request** — An external system starts a run via a unique URL assigned to the workflow.
  </Tab>

  <Tab title="Outcomes">
    * **Files and folders** — Move, copy, rename, delete, lock/unlock, watermark, collaborate, classify, and related operations.
    * **Tasks and notifications** — Assign approval or general tasks; send email with variable-driven content.
    * **Metadata** — Apply, update, or extract metadata (including with AI).
    * **AI and agents** — Metadata extraction, summarization, or Q\&A; custom agents with knowledge sources, citations, and reasoning traces where enabled; use structured AI output in later conditions.
    * **Document generation and signatures** — Box Doc Gen and Box Sign outcomes where enabled.
    * **External systems** — Custom HTTPS request outcomes (connectors, auth, headers, JSON body), subject to admin allow-lists.
  </Tab>

  <Tab title="Logic">
    * Branching on conditions (for example approval accepted vs rejected, or AI classification result).
    * **For each** loops over users, files, or folder contents; **loop back** with a max count.
    * Variables and merging after parallel paths.
    * JSONPath-style reads of nested payloads when integrating over HTTPS.
  </Tab>
</Tabs>

To learn more, see <Link href="/guides/box-automate/triggers-and-logic">Triggers, outcomes, and logic</Link>.

### Developer integrations

<Steps>
  <Step title="Enable Box Automate">
    Work with your Box admin to enable Box Automate (and related products such as Box AI Studio). See <Link href="/guides/box-automate/getting-started-box-automate">Get started with Box Automate</Link>.
  </Step>

  <Step title="Start Manual Start workflows">
    List Manual Start workflows for a folder and trigger them with files and runtime fields (max 20 files per request).
  </Step>

  <Step title="Use the Automate Workflows API">
    Beta Automate Workflows API (`v2026.0`): <Link href="/reference/v2026.0/get-automate-workflows">list callable Box Automate workflows</Link> and <Link href="/reference/v2026.0/post-automate-workflows-id-start">start a Box Automate workflow</Link>.
  </Step>
</Steps>

## Box Doc Gen

Box Doc Gen generates business documents (offer letters, contracts, invoices, agreements, and similar) from **Box Doc Gen templates** stored in Box. Templates are authored in Microsoft Word ([add-in](https://docs.box.com/en/box-doc-gen/box-doc-gen-installation/installing-the-box-doc-gen-template-creator-add-in-for-microsoft-word) or [tagging scripts](https://docs.box.com/en/box-doc-gen/box-doc-gen-templates/template-tags-reference-guide-and-examples)). The API fills tagged fields from JSON and writes output to a destination folder.

<Warning>
  Box Doc Gen API is available only for **Enterprise Advanced** accounts. Currently, template tags are English-only; validate language requirements before production use. Control your own Microsoft Word access to author templates because Box does not control Word licensing.
</Warning>

### API capabilities

<CardGroup>
  <Card title="Mark templates" icon="tag" href={localizeLink("/guides/docgen/mark-template")}>
    Mark files as Box Doc Gen templates.
  </Card>

  <Card title="Generate documents" icon="file" href={localizeLink("/guides/docgen/generate-document")}>
    Generate documents (single or batch) from templates and API input.
  </Card>

  <Card title="Inspect jobs" icon="list-check" href={localizeLink("/guides/docgen/docgen-jobs")}>
    Inspect templates and document generation jobs.
  </Card>
</CardGroup>

All Box Doc Gen API requests must set the `box-version` header to `2025.0`. See <Link href="/guides/api-calls/api-versioning-strategy">Box API versioning</Link>.

### Typical generation flow

<Steps>
  <Step title="Use or create a template">
    Use a predefined sample template or create one with the Box Doc Gen [add-in](https://docs.box.com/en/box-doc-gen/box-doc-gen-installation/installing-the-box-doc-gen-template-creator-add-in-for-microsoft-word) or [tagging scripts](https://docs.box.com/en/box-doc-gen/box-doc-gen-templates/template-tags-reference-guide-and-examples).
  </Step>

  <Step title="Add the template to Box">
    Upload or mark the file as a Box Doc Gen template in Box.
  </Step>

  <Step title="Generate with the API">
    Call <Link href="/guides/docgen/generate-document">`POST /2.0/docgen_batches`</Link> with template file ID, `input_source: api`, JSON `user_input`, `output_type` (`docx` or `pdf`), and destination folder.
  </Step>
</Steps>

For more information, see the following developer guides: <Link href="/guides/docgen/docgen-getting-started">Get started</Link>, <Link href="/guides/docgen/mark-template">Mark template</Link>, <Link href="/guides/docgen/docgen-templates">Templates</Link>, and <Link href="/guides/docgen/docgen-jobs">Jobs</Link>.

## Learn more

<CardGroup>
  <Card title="Box Automate" icon="gears" href={localizeLink("/guides/box-automate/index")}>
    Agentic workflows with triggers, AI, branching, and integrations on Box content.
  </Card>

  <Card title="Get started with Box Automate" icon="rocket" href={localizeLink("/guides/box-automate/getting-started-box-automate")}>
    Enable Box Automate and trigger Manual Start workflows from the API.
  </Card>

  <Card title="Box Automate triggers and logic" icon="diagram-project" href={localizeLink("/guides/box-automate/triggers-and-logic")}>
    Trigger types, outcomes, branching, loops, and variables.
  </Card>

  <Card title="Box Doc Gen" icon="file-lines" href={localizeLink("/guides/docgen/index")}>
    Generate business documents from Word templates and API data.
  </Card>

  <Card title="Box AI Studio" icon="robot" href={localizeLink("/guides/ai-studio/index")}>
    Create and manage custom AI agents used in Automate and Box AI.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED APIS" />


# Get Legal Hold Policy
Source: https://developer.box.com/guides/legal-holds/get



To get the information for a specific Legal Hold policy that has been created in
an enterprise, call the <Link href="/reference/get-legal-hold-policies-id">`GET /legal_hold_policies/:id`</Link> API
endpoint with the `id` of the policy.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/legal_hold_policies/324432" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.legalHoldPolicies.getLegalHoldPolicyById(legalHoldPolicyId);
  ```

  ```python Python v10 theme={null}
  client.legal_hold_policies.get_legal_hold_policy_by_id(legal_hold_policy_id)
  ```

  ```cs .NET v10 theme={null}
  await client.LegalHoldPolicies.GetLegalHoldPolicyByIdAsync(legalHoldPolicyId: legalHoldPolicyId);
  ```

  ```swift Swift v10 theme={null}
  try await client.legalHoldPolicies.getLegalHoldPolicyById(legalHoldPolicyId: legalHoldPolicyId)
  ```

  ```java Java v10 theme={null}
  client.getLegalHoldPolicies().getLegalHoldPolicyById(legalHoldPolicyId)
  ```

  ```java Java v5 theme={null}
  BoxLegalHoldPolicy policy = new BoxLegalHoldPolicy(api, id);
  BoxLegalHoldPolicy.Info policyInfo = policy.getInfo();
  ```

  ```python Python v4 theme={null}
  legal_hold_policy = client.legal_hold_policy(policy_id='12345').get()
  print(f'The "{legal_hold_policy.policy_name}" policy is {legal_hold_policy.status}')
  ```

  ```cs .NET v6 theme={null}
  BoxLegalHoldPolicy policy = await client.LegalHoldPoliciesManager.GetLegalHoldPolicyAsync("11111");
  ```

  ```javascript Node v4 theme={null}
  client.legalHoldPolicies.get('11111')
  	.then(policy => {
  		/* policy -> {
  			type: 'legal_hold_policy',
  			id: '11111',
  			policy_name: 'IRS Audit',
  			description: '',
  			status: 'active',
  			assignment_counts: { user: 1, folder: 0, file: 0, file_version: 0 },
  			created_by: 
  			{ type: 'user',
  				id: '22222',
  				name: 'Example User',
  				login: 'user@example.com' },
  			created_at: '2016-05-18T10:28:45-07:00',
  			modified_at: '2016-05-18T11:25:59-07:00',
  			deleted_at: null,
  			filter_started_at: '2016-05-17T01:00:00-07:00',
  			filter_ended_at: '2016-05-21T01:00:00-07:00' }
  		*/
  	});
  ```
</CodeGroup>

## Required Scopes

Before using any of the Legal Hold APIs, an application must have the right
scopes enabled. See <Link href="/guides/legal-holds#required-scopes">Required Scopes</Link> for more details.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Legal Holds
Source: https://developer.box.com/guides/legal-holds/index



A legal hold is a process that an enterprise can use to preserve all forms of
potentially relevant information when litigation is pending or reasonably
anticipated. Applying a hold to items prevents any user from deleting them from
Box.

Legal Holds can be managed and assigned to folders and files through the Box
APIs.

<Info>
  Legal Holds are a feature of the [Box Governance][governance] package, which
  can be added on to any Business Plus, Enterprise Advanced or Enterprise account.
</Info>

## Policies, Assignments, and Holds

Working with Legal Hold Policies requires a developer to work with three
distinct resources.

* **Policies:**  A <Link href="/reference/resources/legal-hold-policy">Legal Hold Policy</Link> describes the general behavior of the hold. It determines which files should be affected, based on the date and time the files were created or updated.
* **Assignments:** A <Link href="/reference/resources/legal-hold-policy-assignment">Legal Hold Policy Assignment</Link> is a relation between a policy and custodian. In this case, a custodian can be a user, folder, file, or file version. Creating an assignment puts a hold on all the file versions that belong to the custodian. For example, if an assignment is created on a folder the policy is applied to all file versions within that folder.
* **Holds**: A <Link href="/reference/resources/file-version-legal-hold">File Version Legal Hold</Link> represents all the policies that are assigned to a specific file version. Note that every file version can have a maximum of one file version legal hold and this hold contains a list of every assigned policy.

## Example Use Case

If an order of discovery is received or the customer is part of an ongoing
litigation, a legal hold policy can be created to keep track of everything that
needs to be held. The actual holding is done by assigning a policy to a specific
file or folder. When the holds are no longer needed, the policy can be released
by deleting the assignment.

## Required Scopes

Before using any of the Legal Hold APIs, an application must have the <Link href="/guides/api-calls/permissions-and-errors/scopes">GCM and
Manage Legal Hold scopes</Link> enabled. These are not available in the
Developer Console and need to instead be enabled by contacting customer
support.

[governance]: https://www.box.com/security/governance-and-compliance


# List All Legal Hold Policies
Source: https://developer.box.com/guides/legal-holds/list



To list all Legal Hold Policies that have been created in an enterprise, call
the <Link href="/reference/get-legal-hold-policies">`GET /legal_hold_policies`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/legal_hold_policies" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.legalHoldPolicies.getLegalHoldPolicies();
  ```

  ```python Python v10 theme={null}
  client.legal_hold_policies.get_legal_hold_policies()
  ```

  ```cs .NET v10 theme={null}
  await client.LegalHoldPolicies.GetLegalHoldPoliciesAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.legalHoldPolicies.getLegalHoldPolicies()
  ```

  ```java Java v10 theme={null}
  client.getLegalHoldPolicies().getLegalHoldPolicies()
  ```

  ```java Java v5 theme={null}
  Iterable<BoxLegalHoldPolicy.Info> policies = BoxLegalHoldPolicy.getAll(api);
  for (BoxLegalHoldPolicy.Info policyInfo : policies) {
      // Do something with the legal hold policy.
  }
  ```

  ```python Python v4 theme={null}
  policies = client.get_legal_hold_policies()
  for policy in policies:
      print(f'Legal Hold Policy "{policy.name}" has ID {policy.id}')
  ```

  ```cs .NET v6 theme={null}
  BoxCollectionMarkerBased<BoxLegalHoldPolicy> policies = await client.LegalHoldPoliciesManager
      .GetListLegalHoldPoliciesAsync();
  ```

  ```javascript Node v4 theme={null}
  client.legalHoldPolicies.getAll({policy_name: 'Important'})
  	.then(policies => {
  		/* policies -> {
  			entries: 
  			[ { type: 'legal_hold_policy',
  				id: '11111',
  				policy_name: 'Important Policy 1' },
  				{ type: 'legal_hold_policy',
  				id: '22222',
  				policy_name: 'Important Policy 2' } ],
  			limit: 100,
  			order: [ { by: 'policy_name', direction: 'ASC' } ] }
  		*/
  	});
  ```
</CodeGroup>

## Required Scopes

Before using any of the Legal Hold APIs, an application must have the right
scopes enabled. See <Link href="/guides/legal-holds#required-scopes">Required Scopes</Link> for more details.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get Retention Policy
Source: https://developer.box.com/guides/retention-policies/get



To get the information for a specific Retention Policy that has been created in
an enterprise, call the <Link href="/reference/get-retention-policies-id">`GET /retention_policies/:id`</Link> API endpoint
with the `id` of the policy.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/retention_policies/982312" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.retentionPolicies.getRetentionPolicyById(retentionPolicy.id);
  ```

  ```python Python v10 theme={null}
  client.retention_policies.get_retention_policy_by_id(retention_policy.id)
  ```

  ```cs .NET v10 theme={null}
  await client.RetentionPolicies.GetRetentionPolicyByIdAsync(retentionPolicyId: retentionPolicy.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.retentionPolicies.getRetentionPolicyById(retentionPolicyId: retentionPolicy.id)
  ```

  ```java Java v10 theme={null}
  client.getRetentionPolicies().getRetentionPolicyById(retentionPolicy.getId())
  ```

  ```java Java v5 theme={null}
  // Get the policy name and status for a given retention policy
  BoxRetentionPolicy policy = new BoxRetentionPolicy(api, id);
  policy.getInfo("policy_name", "status");
  ```

  ```python Python v4 theme={null}
  retention_policy = client.retention_policy(retention_id='12345').get()
  print(f'Retention Policy ID is {retention_policy.id} and the name is {retention_policy.policy_name}')
  ```

  ```cs .NET v6 theme={null}
  BoxRetentionPolicy policy = await client.RetentionPoliciesManager.GetRetentionPolicyAsync("11111");
  ```

  ```javascript Node v4 theme={null}
  client.retentionPolicies.get('123456789').then((policy) => {
  	/* policy -> {
  			type: 'retention_policy',
  			id: '123456789',
  			policy_name: 'Tax Documents',
  			policy_type: 'indefinite',
  			retention_length: 'indefinite',
  			retention_type: 'modifiable',
  			description: 'Policy to retain all reports',
  			disposition_action: 'remove_retention',
  			can_owner_extend_retention: false,
  			status: 'active',
  			are_owners_notified: true,
  			custom_notification_recipients: []
  			assignment_counts: { enterprise: 0, folder: 1, metadata_template: 0 },
  			created_by:
  			{ type: 'user',
  				id: '11111',
  				name: 'Example User',
  				login: 'user@example.com' },
  			created_at: '2015-05-01T11:12:54-07:00',
  			modified_at: '2015-06-08T11:11:50-07:00' }
  		*/
  });
  ```
</CodeGroup>

## Required Scopes

Before using any of the Retention Policy APIs, an application must have the
right scopes enabled. See <Link href="/guides/retention-policies#required-scopes">Required Scopes</Link> for more details.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Retention Policies
Source: https://developer.box.com/guides/retention-policies/index



A retention policy blocks permanent deletion of content for a specified amount
of time. Admins can create retention policies and then assign them to
specific folders or their entire enterprise. Retention policies can be used to
keep data for as long as is needed, and then automatically delete the content
permanently when the data can no longer be legally held.

<Info>
  Retention Policies are a feature of the [Box Governance][governance] package,
  which can be added on to any Business Plus or Enterprise account.
</Info>

## Policies, Assignments, and Retentions

Working with Retention Policies requires a developer to work with three
distinct resources.

* **Policies:**  A <Link href="/reference/resources/retention-policy">Retention Policy</Link> describes the general behavior of the retention policy. It determines how long a retention should stay in place, if it can be extended, and what happens when the retention policy ends.
* **Assignments:** A <Link href="/reference/resources/retention-policy-assignment">Retention Policy Assignment</Link> is a relation between a policy and folder or enterprise. Creating an assignment puts a retention on all the file versions that belong to that folder or enterprise. For example, if an assignment is created on a folder the policy is applied to all file versions within that folder.
* **Retentions**: A <Link href="/reference/resources/file-version-retention">File Version Retention</Link> represents all the policies that are assigned to a specific file version. Note that every file version can have a maximum of one file version retention and that this resource contains a list of every assigned policy.

<Warning>
  The <Link href="/reference/resources/file-version-retention">file version retention</Link> section of the Box API
  is now deprecated. Instead, you can use <Link href="/reference/get-retention-policy-assignments-id-files-under-retention">files under retention</Link> or
  <Link href="/reference/get-retention-policy-assignments-id-file-versions-under-retention">file versions under retention</Link> endpoints.
</Warning>

## File Deletion with Retention Policies

Files under retention can be deleted from folders, but they will be retained in
the trash until the retention expires. When the retention expires,
you can choose to have the content automatically deleted or for the policy to be
removed.

## Extend Retention for a File

Files under retention can have their retention date extended by
<Link href="/reference/put-files-id/#param-disposition_at">updating</Link> the `disposition_at` field's value with a future
date. Once the date has been extended, it cannot be reverted or changed to be
prior to the new date.

## Required Scopes

Before using any of the Retention Policy APIs, an application must have the following <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link> enabled:

* <Link href="/guides/api-calls/permissions-and-errors/scopes#manage-retention-policies">Manage Retention Policies</Link>, available in the Developer Console under **Configuration** > **Application Scopes**
* <Link href="/guides/api-calls/permissions-and-errors/scopes#global-content-manager-gcm">Global Content Manager (GCM)</Link>, enabled by contacting customer support

[governance]: https://www.box.com/security/governance-and-compliance


# List All Retention Policies
Source: https://developer.box.com/guides/retention-policies/list



To list all Retention Policies that have been created in an enterprise, call
the <Link href="/reference/get-retention-policies">`GET /retention_policies`</Link> API endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/retention_policies" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.retentionPolicies.getRetentionPolicies();
  ```

  ```python Python v10 theme={null}
  client.retention_policies.get_retention_policies()
  ```

  ```cs .NET v10 theme={null}
  await client.RetentionPolicies.GetRetentionPoliciesAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.retentionPolicies.getRetentionPolicies()
  ```

  ```java Java v10 theme={null}
  client.getRetentionPolicies().getRetentionPolicies()
  ```

  ```java Java v5 theme={null}
  Iterable<BoxRetentionPolicy.Info> policies = BoxRetentionPolicy.getAll(api);
  for (BoxRetentionPolicy.Info policyInfo : policies) {
  	// Do something with the retention policy.
  }
  ```

  ```python Python v4 theme={null}
  retention_policies = client.get_retention_policies()
  for policy in retention_policies:
      print(f'The policy ID is {policy.id} and the name is {policy.policy_name}')
  ```

  ```cs .NET v6 theme={null}
  BoxCollectionMarkerBased<BoxRetentionPolicy> policies = await client.RetentionPoliciesManager
      .GetRetentionPoliciesAsync();
  ```

  ```javascript Node v4 theme={null}
  client.retentionPolicies.getAll({ policy_name: 'Tax' }).then((policies) => {
  	/* policies -> {
  			entries:
  			[ { type: 'retention_policy',
  				id: '123456789',
  				name: 'Tax Documents' } ],
  			limit: 100,
  			next_marker: 'someMarkerString' }
  		*/
  });
  ```
</CodeGroup>

## Required Scopes

Before using any of the Retention Policy APIs, an application must have the
right scopes enabled. See <Link href="/guides/retention-policies#required-scopes">Required Scopes</Link> for more details.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Cross-Origin Resource Sharing (CORS)
Source: https://developer.box.com/guides/security/cors



[Cross-Origin Resource Sharing (CORS)][mdn_cors] is a security mechanism used
by web browsers to prevent malicious websites from accessing data on other
sites (like the Box API) without explicit permission.

<Warning>
  CORS only applies to Box API requests made by a web page using a
  web browser, and it relies on the `HTTP Origin` header being passed along
  by the browser. It does not come into play in a server-side environment.
</Warning>

<Card href="https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS" title="Visit the MDN Web Docs for more generic information about CORS." />

## How CORS works

When a browser on one domain (for example `company.com`) tries to fetch
images, files, or even API resources from another domain (`box.com`),
the web browser will prevent access to any of those assets unless the right
CORS headers are present.

When the browser makes a cross-origin request, an `Origin` request header is
passed along with it that contains the domain of the site making that
request. This header can not be changed and is part of your web browser's
essential security.

By default, a browser will not accept any asset loaded from another domain
if there is no `Access-Control-Allow-Origin` response header present.
Servers like Box can explicitly list the domains allowed to access resources
on this server, or they can return a `*` value to allow any domain to access
the API.

## How Box uses CORS

Box uses the `Origin` request header and `Access-Control-Allow-Origin`
response header to enforce CORS rules defined by the developer.

### `Origin`-header validation

The Box API validates the `Origin` request header against the list of allowed
domains set by the application developer. Multiple allowed origins can be set
and any origin not on the list will return in an `HTTP 403` error.

```json theme={null}
{
  "type": "error",
  "status": 403,
  "code": "cors_origin_not_whitelisted",
  "context_info": {
    "origin": "https://company.com"
  },
  "help_url": "/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "Access denied - Did you forget to safelist your origin in the CORS config of your app?",
  "request_id": "4dsdfsa832213"
}
```

If no origin is set, all requests to the Box API for this application return
an error.

### `Access-Control-Allow-Origin` response header

After the Box API has validated the `Origin` header, it will return the data
requested as well as an `Access-Control-Allow-Origin` response header with
the value `*`.

```yaml theme={null}
HTTP/1.1 200 OK
Date: Wed, 23 Sep 2020 14:07:29 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Strict-Transport-Security: max-age=31536000
Cache-Control: no-cache, no-store
Access-Control-Allow-Origin: *
Vary: Origin
BOX-REQUEST-ID: 032cfb446dae4fd0b4c2bff80a1a97ba7
```

By returning this header, the Box API informs the web browser that the
response can be used in the site that requested the data.

## Enabling CORS for your domain

To enable CORS for the domain your application runs on, head over to the
developer console, select your application, and scroll down to the bottom of the
**Configuration** panel to find the **CORS Domains** setting.

Add a comma separated list of all the origins that you expect your application
to be making Box API requests from. Domains require the schema (`http` or
`https`) and can include wildcards for subdomains, for example `*.example.com`.

If your site runs on a non-standard port, it will also need to include that.
This is especially relevant for a site running on `localhost` or `127.0.0.1`.

An example list of origins would be as follows.

```sh theme={null}
https://company.com,https://*.internal.company.com,http://localhost:3000
```

## Debugging CORS

There are a few different kinds of CORS errors that might occur when making
API calls to the Box API.

### `HTTP 403` - No allowed origins defined

You might get this error even after you provided a list of origins. Often,
this is because of a typo in the provided origins.

1. **Check your origins** - Head back to the developer console and make sure your origins map the site you are making the API call from. Keep in mind that an origin includes the scheme (`http(s)`) but no path or trailing `/`. We recommend inspecting the page using your browser's debug console and checking the `Origin` request header value. This value should match one of the provided values in the developer console.
2. **Check your credentials** - Another reason for this error might be that you are authenticating as a different application than the one you have set the origin up for. Check that the credentials match the ones of the application you are intending to use. We recommend trying to make a call from a server-side script to validate that the API call works.

### `Cross-Origin Request Blocked`

In some cases, you might get a Javascript error that mentions CORS.

```sh theme={null}
Cross-Origin Request Blocked: The Same Origin Policy disallows reading
the remote resource at https://api.box.com/2.0/users/me. (Reason: CORS
request did not succeed).
```

In many cases this has little to do with CORS. Instead we recommend checking the
following.

1. **Check your authentication headers** - If the authorization header is not provided or malformed, then the API will return a generic error without the necessary `Access-Control-Allow-Origin` header. This in turn will cause the previously mentioned error to be raised by your browser. Make sure to pass in an access token using the `Authorization: Bearer ...` header.
2. **Check for requests blocked by VPN, Proxies, etc** - In some cases, the Box API might be blocked by your VPN, corporate proxy, a browser extension, your DNS provider, or any other service that can intercept network traffic. Any of these can intercept the request and return a whole new request that does not include the necessary `Access-Control-Allow-Origin` header. To test for this case, try to make the same API call from a non-browser environment, from an incognito window, or from a whole other (not company owned) device.

[mdn_cors]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS

### `Access-Control-Allow-Origin` header issues

If you encounter issues with the `Access-Control-Allow-Origin` header, do the following:

1. **Check if your domain is on the list of allowed origins** - Go to the developer console and open your application. Click on the **Configuration** tab and scroll down. You can add your domain to the list in section **CORS domains**.

<Frame>
  <img alt="CORS allowlist" />
</Frame>

2. **Check if your server is set up correctly** - Configure your server to handle cross-domain requests or use non-cross-domain requests if you receive a warning **No 'access-control-allow-origin' header is present on the requested resource**.


# Device Pinners
Source: https://developer.box.com/guides/security/device-pinners



Building on the login tracking feature – which allows admins to set limits on
the number of devices a user can access Box from and sends alerts to them and
the user whenever a new device is used to access that Box account – Box has
additional device management functionality to increase security when accessing
Box on mobile or desktop devices: device pinning.

To learn more about device pinning, please see our [community
documentation][community].

## APIs

The Box API allows for device pins to be inspected and removed.

* <Link href="/reference/get-enterprises-id-device-pinners">`GET /enterprise/:id/device_pinners`</Link>: Retrieves all the device pins within an enterprise.
* <Link href="/reference/get-device-pinners-id">`GET /device_pinners/:id`</Link>: Retrieves information about an individual device pin.
* <Link href="/reference/delete-device-pinners-id">`DELETE /device_pinners/:id`</Link>: Deletes an individual device pin.

[community]: https://support.box.com/hc/en-us/articles/360043693814-Device-Pinning-Settings


# FedRAMP
Source: https://developer.box.com/guides/security/fedramp



## Overview

FedRAMP is a certification program that allows federal agencies to use cloud
providers for increasingly secure/sensitive government or government-adjacent
data.

FedRAMP defines three categories regarding levels of security, Low, Moderate,
and High.

The higher the security level the more restrictions are in place.

Box is currently certified as [FedRAMP High][FedRAMPCert].

## Considerations

In order to be FedRAMP compliant, your administrator must set up Box in
a very specific way. It is possible that the administrator has further
restricted access to Box functionalities.

Consult with your administrator to identify security restrictions in place that
might affect the usage of the API.

## API usage in FedRAMP

For FedRAMP compliance, you may use the below URLs for API entry points.

| FedRAMP |
| - |
| account.box.com |
| api.box.com |
| upload.box.com |
| dl.boxcloud.com |
| realtime.services.box.net |

[FedRAMPCert]: https://marketplace.fedramp.gov/products/F1212191840A


# Security
Source: https://developer.box.com/guides/security/index



Whether you are a developer getting started with the Box API or a Box Admin
tasked with <Link href="/guides/authorization">authorizing</Link> applications, it is critical you understand the
security mechanisms in place to protect content stored in Box.

The Box API follows the same security principles and restrictions as the Box web
app. This means that you will not be able to bypass content [permissions][perm],
the [waterfall folder structure][waterfall], or Admin-only requirements by
leveraging the Box API.

## Access Tokens

At the core of every Box API call is an <Link href="/guides/authentication/tokens">Access Token</Link>. Because a username
and password cannot be used, the Box servers need a way of validating user
identity. The full capability of an Access Token encompasses user permissions,
token permissions, and application settings.

<Frame>
  <img alt="Access Token Components" />
</Frame>

Access Tokens represent the authenticated user and determine what content a
user can successfully call. Similar to using the Box Web App, you will only be
able to successfully interact with content the user, associated with the Access
Token, either owns or is a collaborator on. This can be further restricted by
<Link href="/guides/authentication/tokens/downscope">downscoping</Link> a token.

<Link href="/guides/authentication/tokens">Access Tokens</Link> are only valid for 60 minutes, but can be <Link href="/reference/post-oauth2-revoke">revoked</Link>
earlier if needed. Once an Access Token expires, when using an OAuth 2.0
application, a <Link href="/guides/authentication/tokens/refresh">Refresh Token</Link> can be <Link href="/reference/post-oauth2-token--refresh">exchanged</Link> for another
Access Token. Refresh tokens are valid for 60 days or one use. Alternatively,
when using a server authentication application, the
<Link href="/reference/post-oauth2-token">request Access Token endpoint</Link> must be called for a new Access Token.
For security reasons we do not allow long-lived access tokens.

<Tip>
  Unsure why you are receiving a 404 error? A great place to start is checking
  to see what user is associated with your Access Token by using the get
  current user endpoint.
</Tip>

## Scopes

<Frame>
  <img alt="Scopes" />
</Frame>

<Link href="/guides/api-calls/permissions-and-errors/scopes">Scopes</Link> are configured in the [Developer Console][dc] upon application
creation. They determine which of the 150+ endpoints Access Tokens of an
application can successfully call.

Because scopes work in conjunction with user permissions, granting the write
scope does not automatically provide a user with API access to all content in a
Box enterprise. Instead, it means that the authenticated user can receive
successful API responses when making write calls to content they have access to.

For example, take an application with only the manage users and manage groups
scopes enabled. If an Access Token of this application tried to make an API call
to get information about a folder, even if the associated user owned it, it
would receive a 403 error. This is because the read scope is required to
perform this action. Access Tokens of this application could only receive
successful responses on API calls related to users and groups.

## Restricted endpoints

There are some API endpoints that only Admins or Co-Admins, granted the
appropriate [permissions][coadminperm], can successfully use. As a general rule
of thumb, if only an Admin or Co-Admin can perform an action via the Box Admin
Console, an Access Token associated with one of these users is required to
complete an API call for the same action. This is called out in our API
<Link href="/reference">reference</Link> documentation for a given endpoint if it is required.

Some Admin-restricted endpoints include:

* Creating, deleting, or getting information about <Link href="/reference/resources/user">users</Link>
* Creating, deleting, or modifying <Link href="/reference/resources/group">groups</Link>
* Viewing user or enterprise <Link href="/reference/resources/event">events</Link>

Other endpoints can only be used by an Admin user's Access Token if the
enterprise has purchased add-on products such as Box Governance or Box Shield.
Some of these endpoints include:

* Interacting with <Link href="/reference/resources/classification">security classifications</Link>
* Interacting with <Link href="/reference/resources/legal-hold-policy">legal hold policies</Link> and <Link href="/reference/resources/legal-hold-policy-assignment">assignments</Link>
* Interacting with <Link href="/reference/resources/retention-policies">retention policies</Link> and <Link href="/reference/resources/retention-policy-assignment">assignments</Link>

## Application Access

<Frame>
  <img alt="Application Access Settings" />
</Frame>

Application access is only configured in the [Developer Console][dc] for
applications leveraging Server Authentication with <Link href="/guides/authentication/jwt">JWT</Link> or
<Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>. This setting determines the
<Link href="/guides/getting-started/users">types of users</Link> that can be used with the application. The two
options are **app access only** or **app + enterprise access**.

Upon <Link href="/guides/authorization">authorizing</Link> one of these applications in the Box Admin Console, a
<Link href="/guides/getting-started/users#service-account">Service Account</Link> (`AutomationUser_xxxx_@boxdevedition.com`)
representing the application is automatically generated. This account is an
Admin-like user that can only be accessed via the API and can then be used to
create users of the application called <Link href="/guides/getting-started/users#app-user">App Users</Link>. If an application
only needs to interact with the Service Account and App Users, or with content
they own or are collaborated on, **app only access** must be selected. If an
application needs to interact with
<Link href="/guides/getting-started/users#managed-users">managed users</Link> and their existing Box content, app + enterprise access must
be selected.

As an example, take a JWT application that has the read/write scopes,
app only access, and is properly <Link href="/guides/authorization">authorized</Link> in the Admin console. If a
managed user obtains an Access Token and makes an API call to a folder they own,
that call would receive a 400 error with the message “Cannot obtain token based
on the enterprise configuration for your app”. Even though the user has access
to the content, the correct scopes are enabled and the app is authorized,
the selected application access only allows the application to interact with the
Service Account and App Users.

## Enterprise settings and authorization

There are a few enterprise settings to be aware of when it comes to the Box API.

<Frame>
  <img alt="Global Integration Settings" />
</Frame>

Platform applications fall into two categories: published and unpublished.
Published applications are found in the [Box Integrations][appcenter]. Box
Admins decide whether published and unpublished applications are enabled by
default and therefore can be used without approval. The status of these settings
determines what actions are necessary to successfully <Link href="/guides/authorization">authorize</Link> an
application for use.

<Frame>
  <img alt="Admin Console Apps Tab" />
</Frame>

Regardless of the settings above, in order for an application leveraging
<Link href="/guides/authentication/jwt">JWT</Link> or <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link> to be used by an enterprise, an
Admin must explicitly <Link href="/guides/authorization">authorize</Link> it via the Box Admin console. The
authorization is a snapshot in time. This means that if a developer revisits
the Developer Console and changes the configuration, the Admin must re-authorize
the application in order for generated Access Tokens to reflect the changes.

If the setting **Disable unpublished apps by default** is turned on, an Admin
must also explicitly <Link href="/guides/authorization">enable</Link> any application leveraging
<Link href="/guides/authentication/oauth2">OAuth 2.0</Link> as the authentication method.

Additionally, if this setting is turned on, Server Authenticated apps will also
require enablement.

[perm]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels

[waterfall]: https://support.box.com/hc/en-us/articles/360043697254-Understanding-Folder-Permissions

[coadminperm]: https://support.box.com/hc/en-us/articles/360044194393-Granting-And-Modifying-Co-Admin-Permissions

[dc]: https://app.box.com/developers/console

[appcenter]: https://app.box.com/services


# Application Flow
Source: https://developer.box.com/guides/security/terms-of-service/flow



In general, applications use Terms of Services as follows.

When an application, authenticated as a user, tries to access an item in Box that
requires the user to have accepted the relevant Terms of Service it receives a
`TERMS_OF_SERVICE_REQUIRED` error.

```json theme={null}
{
  "type": "error",
  "status": 400,
  "code": "terms_of_service_required",
  "context_info": {
    "tos_id": 261346614,
    "tos_user_status_id": 4562456
  },
  "help_url": "/guides/api-calls/permissions-and-errors/common-errors/",
  "message": "User must accept custom terms of service before action can be taken",
  "request_id": "ADF7722DD"
}
```

The application requests the Terms of Service's information by calling
<Link href="/reference/get-terms-of-services-id">`GET /terms_of_services/:id`</Link>.

```json theme={null}
{
  "id": 261346614,
  "type": "terms_of_service",
  "status": "enabled",
  "enterprise": {
    "id": 11446498,
    "type": "enterprise",
    "name": "Acme Inc."
  },
  "tos_type": "managed",
  "text": "By using this service, you agree to ...",
  "created_at": "2012-12-12T10:53:43-08:00",
  "modified_at": "2012-12-12T10:53:43-08:00"
}
```

The application can then show the text from the Terms of Service to the user.

When the user accepts or rejects the terms, it makes a call to either
<Link href="/reference/put-terms-of-service-user-statuses-id">`PUT /terms_of_service_user_statuses/:id`</Link> or
<Link href="/reference/post-terms-of-service-user-statuses">`POST /terms_of_service_user_statuses`</Link> depending on if the initial
error returned a `tos_user_status_id` in the response.

## Server authentication and acting on behalf of users

Applications using JWT, Client Credentials Grant (CCG), or OAuth 2.0 may act as
a <Link href="/guides/getting-started/users#service-account">service account</Link>, an <Link href="/guides/getting-started/users#app-user">App User</Link>, or a managed user.
Terms of Service enforcement depends on which user is in context for the API
request.

| Scenario | Blocked if Managed Terms of Service not accepted? |
| - | - |
| API call with a service account or App User token (no `As-User`) | **No** — headless users are exempt |
| API call with CCG/JWT and <Link href="/guides/authentication/oauth2/as-user">`As-User`</Link> set to a managed user | **Yes** — the user specified in the `As-User` header must have accepted |
| User access token issued for a managed user | **Yes** — token issuance is blocked until Terms of Service is accepted |
| OAuth authorization code flow for a managed user | **Yes** — authorization is blocked until Terms of Service is accepted |
| API call with `As-User` set to a service account or App User | **No** — headless users are exempt |

### Accepting Terms of Service programmatically

When a managed user has not accepted Managed Terms of Service, most API calls
made on their behalf return `terms_of_service_required`. To resolve this
without requiring the user to sign in to the Box web application:

1. Obtain a server authentication access token (JWT or CCG).
2. Set the <Link href="/guides/authentication/oauth2/as-user">`As-User`</Link> header to the managed user's ID so subsequent
   requests run in that user's context.
3. Call the Terms of Service endpoints, which remain available even when Terms
   of Service acceptance is outstanding:
   * <Link href="/reference/get-terms-of-services-id">`GET /terms_of_services/:id`</Link> to retrieve the terms text
   * <Link href="/reference/post-terms-of-service-user-statuses">`POST /terms_of_service_user_statuses`</Link> or
     <Link href="/reference/put-terms-of-service-user-statuses-id">`PUT /terms_of_service_user_statuses/:id`</Link> to accept or reject
4. Retry the original API call.

An admin cannot accept Managed Terms of Service for another user without using
the `As-User` header to act as that user. Acceptance must be recorded for the
user who is subject to the Terms of Service.


# Find Terms for Collaboration
Source: https://developer.box.com/guides/security/terms-of-service/for-colaboration



Information about the Terms of Service that is in effect for any
<Link href="/reference/resources/collaboration">Collaboration</Link> can be inspected by calling the
<Link href="/reference/get-collaborations-id">`GET /collaborations/:id`</Link> API and passing the query
parameter `fields=acceptance_requirements_status`.

```sh cURL theme={null}
curl -X GET https://api.box.com/2.0/collaborations/2342342?fields=acceptance_requirements_status \
    -H "authorization: Bearer <ACCESS_TOKEN>"
```

The resulting response will include a new `acceptance_requirements` object that
includes a mini `terms_of_service` object.

```json theme={null}
{
  "type": "collaboration",
  "id": 2342342>,
  "acceptance_requirements": {
    "terms_of_service": {
      "type": "terms_of_service",
      "id": 6766677
    }
  }
}
```

<Info>
  This information is only returned if the Terms of Service for external users is
  enabled for the enterprise, and the user making the request has the
  <Link href="/guides/security/terms-of-service/permissions">permission</Link> to see the Terms of Service. This holds true for
  both admin and end users, even though admins can generally view Terms of User
  information via the API even if the specific Terms of Service type is
  turned off.
</Info>

If the Terms of Service type is not enabled, the API will return an empty
result.

```json theme={null}
{
  "type": "collaboration",
  "id": 2342342>,
  "acceptance_requirements": {
    "terms_of_service": null
  }
}
```

<Info>
  The `terms_of_service` information is returned within the
  `acceptance_requirements` even if they have already been accepted by the user.
</Info>


# Terms of Service
Source: https://developer.box.com/guides/security/terms-of-service/index



The Box API allows administrators to configure Terms of Services for working on
Box, and for users to accept & re-accept Terms of Services for custom
applications.

## Terminology

### Terms of Services

A Terms of Service is an enterprise-level record that represents the conditions
within which all users are allowed to work with an enterprise's data in Box.

There are currently two types of Terms of Service for any enterprise that can be
enabled independently. The **Managed Terms of Service** can be
enabled for the enterprise's own users, where the **External Terms of Service**
can be enabled for users from other enterprises that collaborated on the
primary enterprise's data.

### Who is subject to Managed Terms of Service?

When Managed Terms of Service is enabled for an enterprise, it applies to
**login-capable managed users** in that enterprise. These are users who can sign
in to Box (for example, standard managed users with credentials).

The following user types are **not** subject to Managed Terms of Service, even
though they belong to the enterprise:

| User type | Managed Terms of Service required? |
| - | - |
| Admin/Co-Admin and Managed user (can log in to Box) | **Yes** |
| <Link href="/guides/getting-started/users#service-account">Service account</Link> (Automation User) | **No** |
| <Link href="/guides/getting-started/users#app-user">App User</Link> | **No** |

Service accounts and App Users are API-only, headless users. They are exempt
from Managed Terms of Service enforcement. The Admin Console setting for
managed users refers to these login-capable users, not every enterprise member.

## Terms of Service User Statuses

A Terms of Service User Status represents the status of the Terms of Service
acceptance for a specific user. There is exactly one Terms of Service User
Status for any given combination of Terms of Service and a user.

There are multiple Terms of Service User Statuses for any Terms of Service,
specifically one for each user.

There could be multiple Terms of Service User Statuses for a given user. The
user could accept or reject multiple External Terms of Services for different
enterprises they have been collaborated into, in addition to accepting or
rejecting their own enterprise’s Managed Terms of Service.

## APIs

Applications that are authenticated as a Box Admin that has the **Edit settings
for your company** permissions can view, create, and edit Terms of Services for
their enterprise via the API.

* <Link href="/reference/get-terms-of-services-id">`GET /terms_of_services/:id`</Link>: To get the information for a specific Terms of Service
* <Link href="/reference/get-terms-of-services">`GET /terms_of_services`</Link>: To get a list of all the Terms of Services used within an enterprise, either for managed or external users.
* <Link href="/reference/post-terms-of-services">`POST /terms_of_services`</Link>: To create Terms of Service settings for either an external or managed user.
* <Link href="/reference/put-terms-of-services-id">`PUT /terms_of_services/:id`</Link>:
  To update a specific Terms of Service setting

Additionally, an application can view and accept Terms of Services for a regular
user via the API.

* <Link href="/reference/get-terms-of-service-user-statuses">`GET /terms_of_service_user_statuses`</Link>: To get a list of all the Terms of Services for a user
* <Link href="/reference/post-terms-of-service-user-statuses">`POST /terms_of_service_user_statuses`</Link>: To accept or reject a specific Terms of Service for the first time
* <Link href="/reference/put-terms-of-service-user-statuses-id">`PUT /terms_of_service_user_statuses/:id`</Link>: To accept or reject a specific Terms of Service that had been previously accepted or rejected.

## Scopes

The following scopes should be granted to the application in order to take the
outlined actions.

* **Manage Enterprise Properties**: Required to enable or edit the enterprise's settings for Terms of Services as well as to view them for external users.
* **Manage Users**: Required to accept Terms of Services for other users.


# Permissions
Source: https://developer.box.com/guides/security/terms-of-service/permissions



The following is a list of permissions users, admins, and co-admins need to have
when working with Terms of Services and Terms of Service Statuses.

## Terms of Service

An end user is considered subject to Terms of Service when:

* User belongs to or is collaborated into an enterprise that has a Terms of Service enabled
* The type of Terms of Service reflects the user's relationship to the Enterprise
  * A managed Terms of Service for a user that is part of the same enterprise
  * An external Terms of Service for users collaborating into the enterprise

For **Managed** Terms of Service specifically, the user must also be a
login-capable managed user. <Link href="/guides/getting-started/users#service-account">Service accounts</Link> and
<Link href="/guides/getting-started/users#app-user">App Users</Link> are headless users and are not subject to Managed Terms
of Service, even when they belong to the enterprise.

Terms of Service settings can be viewed by an end user if:

* The user is subject to a Terms of Service; and
* The Terms of Service Type is enabled on the enterprise

A Terms of Service's settings can be viewed by an enterprise admin or co-admin
if:

* They have **View settings for your company** permissions
* The application has the **Manage enterprise properties** scope enabled
* The Terms of Service belongs to their enterprise

Terms of Service settings can be edited by an enterprise admin or co-admin if:

* They have **Edit settings for your company** permissions
* The application has the **Manage enterprise properties** scope enabled
* The Terms of Service belongs to their enterprise

Enterprise admins and co-admins can view, create, and edit Terms of Service
settings for both external and managed Terms of Service without having accepted
the managed Terms of Service for their own enterprise.

## Terms of Service User Status

Terms of Service User Status can be viewed and edited by an end user if:

* The User Status belongs to the end user
* The Terms of Service type is enabled on the enterprise
* The end user is subject to the Terms of Service

Terms of Service User Statuses belonging to other users can be viewed by
enterprise admins and co-admins if:

* They have **Manage users** permissions
* The application has the **Manage users** scope enabled
* The Terms of Service belongs to their enterprise
* They have accepted the managed Terms of Service for their own enterprise, if applicable

Terms of Service User Status belonging to other users can be edited by
enterprise admins and co-admins if:

* They have **Manage users** permissions
* The application has the **Manage users** scope enabled
* The application has the <Link href="/guides/authentication/oauth2/as-user">**As-User**</Link> scope enabled
* The end user is subject to the Terms of Service
* The end user is not an admin or co-admin
* The Terms of Service belongs to their enterprise
* They have accepted the managed Terms of Service for their own enterprise, if applicable

An end user cannot accept, reject, view external Terms of Service settings for
an enterprise they are collaborating into until the end user accepts the managed
Terms of service for their own enterprise, where applicable. Trying to do so
will result in a `TERMS_OF_SERVICE_REQUIRED` error.


# Bulk delete external users
Source: https://developer.box.com/guides/users/bulk-delete-external-users



You can remove up to 100 external users from your enterprise using the API.
This API endpoint removes access to all types of content you invited the
listed external users to collaborate on.

To remove the external users, call
<Link href="/reference/v2025.0/post-external-users-submit-delete-job">`POST /external_users/submit_delete_job`</Link>.

<Note>
  This endpoint requires API version `2025.0`. Include the `box-version: 2025.0` header in your request.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/external_users/submit_delete_job" \
       -H "box-version: 2025.0" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "external_users": [
           {
             "type": "user",
             "id": "<EXTERNAL_USER_ID>"
           }
         ]
       }'
  ```
</CodeGroup>

This job runs in the background, and sends a completion report listing deletion status for each user when it's finished.

<Note>
  When you delete external users, their pending collaboration invites are not deleted.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create App User
Source: https://developer.box.com/guides/users/create-app-user



App Users are programmatic user accounts that can be created by apps
using server authentication
(<Link href="/guides/authentication/jwt/jwt-setup">JWT</Link> or
<Link href="/guides/authentication/client-credentials/client-credentials-setup">Client Credentials Grant</Link>).
They represent users, groups, or processes behind the scenes in your
application without requiring a Box account to log in.

Before you can create App Users, your JWT or CCG application must be
<Link href="/guides/authorization/platform-app-approval">authorized</Link> in
the Admin Console, which generates a
<Link href="/guides/getting-started/users#service-account">Service Account</Link>. You
use the Service Account's access token to create App Users through the API.

App Users can only be accessed through the Box APIs and don't have credentials
to log in to `box.com` directly.

## Common App User Patterns

Typically app users are created for a number of different patterns:

* To represent a single application user or group of users without a `box.com` account.
* To represent an application process, such as having the app user monitor all events within an enterprise.
* To provide the application with the ability to completely control the file and folder structure of a user account without the possibility of that content being modified through the `box.com` web app.

## Creating a New App User

To generate a new app user, the minimal information that will be required will
be a name for the app user.

<CodeGroup>
  ```java Java v5 theme={null}
  BoxUser.Info createdUserInfo = BoxUser.createAppUser(api, "A User");
  ```

  ```python Python v4 theme={null}
  new_app_user = client.create_user('App User 123', login=None)
  ```

  ```cs .NET v6 theme={null}
  var userParams = new BoxUserRequest()
  {
      Name = "App User 12",
      ExternalAppUserId = "external-id",
      IsPlatformAccessOnly = true
  };
  BoxUser newUser = await client.UsersManager.CreateEnterpriseUserAsync(userParams);
  ```
</CodeGroup>

To see all available optional parameters that may be set when creating an app
user, see the <Link href="/reference/post-users">create user endpoint</Link>.

<Note>
  Before you can make any changes to the newly created account, you need to
  click the link you receive in the confirmation email.
</Note>

Once the app user is created a user object will be returned. Within the user
object is an ID for the app user, which may be used to make API requests to
modify the user in the future.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Create Managed User
Source: https://developer.box.com/guides/users/create-managed-user



To generate a new managed user, the minimal information that will be required
will be a name and an email address for the managed user.

<Note>
  The email address supplied when creating a managed user must be unique. It
  cannot already be associated with an existing Box user.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/users" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "login": "ceo@example.com",
         "name": "Aaron Levie"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.users.createUser({
    name: userName,
    login: userLogin,
    isPlatformAccessOnly: true,
  } satisfies CreateUserRequestBody);
  ```

  ```python Python v10 theme={null}
  client.users.create_user(user_name, login=user_login, is_platform_access_only=True)
  ```

  ```cs .NET v10 theme={null}
  await client.Users.CreateUserAsync(requestBody: new CreateUserRequestBody(name: userName) { Login = userLogin, IsPlatformAccessOnly = true });
  ```

  ```swift Swift v10 theme={null}
  try await client.users.createUser(requestBody: CreateUserRequestBody(name: userName, login: userLogin, isPlatformAccessOnly: true))
  ```

  ```java Java v10 theme={null}
  client.getUsers().createUser(new CreateUserRequestBody.Builder(userName).login(userLogin).isPlatformAccessOnly(true).build())
  ```

  ```java Java v5 theme={null}
  BoxUser.Info createdUserInfo = BoxUser.createEnterpriseUser(api, "user@example.com", "A User");
  ```

  ```python Python v4 theme={null}
  new_user = client.create_user('Temp User', 'user@example.com')
  ```

  ```cs .NET v6 theme={null}
  var userParams = new BoxUserRequest()
  {
      Name = "Example User",
      Login = "user@example.com"
  };
  BoxUser newUser = await client.UsersManager.CreateEnterpriseUserAsync(userParams);
  ```

  ```javascript Node v4 theme={null}
  client.enterprise.addUser(
  	'eddard@winterfell.example.com',
  	'Ned Stark',
  	{
  		role: client.enterprise.userRoles.COADMIN,
  		address: '555 Box Lane',
  		status: client.enterprise.userStatuses.CANNOT_DELETE_OR_EDIT
  	})
  	.then(user => {
  		/* user -> {
  			type: 'user',
  			id: '44444',
  			name: 'Ned Stark',
  			login: 'eddard@winterfell.example.com',
  			created_at: '2012-11-15T16:34:28-08:00',
  			modified_at: '2012-11-15T16:34:29-08:00',
  			role: 'coadmin',
  			language: 'en',
  			timezone: 'America/Los_Angeles',
  			space_amount: 5368709120,
  			space_used: 0,
  			max_upload_size: 2147483648,
  			status: 'active',
  			job_title: '',
  			phone: '',
  			address: '555 Box Lane',
  			avatar_url: 'https://www.box.com/api/avatar/large/deprecated' }
          */
  	});
  ```
</CodeGroup>

To see all available optional parameters that may be set when creating an app
user, see the <Link href="/reference/post-users">create user endpoint</Link>.

<Note>
  Before you can make any changes to the newly created account, you need to
  click the link you receive in the confirmation email.
</Note>

A user object will be returned from the create user request. Within the user
object is an ID for the managed user, which may be used to make API requests to
modify the user in the future.

Once a new managed user is created the email address used will receive an email
from Box asking them to create a password for the account. The account will be
in a `pending` state until that action has taken place.

<Note>
  For security reasons passwords cannot be supplied when creating a new managed
  user.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete User
Source: https://developer.box.com/guides/users/delete-user



The process for deleting both app and managed users is the same. To delete a
user account, supply the user ID for the account that should be
removed.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/users/12345" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.users.deleteUserById(user.id);
  ```

  ```python Python v10 theme={null}
  client.users.delete_user_by_id(user.id)
  ```

  ```cs .NET v10 theme={null}
  await client.Users.DeleteUserByIdAsync(userId: user.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.users.deleteUserById(userId: user.id)
  ```

  ```java Java v10 theme={null}
  client.getUsers().deleteUserById(user.getId())
  ```

  ```java Java v5 theme={null}
  BoxUser user = new BoxUser(api, "0");
  user.delete(false, false);
  ```

  ```python Python v4 theme={null}
  user_id = '33333'
  client.user(user_id).delete(force=True)
  ```

  ```cs .NET v6 theme={null}
  await client.UsersManager.DeleteEnterpriseUserAsync("44444", notify: false, force: true);
  ```

  ```javascript Node v4 theme={null}
  // Delete the user even if they still have files in their account
  client.users.delete('123', {force: true})
      .then(() => {
          // deletion succeeded — no value returned
      });
  ```
</CodeGroup>

There are also two optional parameters that may be set when deleting a user
account:

* force: Whether the user should be deleted even if the account still has content in it.
* notify: Whether the user will receive a notification that the account was deleted.

<Note>
  The delete user request will fail if the user account still has content in
  it. To resolve this, either
  <Link href="/guides/users/deprovision/transfer-folders">transfer all files or folders</Link>
  to another account or use the optional `force` parameter.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Deprovision Users
Source: https://developer.box.com/guides/users/deprovision/index



Part of regular Box enterprise maintenance is removing accounts for users that
are no longer active in your enterprise. When removing a user from your
enterprise, you'll need to move all content owned by the user into another
account before deleting the user account.

<Note>
  The delete user request will fail if the user account still has content in
  it. An optional `force` parameter is available in the API call, which will
  force delete the user account along with all content in the account.
</Note>

The standard best practice when decommissioning a user account is to move all
content owned by that user into another admin level account or into the
application service account. Once moved, you can transfer ownership of the
content to a different user or collaborate a different user on the content if
needed.

## Deprovisioning Example

Use the following code samples to transfer a user's content and then delete the
user. When content is being transferred, a new folder is created in the
destination user's root folder following this pattern:
`employee_email@email.com - employee_name's Files and Folders`

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    'use strict'
    const box = require('box-node-sdk');
    const fs = require('fs');

    let configFile = fs.readFileSync('config.json');
    configFile = JSON.parse(configFile);

    let session = box.getPreconfiguredInstance(configFile);
    let serviceAccountClient = session.getAppAuthClient('enterprise');

    const transferUserID = '3278487052';
    (async () => {
        let serviceAccount = await serviceAccountClient.users.get('me');
        let transferredFolder = await serviceAccountClient.enterprise.transferUserContent(transferUserID,serviceAccount.id);
        console.log(transferredFolder);
        await serviceAccountClient.users.delete(transferUserID, null);
        console.log('Completed');
    })();
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    Path configPath = Paths.get("config.json");
    try (BufferedReader reader = Files.newBufferedReader(configPath,Charset.forName("UTF-8"))){
        String transferUserId = "3277722534";

        BoxConfig boxConfig = BoxConfig.readFrom(reader);
        BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection
          .getAppEnterpriseConnection(boxConfig);

        BoxUser destinationUser = new BoxUser(serviceAccountClient,
            BoxUser.getCurrentUser(serviceAccountClient).getID());
        try {
            destinationUser.moveFolderToUser(transferUserId);
        } catch (BoxAPIException e) {}

        BoxUser removeUser = new BoxUser(serviceAccountClient, transferUserId);
        removeUser.delete(false, false);
    }
    ```
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    using(FileStream fs = new FileStream("./config.json", FileMode.Open)) {
        var config = BoxConfig.CreateFromJsonFile(fs);
        var session = new BoxJWTAuth(config);
        var serviceAccountClient = session.AdminClient(session.AdminToken());

        var transferUserId = "3276247601";

        var serviceAccount = await serviceAccountClient.UsersManager.GetCurrentUserInformationAsync();
        var moveAction = await serviceAccountClient.UsersManager.MoveUserFolderAsync(transferUserId,serviceAccount.Id);

        System.Console.WriteLine(moveAction.Name);
        await serviceAccountClient.UsersManager.DeleteEnterpriseUserAsync(transferUserId,false,false);
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    box users:transfer-content $transfer_from_user_id $transfer_to_user_id
    box users:delete $transfer_from_user_id --yes
    ```
  </Tab>
</Tabs>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Transfer Files & Folders
Source: https://developer.box.com/guides/users/deprovision/transfer-folders



As part of user account deprovisioning, a common requirement is to transfer all
files and folders that are stored within the user account to another user
account or into a location for long term storage, such as into the service
account.

There are two general methods that are employed to accomplish this within Box:

* Using the direct <Link href="/reference/put-users-id-folders-0">transfer owned folders</Link> API, which will move all content from one user directly to another.
* Using the collaboration transfer method to change ownership of one file or folder at a time from one user to another.

<Note>
  Files owned by a user will be inaccessible while they are being transferred.
  This also means that any shared content owned by the user may be inaccessible
  during the move.

  Depending on the volume of content, this operation may take a significant
  amount of time.
</Note>

## Transfer Owned Folders API Method

The <Link href="/reference/put-users-id-folders-0">transfer owned folders endpoint</Link> is
designed to move the entirety of content owned by one user over to another user.

<Note>
  The transfer owned folders API is performed as a synchronous process, which
  might lead to a slow response when the source user has a large number of
  items in all of its folders.
</Note>

To call the transfer endpoint, you will supply the user ID to transfer from and
the user ID to transfer to.

<CodeGroup>
  ```typescript Node/TypeScript v10 theme={null}
  await client.transfer.transferOwnedFolder(
    sourceUser.id,
    {
      ownedBy: {
        id: targetUser.id,
      } satisfies TransferOwnedFolderRequestBodyOwnedByField,
    } satisfies TransferOwnedFolderRequestBody,
    {
      queryParams: { notify: false } satisfies TransferOwnedFolderQueryParams,
    } satisfies TransferOwnedFolderOptionalsInput,
  );
  ```

  ```python Python v10 theme={null}
  client.transfer.transfer_owned_folder(
      source_user.id, TransferOwnedFolderOwnedBy(id=target_user.id), notify=False
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Transfer.TransferOwnedFolderAsync(userId: sourceUser.Id, requestBody: new TransferOwnedFolderRequestBody(ownedBy: new TransferOwnedFolderRequestBodyOwnedByField(id: targetUser.Id)), queryParams: new TransferOwnedFolderQueryParams() { Notify = false });
  ```

  ```swift Swift v10 theme={null}
  try await client.transfer.transferOwnedFolder(userId: sourceUser.id, requestBody: TransferOwnedFolderRequestBody(ownedBy: TransferOwnedFolderRequestBodyOwnedByField(id: targetUser.id)), queryParams: TransferOwnedFolderQueryParams(notify: false))
  ```

  ```java Java v10 theme={null}
  client.getTransfer().transferOwnedFolder(sourceUser.getId(), new TransferOwnedFolderRequestBody(new TransferOwnedFolderRequestBodyOwnedByField(targetUser.getId())), new TransferOwnedFolderQueryParams.Builder().notify(false).build())
  ```

  ```java Java v5 theme={null}
  String sourceUserID = "11111";
  String destinationUserID = "22222";
  BoxUser sourceUser = new BoxUser(api, sourceUserID);
  BoxFolder.Info transferredFolderInfo = sourceUser.transferContent(destinationUserID);
  ```

  ```python Python v4 theme={null}
  source_user_id = '33333'
  destination_user_id = '44444'

  user = client.user(source_user_id)
  destination_user = client.user(destination_user_id)

  folder = user.transfer_content(destination_user)
  print(f'Created new folder "{folder.name}" in the account of user {destination_user.id}')
  ```

  ```cs .NET v6 theme={null}
  var sourceUserId = "33333";
  var destinationUserId = "44444";
  BoxFolder movedFolder = await client.MoveUserFolderAsync(sourceUserId, destinationUserId);
  ```

  ```javascript Node v4 theme={null}
  var sourceUserID = '33333';
  var destinationUserID = '44444';
  client.enterprise.transferUserContent(sourceUserID, destinationUserID)
  	.then(movedFolder => {
  		/* movedFolder -> {
  			type: 'folder',
  			id: '123456789',
  			sequence_id: '1',
  			etag: '1',
  			name: 'Other User's Files and Folders',
  			created_at: '2018-04-23T11:00:07-07:00',
  			modified_at: '2018-04-23T11:00:07-07:00',
  			description: 'This folder contains files previously owned by Other User, and were transferred to you by your enterprise administrator. If you have any questions, please contact Enterprise Admin (admin@example.com).',
  			size: 0,
  			path_collection: 
  			{ total_count: 1,
  				entries: 
  				[ { type: 'folder',
  					id: '0',
  					sequence_id: null,
  					etag: null,
  					name: 'All Files' } ] },
  			created_by: 
  			{ type: 'user',
  				id: '99999',
  				name: 'Enterprise Admin',
  				login: 'admin@example.com' },
  			modified_by: 
  			{ type: 'user',
  				id: '99999',
  				name: 'Enterprise Admin',
  				login: 'admin@example.com' },
  			trashed_at: null,
  			purged_at: null,
  			content_created_at: '2018-04-23T11:00:07-07:00',
  			content_modified_at: '2018-04-23T11:00:07-07:00',
  			owned_by: 
  			{ type: 'user',
  				id: '33333',
  				name: 'Example User',
  				login: 'user@example.com' },
  			shared_link: null,
  			folder_upload_email: null,
  			parent: 
  			{ type: 'folder',
  				id: '0',
  				sequence_id: null,
  				etag: null,
  				name: 'All Files' },
  			item_status: 'active' }
  		*/
  	});
  ```
</CodeGroup>

## Collaboration Transfer Method

The collaboration transfer method is a process that uses the
<Link href="/reference/post-collaborations">collaboration endpoint</Link> to change the
ownership of a single file or folder from one user to another instantaneously.

<Note>
  This method will perform an instantaneous transfer of ownership of a single
  file or folder, but **cannot** be used to transfer the root (all files and
  folders) from one user to another.
</Note>

The general process, between `transfer_from_user` to `transfer_to_user`, will
follow these steps:

### Add Transfer To User as Co-Owner

The first step is to add the `transfer_to_user` account as a collaborator with
`co-owner` access on the file or folder that should be transferred.

Making the call as the `transfer_from_user` account, add the `transfer_to_user`
as a co-owner using the
<Link href="/reference/post-collaborations">add collaboration endpoint</Link>.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/collaborations" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "item": {
           "type": "file",
           "id": "11446498"
         },
         "accessible_by": {
           "type": "user",
           "login": "user@example.com"
         },
         "role": "editor"
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.userCollaborations.createCollaboration({
    item: {
      type: 'folder' as CreateCollaborationRequestBodyItemTypeField,
      id: folder.id,
    } satisfies CreateCollaborationRequestBodyItemField,
    accessibleBy: {
      type: 'user' as CreateCollaborationRequestBodyAccessibleByTypeField,
      id: user.id,
    } satisfies CreateCollaborationRequestBodyAccessibleByField,
    role: 'editor' as CreateCollaborationRequestBodyRoleField,
  } satisfies CreateCollaborationRequestBody);
  ```

  ```python Python v10 theme={null}
  client.user_collaborations.create_collaboration(
      CreateCollaborationItem(type=CreateCollaborationItemTypeField.FOLDER, id=folder.id),
      CreateCollaborationAccessibleBy(
          type=CreateCollaborationAccessibleByTypeField.USER, id=user.id
      ),
      CreateCollaborationRole.EDITOR,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.UserCollaborations.CreateCollaborationAsync(requestBody: new CreateCollaborationRequestBody(item: new CreateCollaborationRequestBodyItemField() { Type = CreateCollaborationRequestBodyItemTypeField.Folder, Id = folder.Id }, accessibleBy: new CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.User) { Id = user.Id }, role: CreateCollaborationRequestBodyRoleField.Editor));
  ```

  ```swift Swift v10 theme={null}
  try await client.userCollaborations.createCollaboration(requestBody: CreateCollaborationRequestBody(item: CreateCollaborationRequestBodyItemField(type: CreateCollaborationRequestBodyItemTypeField.folder, id: folder.id), accessibleBy: CreateCollaborationRequestBodyAccessibleByField(type: CreateCollaborationRequestBodyAccessibleByTypeField.user, id: user.id), role: CreateCollaborationRequestBodyRoleField.editor))
  ```

  ```java Java v10 theme={null}
  client.getUserCollaborations().createCollaboration(new CreateCollaborationRequestBody(new CreateCollaborationRequestBodyItemField.Builder().type(CreateCollaborationRequestBodyItemTypeField.FOLDER).id(folder.getId()).build(), new CreateCollaborationRequestBodyAccessibleByField.Builder(CreateCollaborationRequestBodyAccessibleByTypeField.USER).id(user.getId()).build(), CreateCollaborationRequestBodyRoleField.EDITOR))
  ```

  ```java Java v5 theme={null}
  BoxCollaborator user = new BoxUser(api, "user-id")
  BoxFolder folder = new BoxFolder(api, "folder-id");
  folder.collaborate(user, BoxCollaboration.Role.EDITOR);
  ```

  ```python Python v4 theme={null}
  from boxsdk.object.collaboration import CollaborationRole

  user = client.user(user_id='11111')
  collaboration = client.folder(folder_id='22222').collaborate(user, CollaborationRole.VIEWER)

  collaborator = collaboration.accessible_by
  item = collaboration.item
  has_accepted = 'has' if collaboration.status == 'accepted' else 'has not'
  print(f'{collaborator.name} {has_accepted} accepted the collaboration to folder "{item.name}"')
  ```

  ```cs .NET v6 theme={null}
  // collaborate folder 11111 with user 22222
  BoxCollaborationRequest requestParams = new BoxCollaborationRequest()
  {
      Item = new BoxRequestEntity()
      {
          Type = BoxType.folder,
          Id = "11111"
      },
      Role = "editor",
      AccessibleBy = new BoxCollaborationUserRequest()
      {
          Type = BoxType.user,
          Id = "22222"
      }
  };
  BoxCollaboration collab = await client.CollaborationsManager.AddCollaborationAsync(requestParams);
  ```

  ```javascript Node v4 theme={null}
  // Invite user 123456 to collaborate on folder 987654
  client.collaborations.createWithUserID('123456', '987654', client.collaborationRoles.EDITOR)
  	.then(collaboration => {
  		/* collaboration -> {
  			type: 'collaboration',
  			id: '11111',
  			created_by: 
  			{ type: 'user',
  				id: '22222',
  				name: 'Inviting User',
  				login: 'inviter@example.com' },
  			created_at: '2016-11-16T21:33:31-08:00',
  			modified_at: '2016-11-16T21:33:31-08:00',
  			expires_at: null,
  			status: 'accepted',
  			accessible_by: 
  			{ type: 'user',
  				id: '123456',
  				name: 'Collaborator User',
  				login: 'collaborator@example.com' },
  			role: 'editor',
  			acknowledged_at: '2016-11-16T21:33:31-08:00',
  			item: 
  			{ type: 'folder',
  				id: '987654',
  				sequence_id: '0',
  				etag: '0',
  				name: 'Collaborated Folder' } }
  		*/
  	});
  ```
</CodeGroup>

### Fetch Collaboration ID as Transfer To User

The next step is to make a request to get the collaboration information, making
the request as the `transfer_to_user` account. The collaboration object
returned will include a collaboration ID, which is used for the last step.

Making the call as the `transfer_to_user` account, get the collaboration on the
file or folder ID being transferred, using the
<Link href="/reference/get-collaborations-id">get collaboration endpoint</Link>. Capture the
collaboration ID.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/collaborations/1234" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.userCollaborations.getCollaborationById(collaborationId);
  ```

  ```python Python v10 theme={null}
  client.user_collaborations.get_collaboration_by_id(collaboration_id)
  ```

  ```cs .NET v10 theme={null}
  await client.UserCollaborations.GetCollaborationByIdAsync(collaborationId: collaborationId);
  ```

  ```swift Swift v10 theme={null}
  try await client.userCollaborations.getCollaborationById(collaborationId: collaborationId)
  ```

  ```java Java v10 theme={null}
  client.getUserCollaborations().getCollaborationById(collaborationId)
  ```

  ```cs .NET v6 theme={null}
  await client.UserCollaborations.GetCollaborationByIdAsync(collaborationId: collaborationId);
  ```

  ```javascript Node v4 theme={null}
  await client.userCollaborations.getCollaborationById(collaborationId);
  ```
</CodeGroup>

### Remove Transfer From User as Owner

The final step is to remove the `transfer_from_user` account as an owner of the
file or folder, which is accomplished using the
<Link href="/reference/delete-collaborations-id">delete collaboration endpoint</Link>.

Making the call as the `transfer_to_user` account, remove the `transfer_from_user`
as a collaborator on the file or folder.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/collaborations/1234" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.userCollaborations.deleteCollaborationById(collaborationId);
  ```

  ```python Python v10 theme={null}
  client.user_collaborations.delete_collaboration_by_id(collaboration_id)
  ```

  ```cs .NET v10 theme={null}
  await client.UserCollaborations.DeleteCollaborationByIdAsync(collaborationId: collaborationId);
  ```

  ```swift Swift v10 theme={null}
  try await client.userCollaborations.deleteCollaborationById(collaborationId: collaborationId)
  ```

  ```java Java v10 theme={null}
  client.getUserCollaborations().deleteCollaborationById(collaborationId)
  ```

  ```cs .NET v6 theme={null}
  await client.UserCollaborations.DeleteCollaborationByIdAsync(collaborationId: collaborationId);
  ```

  ```javascript Node v4 theme={null}
  await client.userCollaborations.getCollaborationById(collaborationId);
  ```
</CodeGroup>

The file or folder is now owned by the `transfer_to_user` account, and the
`transfer_from_user` account no longer has access.

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Users overview
Source: https://developer.box.com/guides/users/index



The Box API supports a variety of users, ranging from real employees logging in
with their Managed User account, to applications using App Users to drive
powerful automation workflows.

<Card href={localizeLink("/guides/getting-started/users/")} title="Learn more about user types" />

## (De-)Provision Users

Managing the onboarding and offboarding of employees, customers, and users is a
common requirement in the lifespan of a Box application.

During account provisioning the main tasks that will be needed will be:

* How to create new app and managed user accounts to represent the users.
* How to instantiate the new user account with common or repeatable folder and file architectures.

During account deprovisioning the main tasks that will be needed will be:

* How to transfer files and folders from one account to another for offboarding.
* How to delete user accounts.


# Create Architecture Skeleton
Source: https://developer.box.com/guides/users/provision/architecture



Our first requirement is to copy general files and folders into each individual
user's root folder on account creation. This problem has been solved within
standard Linux distributions through a directory called `/etc/skel`,
which we'll emulate with a Box specific solution here. When adding a new user in
Linux, the files and folders within `/etc/skel` are copied to the new user's
home directory.

When creating a
<Link href="/guides/authentication/jwt/jwt-setup">JWT-based Box application</Link>, a
<Link href="/guides/getting-started/users#service-account">Service Account</Link> is created
within the Box Enterprise. A Service Account is similar in functionality to a
co-admin within a Box Enterprise, and most useful to this use case, can own,
copy, and collaborate other users on files and folders. More importantly, you
don't have to use a Service Account strictly for developing platform applications
for users, and instead, can use a Service Account in more of an automation
capacity.

<Info>
  **Platform app requirements**

  When creating your JWT-based custom Box application for this recipe, you'll
  need to enable the following scopes: **Manage users**, **Manage groups**,
  **Perform Actions as Users**, and **Generate User Access Tokens**.

  See <Link href="/guides/authentication/jwt/jwt-setup">JWT Application Setup</Link> for
  more information on creating a JWT-based Box application and the scopes in a
  Box application.
</Info>

We'll start by creating the `etc` and `skel` folders and granting ownership of
the folders to the Service Account.

<Tabs>
  <Tab title="etc_skel.json">
    ```json theme={null}
    {
      "name": "etc",
      "parent": {
        "id": "0"
      },
      "children": [
        {
          "name": "skel",
          "children": []
        }
      ]
    }
    ```
  </Tab>

  <Tab title="skel_sub_directories.json">
    ```json theme={null}
    [
      {
        "name": "Market Research",
        "parent": {
          "id": "44884797174"
        },
        "children": [
          {
            "name": "Statistics",
            "children": [
              {
                "name": "Computed",
                "children": []
              }
            ]
          }
        ]
      },
      {
        "name": "Sales Plays",
        "parent": {
          "id": "44884797174"
        },
        "children": [
          {
            "name": "Big Pharma",
            "children": []
          }
        ]
      }
    ]
    ```
  </Tab>
</Tabs>

The code here can optionally be reused to build any folder structure formatted
as the JSON objects above demonstrate.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    "use strict";
    const fs = require("fs");
    const box = require("box-node-sdk");

    class BoxFolderTreeCreator {
        constructor(boxClient, options) {
            options = options || {};
            if (options.boxClient) {
                throw new Error("Must include a boxClient field.");
            }

            options.boxFolderTreeName = options.boxFolderTreeName || "tree.json";

            this.boxClient = boxClient;
            this.boxFolderTree = JSON.parse(fs.readFileSync(options.boxFolderTreeName));
            this.createdBoxFolders = [];
        }

        async createFolderTree(branch = null, parentFolderId = "0") {
            this.createdBoxFolders = [];
            if (Array.isArray(this.boxFolderTree)) {
                let folderTasks = [];
                this.boxFolderTree.forEach(folder => {
                    folderTasks.push(this._createFolder(folder, ""));
                });
                await Promise.all(folderTasks);
                return this.createdBoxFolders;
            } else if (typeof this.boxFolderTree === "object") {
                console.log("Is object");
                await this._createFolders(this.boxFolderTree, "");
                return this.createdBoxFolders;
            } else {
                throw new Error("Incorrectly formatted JSON folder tree.");
            }
        }

        async _createFolders(branch, parentFolderId = "0") {
            if (branch.parent != null && branch.parent.id != null) {
                parentFolderId = branch.parent.id;
            }
            let folder;
            try {
                folder = await this.boxClient.folders.create(parentFolderId, branch.name);
            } catch (e) {
                let existingFolderId = BoxFolderTreeCreator.handleFolderConflictError(e);
                folder = await this.boxClient.folders.get(existingFolderId);
            }
            this.createdBoxFolders.push(folder);
            if (branch.children.length <= 0) {
                console.log("No more folders to create...");
                return;
            } else {
                let createFolderTasks = [];
                branch.children.forEach(child => {
                    console.log("Creating folder...");
                    console.log(child.name);
                    createFolderTasks.push(this._createFolders(child, folder.id));
                });
                return await Promise.all(createFolderTasks);
            }
        }

        static handleFolderConflictError(e) {
            if (e && e.response && e.response.body) {
                let errorBody = e.response.body;
                if (errorBody.status === 409) {
                    if (
                        errorBody.context_info &&
                        errorBody.context_info.conflicts &&
                        errorBody.context_info.conflicts.length > 0
                    ) {
                        let conflict = errorBody.context_info.conflicts[0];
                        if (conflict && conflict.id) {
                            return conflict.id;
                        }
                    }
                }
            }
        }
    }

    let configFile = fs.readFileSync("config.json");
    configFile = JSON.parse(configFile);

    let session = box.getPreconfiguredInstance(configFile);
    let serviceAccountClient = session.getAppAuthClient("enterprise");

    let treeCreator = new BoxFolderTreeCreator(serviceAccountClient);

    (async () => {
        let createdFolders = await treeCreator.createFolderTree();
        console.log(createdFolders);
    })();
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    package com.box;

    import java.io.BufferedReader;
    import java.io.IOException;
    import java.nio.charset.Charset;
    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.nio.file.Paths;
    import java.util.ArrayList;
    import java.util.regex.Matcher;
    import java.util.regex.Pattern;

    import com.box.sdk.BoxAPIException;
    import com.box.sdk.BoxConfig;
    import com.box.sdk.BoxDeveloperEditionAPIConnection;
    import com.box.sdk.BoxFolder;
    import com.eclipsesource.json.JsonObject;
    import com.eclipsesource.json.JsonValue;

    public class BoxFolderTreeCreator {
        private BoxDeveloperEditionAPIConnection _boxClient;
        private JsonValue _boxFolderTree;
        private ArrayList<BoxFolder.Info > _createdFolders;

        public BoxFolderTreeCreator(BoxDeveloperEditionAPIConnection
            boxClient) throws IOException {
            this(boxClient, "tree.json");
        }

        public BoxFolderTreeCreator(BoxDeveloperEditionAPIConnection boxClient,
            String folderTreeFileName)
        throws IOException {
            this._boxClient = boxClient;
            try (BufferedReader tree =
                Files.newBufferedReader(Paths.get(folderTreeFileName))) {
                this._boxFolderTree = JsonValue.readFrom(tree);
            }
            this._createdFolders = new ArrayList<>();
        }

        public ArrayList<BoxFolder.Info > createFolderTree() {
            if (this._boxFolderTree.isArray()) {
                for (JsonValue folder: this._boxFolderTree.asArray()) {
                    System.out.println("Processing this folder: " + folder);
                    _createFolders(folder.asObject(), null);
                }
                return this._createdFolders;
            } else {
                _createFolders(this._boxFolderTree.asObject(), null);
                return this._createdFolders;
            }
        }

        private void _createFolders(JsonObject branch, String parentFolderID) {
            if (parentFolderID == null && branch.get("parent") != null &&
                branch.get("parent").asObject().get("id") != null) {
                System.out.println("Looking for parent folder id...");
                System.out.println(branch.get("parent").asObject().get("id").asString());
                parentFolderID = branch.get("parent").asObject().get("id").asString();
            }
            System.out.println("Folder name:");
            System.out.println(branch.get("name"));
            System.out.println("Parent Folder ID:");
            System.out.println(parentFolderID);
            BoxFolder.Info createdFolder;
            try {
                BoxFolder parent = new BoxFolder(this._boxClient, parentFolderID);
                createdFolder = parent.createFolder(branch.get("name").asString());
            } catch (BoxAPIException e) {
                if (e.getResponseCode() == 409) {
                    // Use the ID returned from the conflict error to continue
                    String conflictId = getIdFromConflict(e.getResponse());
                    createdFolder = new BoxFolder(this._boxClient, conflictId).getInfo();
                } else {
                    throw e;
                }
            }

            this._createdFolders.add(createdFolder);

            if (!branch.get("children").asArray().isEmpty()) {
                for (JsonValue child: branch.get("children").asArray()) {
                    _createFolders(child.asObject(), createdFolder.getID());
                }
            } else {
                return;
            }
        }

        private static String getIdFromConflict(String message) {
            String id = "";
            Pattern p = Pattern.compile("\"id\":\"[0-9]+\"");
            Pattern p2 = Pattern.compile("[0-9]+");
            Matcher m = p.matcher(message);
            if (m.find()) {
                String sub = m.group();
                Matcher m2 = p2.matcher(sub);
                if (m2.find()) {
                    id = m2.group();
                }
            }
            return id;
        }

        public static void main(String[] args) throws Exception {
            Path configPath = Paths.get("config.json");
            try (BufferedReader reader =
                Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) {
                BoxConfig boxConfig = BoxConfig.readFrom(reader);
                BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection
                    .getAppEnterpriseConnection(boxConfig);

                BoxFolderTreeCreator treeBuilder = new
                    BoxFolderTreeCreator(serviceAccountClient, "etc_skel.json");
                ArrayList<BoxFolder.Info > folders = treeBuilder.createFolderTree();
                for (BoxFolder.Info folder: folders) {
                    System.out.println(folder.getID());
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    using System;
    using System.Collections;
    using System.Collections.Generic;
    using System.IO;
    using System.Linq;
    using System.Threading.Tasks;
    using Box.V2;
    using Box.V2.Config;
    using Box.V2.Exceptions;
    using Box.V2.JWTAuth;
    using Box.V2.Models;
    using Newtonsoft.Json.Linq;

    namespace BoxPlayground {
        public class Program {
            static void Main(string[] args) {
                ExecuteMainAsync().Wait();
            }

            private static async Task ExecuteMainAsync() {
                using(FileStream fs = new FileStream("./config.json",
                    FileMode.Open)) {
                    var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs));
                    var client = session.AdminClient(session.AdminToken());
                    var treeCreator = new BoxFolderTreeCreator(client, "etc_skel.json");
                    var createdFolders = await treeCreator.CreateFolderTree();
                    foreach(var folder in createdFolders) {
                        System.Console.WriteLine(folder.Name);
                        System.Console.WriteLine(folder.Id);
                    }

                }
            }

            public class BoxFolderTreeCreator {
                public BoxClient BoxClient {
                    get;
                    set;
                }
                public JToken BoxFolderTree {
                    get;
                    set;
                }
                public List < BoxFolder > CreatedBoxFolders {
                    get;
                    set;
                }

                public BoxFolderTreeCreator(BoxClient boxClient,
                    string boxFolderTreeFileName = "tree.json") {
                    this.BoxClient = boxClient;
                    this.BoxFolderTree = JToken.Parse(File.ReadAllText(boxFolderTreeFileName));
                    this.CreatedBoxFolders = new List < BoxFolder > ();
                }
                public async Task < List < BoxFolder >>
                    CreateFolderTree(dynamic branch = null,
                    string parentFolderId = "0") {
                    this.CreatedBoxFolders = new List < BoxFolder > ();

                    if (this.BoxFolderTree is JArray) {
                        var folderTasks = new List < Task > ();
                        foreach(JObject folder in this.BoxFolderTree) {
                            folderTasks.Add(_createFolder(folder, String.Empty));
                        }
                        await Task.WhenAll(folderTasks);
                        return this.CreatedBoxFolders;
                    }
                    else if (this.BoxFolderTree is JObject) {
                        System.Console.WriteLine("Is object");
                        await _createFolder(this.BoxFolderTree as JObject, String.Empty);
                        return this.CreatedBoxFolders;
                    }
                    else {
                        throw new Exception("Incorrectly formatted JSON folder tree.");
                    }

                }

                private async Task _createFolder(dynamic branch,
                    string parentFolderId = "0") {

                    if (branch.parent != null && branch.parent.id != null) {
                        parentFolderId = branch.parent.id;
                    }

                    BoxFolder createdFolder;
                    try {
                        createdFolder = await this.BoxClient.FoldersManager.CreateAsync(
                            new BoxFolderRequest {
                                Parent = new BoxRequestEntity {
                                    Id = parentFolderId
                                },
                                Name = branch.name
                        });
                    }
                    catch(BoxConflictException < BoxFolder > e) {
                        createdFolder = await this.BoxClient.FoldersManager.GetInformationAsync(e.ConflictingItems.FirstOrDefault().Id);
                    }

                    this.CreatedBoxFolders.Add(createdFolder);

                    if (branch.children.Count <= 0) {
                        System.Console.WriteLine("No more folders to create...");
                        return;
                    }
                    else {
                        var createFolderTasks = new List < Task > ();
                        foreach(var child in branch.children) {
                            System.Console.WriteLine("Creating folder...");
                            System.Console.WriteLine(child.name);
                            createFolderTasks.Add(_createFolder(child as JObject,
                                createdFolder.Id));
                        }
                        await Task.WhenAll(createFolderTasks);
                    }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

<RelatedLinks title="RELATED GUIDES" />


# Provision Users
Source: https://developer.box.com/guides/users/provision/index



When setting up a brand new Box user account, a common need is to have that new
account be populated with standard folders, collaborations, and group
associations.

Typically there are some common questions that may be asked about the user
account to determine when standard setup may be needed for the account:

* Will the user need access to standard company files or folders immediately?
* Are collaborations associated individually or through groups? If through a group association, are there any standard groups that the user should be added to?
* Should the user be assigned any tasks to complete?
* Would any instructional comments on any files be helpful?

<Danger>
  **New User Password Resets and Email Confirmation**

  You may experience some errors when creating users and immediately trying to
  take actions with that user through the API. For example, a common error to
  receive is `user_email_confirmation_required` or `password_reset_required`.
  These kinds of errors may block some actions within the API, but you can
  still add the user as a collaborator on folders, add the user to groups, etc.
</Danger>

## Sample Overview

In this scenario we'll focus on provisioning a new
<Link href="/guides/getting-started/users#managed-users">Box Managed User</Link>, as there
are very different considerations when provisioning Box App User accounts.

We'll start with solving the most repeatable aspects of
provisioning a user's account, creating a general folder and file structure
that everyone will have on first login, using groups to control access to
shared files and folders for users.

To create the managed user account itself, see
<Link href="/guides/users/create-managed-user">create managed user</Link>.

## Guide steps

This guide walks through the provisioning process in three steps:

<CardGroup>
  <Card title="Create architecture skeleton" href="/guides/users/provision/architecture">
    Create an `etc/skel` folder structure owned by your application's service
    account to hold the default files and folders for every new user.
  </Card>

  <Card title="Populate content" href="/guides/users/provision/populate-content">
    Copy the skeleton content into a new user's root folder when the account is
    created.
  </Card>

  <Card title="Setup shared folders" href="/guides/users/provision/shared-folders">
    Create shared folders in the service account and use groups to control
    each user's level of access.
  </Card>
</CardGroup>


# Populate Content
Source: https://developer.box.com/guides/users/provision/populate-content



Once the architecture files have been defined through the `etc/skel`
structure in your service account, you can now use the following script to copy
anything under the `skel` directly to the new user's root directory.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    'use strict'
    const box = require('box-node-sdk');
    const fs = require('fs');
    const skelFolderId = "45117847998";
    const userID = "275111793";

    let configFile = fs.readFileSync('config.json');
    configFile = JSON.parse(configFile);

    let session = box.getPreconfiguredInstance(configFile);
    let serviceAccountClient = session.getAppAuthClient("enterprise");

    (async () => {
        // The userID can be obtained when creating the user via the
        // API or by using the search users feature.
        // The skel folder ID shouldn't ever change unless it's deleted and recreated.
        await copySkelDirectoryForUser(userID, skelFolderId, serviceAccountClient);
    })();

    async function copySkelDirectoryForUser(userID, skelFolderId, boxClient) {
        // Enable iterators in case there are more than the
        // default limit of items under the skel directory.
        boxClient._useIterators = true;

        // You collaborate the user temporarily on the skel directory
        // to copy all items into that user's root folder.
        let collabSkelFolder;
        try {
            collabSkelFolder = await boxClient.collaborations.createWithUserID(userID,
                skelFolderId, boxClient.collaborationRoles.EDITOR);
        } catch (e) {
            // Handle that the collaboration on the skel folder could already exist.
            if (e.response.body.code === 'user_already_collaborator') {
                let collaborationsIterator = await boxClient.folders.getCollaborations(skelFolderId);
                let collaborations = await autoPage(collaborationsIterator);
                let results = collaborations.filter((collaboration) => {
                    return collaboration.accessible_by.id === userID;
                });
                console.log(results);
                if (results.length > 0) {
                    collabSkelFolder = results[0];
                } else {
                    throw new Error("Couldn't create new collaboration
                        or located existing collaboration.");
                }
            } else {
                throw e;
            }
        }
        console.log(collabSkelFolder);

        // Switching context to make calls on behalf of the user.
        // To access this user's root folder, the boxClient needs
        // to be scoped to make API calls as the user.
        boxClient.asUser(userID);

        // Iterate over all the items under the skel directory.
        let skelFolderItemsIterator = await boxClient.folders.getItems(skelFolderId);
        let skelFolderCollection = await autoPage(skelFolderItemsIterator);
        console.log(skelFolderCollection);

        // Now, as the user, copy the folders and files into
        // the user's root folder -- folder ID '0'.
        let copyTasks = [];
        skelFolderCollection.forEach((item) => {
            if (item.type === 'folder') {
                copyTasks.push(boxClient.folders.copy(item.id, '0')
                    .catch((e) => {
                        let itemId = handleConflictError(e);
                        if (itemId) {
                            console.log(itemId);
                            return boxClient.folders.get(itemId);
                        } else {
                            throw e;
                        }
                    }));
            } else if (item.type === 'file') {
                copyTasks.push(boxClient.files.copy(item.id, '0')
                    .catch((e) => {
                        let itemId = handleConflictError(e);
                        if (itemId) {
                            console.log(itemId);
                            return boxClient.files.get(itemId);
                        } else {
                            throw e;
                        }
                    }));
            } else {
                console.log("Unable to resolve item type to known types...");
            }
        });

        let copiedItems = await Promise.all(copyTasks);
        console.log(copiedItems);

        // Switching the boxClient context back to that of the service account.
        boxClient.asSelf();

        /*
            Since the service account owns the skel directory,
            boxClient needs to make API calls as the service account
            to remove the temporary collaboration on the skel directory.
        */
        try {
            await boxClient.collaborations.delete(collabSkelFolder.id);
            console.log("Removed collaboration on skel...");
        } catch (e) {
            console.log("Couldn't remove skel collaboration...");
            console.log(e.respose.body);
        }

        function handleConflictError(e) {
            if (e && e.response && e.response.body) {
                let errorBody = e.response.body;
                if (errorBody.status === 409) {
                    if (errorBody.context_info
                        && errorBody.context_info.conflicts
                        && errorBody.context_info.conflicts) {
                        let conflict = errorBody.context_info.conflicts;
                        if (conflict && conflict.id) {
                            return conflict.id;
                        }
                    }
                }
            }
        }

        function autoPage(iterator, collection = []) {
            let moveToNextItem = async () => {
                let item = await iterator.next();
                if (item.value) {
                    collection.push(item.value);
                }

                if (item.done !== true) {
                    return moveToNextItem();
                } else {
                    return collection;
                }
            }
            return moveToNextItem();
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    package com.box;

    import java.io.BufferedReader;
    import java.nio.charset.Charset;
    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.nio.file.Paths;
    import java.util.ArrayList;
    import java.util.Collection;
    import java.util.Optional;
    import java.util.regex.Matcher;
    import java.util.regex.Pattern;
    import com.box.sdk.BoxAPIException;
    import com.box.sdk.BoxCollaboration;
    import com.box.sdk.BoxConfig;
    import com.box.sdk.BoxDeveloperEditionAPIConnection;
    import com.box.sdk.BoxFile;
    import com.box.sdk.BoxFolder;
    import com.box.sdk.BoxItem;
    import com.box.sdk.BoxUser;
    import com.eclipsesource.json.JsonObject;

    public class BoxPlayground {

        public static void main(String[] args) throws Exception {
            Path configPath = Paths.get("config.json");
            try (BufferedReader reader = Files.newBufferedReader(configPath,
                Charset.forName("UTF-8"))) {
                String skelFolderId = "45117847998";
                String userId = "275111793";

                BoxConfig boxConfig = BoxConfig.readFrom(reader);
                BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection
                    .getAppEnterpriseConnection(boxConfig);
                BoxDeveloperEditionAPIConnection userClient = BoxDeveloperEditionAPIConnection.getAppUserConnection(userId,
                    boxConfig);

                BoxFolder skelFolder = new BoxFolder(serviceAccountClient, skelFolderId);
                BoxCollaboration.Info skelFolderCollaboration;
                try {
                    skelFolderCollaboration = skelFolder.collaborate(new
                        BoxUser(serviceAccountClient, userId),
                        BoxCollaboration.Role.EDITOR);
                } catch (BoxAPIException e) {
                    System.out.println("Searching for existing collaborator.");
                    JsonObject errorMessage = JsonObject.readFrom(e.getResponse());
                    String code = errorMessage.get("code").asString().intern();
                    if (code == "user_already_collaborator") {
                        System.out.println("Already collaborated...");
                        Collection<BoxCollaboration.Info > collaborations = skelFolder.getCollaborations();
                        System.out.println(collaborations.size());
                        Optional<BoxCollaboration.Info > results =
                            collaborations.stream().filter(c -> {
                            return c.getAccessibleBy().getID().intern() == userId;
                        }).findFirst();
                        if (results.isPresent()) {
                            skelFolderCollaboration = results.get();
                        } else {
                            throw new Exception("Couldn't create new collaboration
                                or find existing collaboration.");
                        }
                    } else {
                        throw e;
                    }
                }
                System.out.println(skelFolderCollaboration.getID());

                BoxFolder collabedSkelFolder = new BoxFolder(userClient, skelFolderId);
                ArrayList<BoxItem.Info > copiedItems = new ArrayList<>();
                for (BoxItem.Info itemInfo: collabedSkelFolder) {
                    if (itemInfo instanceof BoxFile.Info) {
                        BoxFile.Info fileInfo = (BoxFile.Info) itemInfo;
                        BoxFile copyFile = new BoxFile(userClient, fileInfo.getID());
                        BoxFile.Info copiedFile;
                        try {
                            copiedFile = copyFile.copy(BoxFolder.getRootFolder(userClient));
                        } catch (BoxAPIException e) {
                            System.out.println(e.getMessage());
                            String conflictId = getIdFromConflict(e.getMessage());
                            System.out.println(conflictId);
                            copiedFile = new BoxFile(userClient, conflictId).getInfo();
                        }
                        copiedItems.add((BoxItem.Info) copiedFile);
                    } else if (itemInfo instanceof BoxFolder.Info) {
                        BoxFolder.Info folderInfo = (BoxFolder.Info) itemInfo;
                        BoxFolder copyFolder = new BoxFolder(userClient, folderInfo.getID());
                        BoxFolder.Info copiedFolder;
                        try {
                            copiedFolder = copyFolder.copy(BoxFolder.getRootFolder(userClient));
                        } catch (BoxAPIException e) {
                            System.out.println(e.getMessage());
                            String conflictId = getIdFromConflict(e.getMessage());
                            System.out.println(conflictId);
                            copiedFolder = new BoxFolder(userClient, conflictId).getInfo();
                        }
                        copiedItems.add((BoxItem.Info) copiedFolder);
                    }
                }

                System.out.println("Copied " + copiedItems.size() +
                    " items from the skel directory.");

                BoxCollaboration tempSkelCollab = new BoxCollaboration(serviceAccountClient,
                    skelFolderCollaboration.getID());
                tempSkelCollab.delete();
                System.out.println("Removed temporary skel directory collaboration.");
            }
        }

        private static String getIdFromConflict(String message) {
            String id = "";
            Pattern p = Pattern.compile("\"id\":\"[0-9]+\"");
            Pattern p2 = Pattern.compile("[0-9]+");
            Matcher m = p.matcher(message);
            if (m.find()) {
                String sub = m.group();
                Matcher m2 = p2.matcher(sub);
                if (m2.find()) {
                    id = m2.group();
                }
            }
            return id;
        }
    }
    ```
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    using System;
    using System.Collections;
    using System.Collections.Generic;
    using System.IO;
    using System.Linq;
    using System.Threading.Tasks;
    using Box.V2;
    using Box.V2.Config;
    using Box.V2.Exceptions;
    using Box.V2.JWTAuth;
    using Box.V2.Models;
    using Newtonsoft.Json.Linq;

    namespace BoxPlayground {
        public class Program {
            static void Main(string[] args) {
                ExecuteMainAsync().Wait();
            }

            private static async Task ExecuteMainAsync() {
                using(FileStream fs =
                    new FileStream("./config.json", FileMode.Open)) {
                    var skelFolderId = "45117847998";
                    var userId = "275111793";

                    var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs));
                    var client = session.AdminClient(session.AdminToken());
                    var userClient = session.UserClient(session.UserToken(userId),
                        userId);
                    BoxCollaboration collabSkelFolder;
                    try {
                        collabSkelFolder = await client.CollaborationsManager.AddCollaborationAsync(
                        new BoxCollaborationRequest {
                            AccessibleBy = new BoxCollaborationUserRequest {
                                Id = userId
                            },
                            Item = new BoxRequestEntity {
                                Id = skelFolderId,
                                Type = BoxType.folder
                            },
                            Role = BoxCollaborationRole.Editor.ToString()
                        });
                    }
                    catch(BoxException e) {
                        var errorMessage = JObject.Parse(e.Message);
                        if (errorMessage.GetValue("code").ToString()
                            == "user_already_collaborator") {
                            System.Console.WriteLine("Already a collaborator");
                            var collaborations = await client.FoldersManager.GetCollaborationsAsync(skelFolderId);
                            var existingCollab = collaborations.Entries.Find((collaboration)
                                = >{
                                return collaboration.AccessibleBy.Id == userId;
                            });
                            if (existingCollab != null) {
                                collabSkelFolder = existingCollab;
                            }
                            else {
                                throw new Exception("Couldn't create new collaboration
                                    or find existing collaboration");
                            }
                        }
                        else {
                            throw e;
                        }
                    }

                    var items = await
                        userClient.FoldersManager.GetFolderItemsAsync(skelFolderId,
                        limit: 1000, autoPaginate: true);
                    var copyTasks = new List < Task < BoxItem >> ();
                    items.Entries.ForEach((item) = >{
                        if (item.Type == BoxType.folder.ToString()) {
                            copyTasks.Add(userClient.FoldersManager.CopyAsync(new
                                BoxFolderRequest {
                                Id = item.Id,
                                Parent = new BoxRequestEntity {
                                    Id = "0"
                                }
                            }).ContinueWith((folder) = >{
                                try {
                                    return (BoxItem) folder.Result;
                                }
                                catch(Exception e) {
                                    var errorMessage = JObject.Parse(e.InnerException.Message);
                                    if (errorMessage.GetValue("status").ToObject
                                        < int > () == 409) {
                                        System.Console.WriteLine("Conflict found");
                                        System.Console.WriteLine(errorMessage.SelectToken("context_info.conflicts.id"));
                                        return (BoxItem) userClient.FoldersManager.GetInformationAsync(errorMessage.SelectToken("context_info.conflicts.id").ToString()).Result;
                                    }
                                    else {
                                        throw e;
                                    }
                                }

                            }));
                        }
                        else if (item.Type == BoxType.file.ToString()) {
                            copyTasks.Add(userClient.FilesManager.CopyAsync(new
                                BoxFileRequest {
                                Id = item.Id,
                                Parent = new BoxRequestEntity {
                                    Id = "0"
                                }
                            }).ContinueWith((file) = >{
                                try {
                                    return (BoxItem) file.Result;
                                }
                                catch(Exception e) {
                                    var errorMessage = JObject.Parse(e.InnerException.Message);
                                    if (errorMessage.GetValue("status").ToObject
                                        < int > () == 409) {
                                        System.Console.WriteLine("Conflict found");
                                        System.Console.WriteLine(errorMessage.SelectToken("context_info.conflicts.id"));
                                        return (BoxItem) userClient.FilesManager.GetInformationAsync(errorMessage.SelectToken("context_info.conflicts.id").ToString()).Result;
                                    }
                                    else {
                                        throw e;
                                    }
                                }
                            }));
                        }
                        else {
                            System.Console.WriteLine("Couldn't process this item...");
                        }
                    });
                    var copiedItems = await Task.WhenAll(copyTasks);
                    System.Console.WriteLine($ "Copied {copiedItems.Count()}
                        items from the skel directory.");

                    if (await client.CollaborationsManager.RemoveCollaborationAsync(collabSkelFolder.Id)){
                        System.Console.WriteLine("Removed temporary skel
                            directory collaboration...");
                        System.Console.WriteLine("Complete!");
                    }
                    else {
                        System.Console.WriteLine("Something went wrong when
                            removing skel directory collaboration.");
                    }
                }
            }
        }
    }
    ```
  </Tab>
</Tabs>

<RelatedLinks title="RELATED GUIDES" />


# Setup Shared Folders
Source: https://developer.box.com/guides/users/provision/shared-folders



As a final step to manage access to shared folders, we'll create the folder
structures needed within the service account. Then, groups will map to the
needed permissions based on user types and level of access needed to those
folders. We'll use a Marketing Department as an example.

<Tabs>
  <Tab title="marketing_folders.json">
    ```json theme={null}
    {
      "name": "Marketing Department",
      "parent": {
        "id": "0"
      },
      "children": [
        {
          "name": "Projects",
          "children": []
        },
        {
          "name": "Newsletter",
          "children": [
            {
              "name": "Drafts",
              "children": []
            }
          ]
        }
      ]
    }
    ```
  </Tab>
</Tabs>

Working from this sample folder structure, we can use the folder tree creator
code we used earlier to create the `etc/skel` structure. That code may be
modified to make your own structure.

Once created, we'll need the IDs of the folders that each group will need to
access. For example, Marketing managers will likely have `editor` access to all
folders within the Marketing Department. On the other hand, Marketing project
managers will likely need `editor` access to only the `Projects` folder. We'll
create two groups and give them these permissions.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    "use strict";
    const fs = require("fs");
    const box = require("box-node-sdk");

    let configFile = fs.readFileSync("config.json");
    configFile = JSON.parse(configFile);

    let session = box.getPreconfiguredInstance(configFile);
    let serviceAccountClient = session.getAppAuthClient("enterprise");

    const marketingDeptFolderID = "45765309069";
    const marketingProjectsFolderID = "45765461670";
    const marketingManagersGroupName = "Marketing Managers";
    const marketingProjectManagersGroupName = "Marketing Project Managers";

    (async () => {
        let marketingManagerGroup;
        try {
            marketingManagerGroup = await serviceAccountClient.groups.create(
                marketingManagersGroupName,
                {
                    description: "For Marketing department leadership team.",
                    invitability_level: "admins_only",
                    member_viewability_level: "admins_only"
                }
            );
        } catch (e) {
          marketingManagerGroup = await handleGroupConflictError(
              e,
              marketingManagersGroupName,
              serviceAccountClient
          );
        }

        console.log(marketingManagerGroup);

        let marketingProjectManagerGroup;
        try {
            marketingProjectManagerGroup = await serviceAccountClient.groups.create(
                marketingProjectManagersGroupName,
                {
                    description: "All team members who manage Marketing projects.",
                    invitability_level: "admins_and_members",
                    member_viewability_level: "admins_and_members"
                }
            );
        } catch (e) {
            marketingProjectManagerGroup = await handleGroupConflictError(
                e,
                marketingProjectManagersGroupName,
                serviceAccountClient
            );
        }

        console.log(marketingProjectManagerGroup);

        let collabMarketingManagers;
        try {
            collabMarketingManagers = await serviceAccountClient.collaborations.createWithGroupID(
                marketingManagerGroup.id,
                marketingDeptFolderID,
                serviceAccountClient.collaborationRoles.EDITOR
            );
        } catch (e) {
            collabMarketingManagers = await handleFolderCollaborationConflictError(
                e,
                marketingDeptFolderID,
                marketingManagerGroup.id,
                serviceAccountClient
            );
        }
        console.log(collabMarketingManagers);

        let collabMarketingProjectManagers;
        try {
            collabMarketingProjectManagers = await serviceAccountClient.collaborations.createWithGroupID(
                marketingProjectManagerGroup.id,
                marketingProjectsFolderID,
                serviceAccountClient.collaborationRoles.EDITOR
            );
        } catch (e) {
            collabMarketingProjectManagers = await handleFolderCollaborationConflictError(
                e,
                marketingProjectsFolderID,
                marketingProjectManagerGroup.id,
                serviceAccountClient
            );
        }
        console.log(collabMarketingProjectManagers);
    })();

    async function autoPage(iterator, collection = []) {
        let moveToNextItem = async () => {
            let item = await iterator.next();
            if (item.value) {
                collection.push(item.value);
            }

            if (item.done !== true) {
                return moveToNextItem();
            } else {
                return collection;
            }
        };
        return moveToNextItem();
    }

    async function handleGroupConflictError(e, groupName, boxClient) {
        let storeIteratorSetting = boxClient._useIterators;
        if (e && e.response && e.response.body && e.response.body.status === 409) {
            boxClient._useIterators = true;
            let groupsIterator = await boxClient.groups.getAll({
                name: groupName
            });
            let groups = await autoPage(groupsIterator);
            let results = groups.filter(group => {
                return group.name === groupName;
            });
            if (results.length > 0) {
                boxClient._useIterators = storeIteratorSetting;
                return results[0];
            } else {
                throw new Error("Couldn't create group or find existing group.");
            }
        } else {
            throw e;
        }
    }

    async function handleFolderCollaborationConflictError(
        e,
        folderID,
        groupID,
        boxClient
    ) {
        let storeIteratorSetting = boxClient._useIterators;
        if (e && e.response && e.response.body && e.response.body.status === 409) {
            boxClient._useIterators = true;
            let collaborationsIterator = await boxClient.folders.getCollaborations(
                folderID
            );
            let collaborations = await autoPage(collaborationsIterator);
            let results = collaborations.filter(collaboration => {
                return collaboration.accessible_by.id === groupID;
            });
            console.log(results);
            if (results.length > 0) {
                boxClient._useIterators = storeIteratorSetting;
                return results[0];
            } else {
                throw new Error(
                    "Couldn't create new collaboration or located existing collaboration."
                );
            }
        } else {
            throw e;
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    package com.box;

    import java.io.BufferedReader;
    import java.nio.charset.Charset;
    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.nio.file.Paths;
    import java.util.Collection;
    import java.util.Optional;
    import com.box.sdk.BoxAPIException;
    import com.box.sdk.BoxCollaboration;
    import com.box.sdk.BoxConfig;
    import com.box.sdk.BoxDeveloperEditionAPIConnection;
    import com.box.sdk.BoxFolder;
    import com.box.sdk.BoxGroup;
    import com.eclipsesource.json.JsonObject;

    public class BoxPlayground {

        public static void main(String[] args) throws Exception {
            Path configPath = Paths.get("config.json");
            try (BufferedReader reader =
                Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) {
                String marketingDeptFolderID = "45765309069";
                String marketingProjectsFolderID = "45765461670";
                String marketingManagersGroupName = "Marketing Managers";
                String marketingProjectManagersGroupName = "Marketing Project Managers";

                BoxConfig boxConfig = BoxConfig.readFrom(reader);
                BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection
                    .getAppEnterpriseConnection(boxConfig);

                BoxGroup.Info marketingManagerGroup;
                try {
                    marketingManagerGroup = BoxGroup.createGroup(serviceAccountClient,
                        marketingManagersGroupName, null,
                        null, "For Marketing department leadership team.",
                        "admins_only", "admins_only");
                } catch (BoxAPIException e) {
                    JsonObject errorMessage = JsonObject.readFrom(e.getResponse());
                    int status = errorMessage.get("status").asInt();
                    if (status == 409) {
                        marketingManagerGroup =
                            handleGroupConflictError(marketingManagersGroupName,
                            serviceAccountClient);
                    } else {
                        throw e;
                    }
                }
                System.out.println(marketingManagerGroup.getID());

                BoxGroup.Info marketingProjectManagerGroup;
                try {
                    marketingProjectManagerGroup = BoxGroup.createGroup(serviceAccountClient,
                        marketingProjectManagersGroupName, null, null,
                        "All team members who manage Marketing projects.",
                        "admins_and_members", "admins_and_members");
                } catch (BoxAPIException e) {
                    JsonObject errorMessage = JsonObject.readFrom(e.getResponse());
                    int status = errorMessage.get("status").asInt();
                    if (status == 409) {
                        marketingProjectManagerGroup = handleGroupConflictError(marketingProjectManagersGroupName,
                            serviceAccountClient);
                    } else {
                        throw e;
                    }
                }
                System.out.println(marketingProjectManagerGroup.getID());

                BoxFolder marketDeptFolder =
                    new BoxFolder(serviceAccountClient, marketingDeptFolderID);
                BoxCollaboration.Info marketingDeptFolderCollaboration;
                try {
                    marketingDeptFolderCollaboration = marketDeptFolder.collaborate(
                        new BoxGroup(serviceAccountClient, marketingManagerGroup.getID()),
                        BoxCollaboration.Role.EDITOR);
                } catch (BoxAPIException e) {
                    System.out.println("Searching for existing collaborator.");
                    JsonObject errorMessage = JsonObject.readFrom(e.getResponse());
                    int status = errorMessage.get("status").asInt();
                    if (status == 409) {
                        marketingDeptFolderCollaboration = handleFolderCollaborationConflict(marketDeptFolder,
                            marketingManagerGroup.getID());
                    } else {
                        throw e;
                    }
                }
                System.out.println(marketingDeptFolderCollaboration.getID());

                BoxFolder marketingProjectsFolder =
                    new BoxFolder(serviceAccountClient, marketingProjectsFolderID);
                BoxCollaboration.Info marketingProjectsFolderCollaboration;
                try {
                    marketingProjectsFolderCollaboration = marketingProjectsFolder.collaborate(
                        new BoxGroup(serviceAccountClient, marketingProjectManagerGroup.getID()),
                        BoxCollaboration.Role.EDITOR);
                } catch (BoxAPIException e) {
                    System.out.println("Searching for existing collaborator.");
                    JsonObject errorMessage = JsonObject.readFrom(e.getResponse());
                    int status = errorMessage.get("status").asInt();
                    if (status == 409) {
                        marketingProjectsFolderCollaboration = handleFolderCollaborationConflict(marketingProjectsFolder,
                            marketingProjectManagerGroup.getID());
                    } else {
                        throw e;
                    }
                }
                System.out.println(marketingProjectsFolderCollaboration.getID());

            }
        }

        private static BoxCollaboration.Info
            handleFolderCollaborationConflict(BoxFolder folder, String groupID)
        throws Exception {
            System.out.println("Already collaborated...");
            Collection<BoxCollaboration.Info > collaborations = folder.getCollaborations();
            Optional<BoxCollaboration.Info > results =
                collaborations.stream().filter(c -> {
                return c.getAccessibleBy().getID().intern() == groupID.intern();
            }).findFirst();
            if (results.isPresent()) {
                return results.get();
            } else {
                throw new Exception("Couldn't create new
                    collaboration or find existing collaboration.");
            }
        }

        private static BoxGroup.Info handleGroupConflictError(String groupName,
            BoxDeveloperEditionAPIConnection boxClient)
        throws Exception {
            Iterable<BoxGroup.Info > groups =
                BoxGroup.getAllGroupsByName(boxClient, groupName);
            BoxGroup.Info foundGroup = null;
            for (BoxGroup.Info group: groups) {
                if (group.getName().intern() == groupName) {
                    foundGroup = group;
                    break;
                }
            }
            if (foundGroup != null) {
                return foundGroup;
            } else {
                throw new Exception("Couldn't create group or find existing group.");
            }
        }
    }
    ```
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    using System;
    using System.Collections;
    using System.Collections.Generic;
    using System.IO;
    using System.Linq;
    using System.Threading.Tasks;
    using Box.V2;
    using Box.V2.Config;
    using Box.V2.Exceptions;
    using Box.V2.JWTAuth;
    using Box.V2.Models;
    using Box.V2.Models.Request;
    using Newtonsoft.Json.Linq;

    namespace BoxPlayground {
        public class Program {
            static void Main(string[] args) {
                ExecuteMainAsync().Wait();
            }

            private static async Task ExecuteMainAsync() {
                using(FileStream fs =
                    new FileStream("./config.json", FileMode.Open)) {
                    var marketingDeptFolderId = "45765309069";
                    var marketingProjectsFolderId = "45765461670";
                    var marketingManagersGroupName = "Marketing Managers";
                    var marketingProjectManagersGroupName = "Marketing Project Managers";

                    var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs));
                    var serviceAccountClient = session.AdminClient(session.AdminToken());

                    BoxGroup marketingManagerGroup;
                    try {
                        marketingManagerGroup = await
                            serviceAccountClient.GroupsManager.CreateAsync(new
                                BoxGroupRequest {
                            Name = marketingManagersGroupName,
                            InvitabilityLevel = "admins_only",
                            MemberViewabilityLevel = "admins_only"
                        });
                    }
                    catch(BoxException e) {
                        var errorMessage = JObject.Parse(e.Message);
                        if (errorMessage.GetValue("status").ToObject < int >
                            () == 409) {
                            marketingManagerGroup = await
                                HandleGroupConflictError(marketingManagersGroupName,
                                serviceAccountClient);
                        }
                        else {
                            throw e;
                        }
                    }
                    System.Console.WriteLine(marketingManagerGroup.Id);

                    BoxGroup marketingProjectsManagerGroup;
                    try {
                        marketingProjectsManagerGroup = await
                            serviceAccountClient.GroupsManager.CreateAsync(new
                                BoxGroupRequest {
                            Name = marketingProjectManagersGroupName,
                            InvitabilityLevel = "admins_and_members",
                            MemberViewabilityLevel = "admins_and_members"
                        });
                    }
                    catch(BoxException e) {
                        var errorMessage = JObject.Parse(e.Message);
                        if (errorMessage.GetValue("status").ToObject < int >
                            () == 409) {
                            marketingProjectsManagerGroup = await
                                HandleGroupConflictError(marketingProjectManagersGroupName,
                                serviceAccountClient);
                        }
                        else {
                            throw e;
                        }
                    }
                    System.Console.WriteLine(marketingProjectsManagerGroup.Id);

                    BoxCollaboration marketingManagerCollab;
                    try {
                        marketingManagerCollab = await serviceAccountClient.CollaborationsManager.AddCollaborationAsync(
                        new BoxCollaborationRequest {
                            AccessibleBy = new BoxCollaborationUserRequest {
                                Id = marketingManagerGroup.Id,
                                Type = BoxType.group
                            },
                            Item = new BoxRequestEntity {
                                Id = marketingDeptFolderId,
                                Type = BoxType.folder
                            },
                            Role = BoxCollaborationRole.Editor.ToString()
                        });
                    }
                    catch(BoxException e) {
                        var errorMessage = JObject.Parse(e.Message);
                        if (errorMessage.GetValue("status").ToObject < int >
                            () == 409) {
                            marketingManagerCollab = await
                                HandleFolderCollaborationConflictError(marketingDeptFolderId,
                                marketingManagerGroup.Id, serviceAccountClient);
                        }
                        else {
                            throw e;
                        }
                    }
                    System.Console.WriteLine(marketingManagerCollab.Id);

                    BoxCollaboration marketingProjectsManagerCollab;
                    try {
                        marketingProjectsManagerCollab = await serviceAccountClient.CollaborationsManager.AddCollaborationAsync(
                        new BoxCollaborationRequest {
                            AccessibleBy = new BoxCollaborationUserRequest {
                                Id = marketingProjectsManagerGroup.Id,
                                Type = BoxType.group
                            },
                            Item = new BoxRequestEntity {
                                Id = marketingProjectsFolderId,
                                Type = BoxType.folder
                            },
                            Role = BoxCollaborationRole.Editor.ToString()
                        });
                    }
                    catch(BoxException e) {
                        var errorMessage = JObject.Parse(e.Message);
                        if (errorMessage.GetValue("status").ToObject < int >
                            () == 409) {
                            marketingProjectsManagerCollab = await
                                HandleFolderCollaborationConflictError(marketingProjectsFolderId,
                                    marketingProjectsManagerGroup.Id, serviceAccountClient);
                        }
                        else {
                            throw e;
                        }
                    }
                    System.Console.WriteLine(marketingProjectsManagerCollab.Id);
                }
            }

            public async static Task < BoxGroup >
                HandleGroupConflictError(string groupName, BoxClient boxClient) {
                System.Console.WriteLine("Found conflict.");
                var groups = await
                    boxClient.GroupsManager.GetAllGroupsAsync(autoPaginate: true);
                return groups.Entries.Find((group) = >{
                    return group.Name == groupName;
                });
            }
            public async static Task < BoxCollaboration >
                HandleFolderCollaborationConflictError(string folderId,
                string groupId, BoxClient boxClient) {
                System.Console.WriteLine("Already a collaborator");
                var collaborations = await boxClient.FoldersManager.GetCollaborationsAsync(folderId);
                var existingCollab =
                    collaborations.Entries.Find((collaboration) = >{
                    return collaboration.AccessibleBy.Id == groupId;
                });
                if (existingCollab != null) {
                    return existingCollab;
                }
                else {
                    throw new Exception("Couldn't create new collaboration or find existing collaboration");
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    box groups:create "Marketing Managers" --invite=admins_only --view-members=admins_only
    box groups:create "Marketing Project Managers" --invite=admins_and_members --view-members=admins_and_members
    ```
  </Tab>
</Tabs>

Once the groups are created, add the user to that group and they will
have the prescribed access to the shared folders created within the service
account.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    'use strict'
    const fs = require('fs');
    const box = require('box-node-sdk');

    let configFile = fs.readFileSync('config.json');
    configFile = JSON.parse(configFile);

    let session = box.getPreconfiguredInstance(configFile);
    let serviceAccountClient = session.getAppAuthClient("enterprise");

    const marketingManagerGroupID = "839790214";
    const marketingManagerUserID = "275111793";

    (async () => {
        let addedUser;
        try {
            addedUser = await
                serviceAccountClient.groups.addUser(marketingManagerGroupID,
                marketingManagerUserID, {
                role: serviceAccountClient.groups.userRoles.ADMIN
            });
        } catch (e) {
            addedUser =
                await handleGroupMembershipConflictError(e,
                marketingManagerGroupID, marketingManagerUserID, serviceAccountClient);
        }
        console.log(addedUser);
    })();

    async function autoPage(iterator, collection = []) {
        let moveToNextItem = async () => {
            let item = await iterator.next();
            if (item.value) {
                collection.push(item.value);
            }

            if (item.done !== true) {
                return moveToNextItem();
            } else {
                return collection;
            }
        }
        return moveToNextItem();
    }

    async function handleGroupMembershipConflictError(e,
        groupID, userID, boxClient) {
        let storeIteratorSetting = boxClient._useIterators;
        if (e && e.response
            && e.response.body
            && e.response.body.status === 409) {
            boxClient._useIterators = true;
            let groupMembershipsIterator = await boxClient.groups.getMemberships(groupID);
            let groupMemberships = await autoPage(groupMembershipsIterator);
            let results = groupMemberships.filter((groupMembership) => {
                return groupMembership.user.id === userID;
            });
            if (results.length > 0) {
                boxClient._useIterators = storeIteratorSetting;
                return results[0];
            } else {
                throw new Error("Couldn't create group membership or find existing group membership.");
            }
        } else {
            throw e;
        }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    package com.box;

    import java.io.BufferedReader;
    import java.nio.charset.Charset;
    import java.nio.file.Files;
    import java.nio.file.Path;
    import java.nio.file.Paths;
    import com.box.sdk.BoxAPIException;
    import com.box.sdk.BoxConfig;
    import com.box.sdk.BoxDeveloperEditionAPIConnection;
    import com.box.sdk.BoxGroup;
    import com.box.sdk.BoxGroupMembership;
    import com.box.sdk.BoxUser;
    import com.box.sdk.BoxGroupMembership.Role;
    import com.eclipsesource.json.JsonObject;

    public class BoxPlayground {

        public static void main(String[] args) throws Exception {
            Path configPath = Paths.get("config.json");
            try (BufferedReader reader =
                Files.newBufferedReader(configPath, Charset.forName("UTF-8"))) {
                String marketingManagerGroupID = "839982796";
                String marketingManagerUserID = "275111793";

                BoxConfig boxConfig = BoxConfig.readFrom(reader);
                BoxDeveloperEditionAPIConnection serviceAccountClient = BoxDeveloperEditionAPIConnection
                    .getAppEnterpriseConnection(boxConfig);

                BoxGroupMembership.Info marketingManagerMembership = null;
                BoxGroup marketingManagerGroup =
                    new BoxGroup(serviceAccountClient, marketingManagerGroupID);
                try {
                    marketingManagerMembership = marketingManagerGroup
                        .addMembership(new BoxUser(serviceAccountClient,
                        marketingManagerUserID), Role.ADMIN);
                } catch (BoxAPIException e) {
                    JsonObject errorMessage = JsonObject.readFrom(e.getResponse());
                    int status = errorMessage.get("status").asInt();
                    if (status == 409) {
                        System.out.println("Found existing membership");
                        Iterable<BoxGroupMembership.Info > memberships = marketingManagerGroup.getAllMemberships();
                        for (BoxGroupMembership.Info membership: memberships) {
                            if (membership.getUser().getID().intern()
                                == marketingManagerUserID) {
                                marketingManagerMembership = membership;
                                break;
                            }
                        }
                        if (marketingManagerMembership == null) {
                            throw new Exception("Couldn't add user to
                                group or find existing membership");
                        }
                    } else {
                        throw e;
                    }
                }
                System.out.println(marketingManagerMembership.getID());
                System.out.println(marketingManagerMembership.getRole());
            }
        }
    }
    ```
  </Tab>

  <Tab title=".NET">
    ```csharp theme={null}
    using System;
    using System.Collections;
    using System.Collections.Generic;
    using System.IO;
    using System.Linq;
    using System.Threading.Tasks;
    using Box.V2;
    using Box.V2.Config;
    using Box.V2.Exceptions;
    using Box.V2.JWTAuth;
    using Box.V2.Models;
    using Box.V2.Models.Request;
    using Newtonsoft.Json.Linq;

    namespace BoxPlayground {
        public class Program {
            static void Main(string[] args) {
                ExecuteMainAsync().Wait();
            }

            private static async Task ExecuteMainAsync() {
                using(FileStream fs =
                    new FileStream("./config.json", FileMode.Open)) {
                    var marketingManagerGroupId = "839982796";
                    var marketingManagerUserId = "275111793";

                    var session = new BoxJWTAuth(BoxConfig.CreateFromJsonFile(fs));
                    var serviceAccountClient = session.AdminClient(session.AdminToken());
                    BoxGroupMembership marketingManagerMembership;
                    try {
                        marketingManagerMembership = await
                            serviceAccountClient.GroupsManager.AddMemberToGroupAsync(new
                            BoxGroupMembershipRequest {
                            User = new BoxRequestEntity {
                                Id = marketingManagerUserId
                            },
                            Group = new BoxGroupRequest {
                                Id = marketingManagerGroupId
                            },
                            Role = "admin"
                        });
                    }
                    catch(BoxException e) {
                        var errorMessage = JObject.Parse(e.Message);
                        if (errorMessage.GetValue("status").ToObject
                            < int > () == 409) {
                            var groups = await
                                serviceAccountClient.GroupsManager.GetAllGroupMembershipsForGroupAsync(marketingManagerGroupId,
                                autoPaginate: true);
                            marketingManagerMembership =
                                groups.Entries.Find((group) = >{
                                return group.User.Id == marketingManagerUserId;
                            });

                            if (marketingManagerMembership == null) {
                                throw new Exception("Couldn't create new
                                    collaboration or find existing collaboration");
                            }
                        }
                        else {
                            throw e;
                        }
                    }
                    System.Console.WriteLine(marketingManagerMembership.Id);
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```shell theme={null}
    box groups:membership:add $user_id $group_id --role=admin
    ```
  </Tab>
</Tabs>

<RelatedLinks title="RELATED GUIDES" />


# Delete webhooks (v1)
Source: https://developer.box.com/guides/webhooks/v1/delete-v1



<RelatedLinks title="REQUIRED GUIDES" />

V1 webhooks cannot be fully deleted. Instead, the webhook can be set back to
Developer Mode by [support][support]. Developers can also remove the
application from their account by revisiting the enablement URL and
clicking **Remove**.

[support]: https://support.box.com/hc/en-us/requests/new


# Create webhooks (v2)
Source: https://developer.box.com/guides/webhooks/v2/create-v2



V2 webhooks can monitor specific files or folders. They can be
created in the [Developer Console][console] and with API.

## Developer console

<Warning>
  V2 webhooks can be created only when the scope **Manage Webhooks**
  is selected and the application is authorized. See more about
  <Link href="/guides/applications">Required Access Scopes</Link> and <Link href="/guides/authorization">authorization</Link>.
</Warning>

To create a webhook follow the steps below.

1. Navigate to your application in the [Developer Console][console].
2. Select the **Webhooks** tab.
3. Click the **Create webhook** button.
4. Select **V2** from the drop-down list.
5. Fill in the form.
6. Click **Create webhook** button to save your changes.

### Required fields

| Field name | Description | Required |
| - | - | - |
| URL Address | URL address to be notified by the webhook. | Yes |
| Content type | Type of content (file/folder) the webhook is configured for. | Yes |
| Triggers | Different triggers that activate the webhook. | Yes |

## API

<Warning>
  This API requires the application to have the **Manage Webhooks** scope enabled.
</Warning>

To attach a webhook to a folder, call the <Link href="/reference/post-webhooks">create webhook</Link> endpoint with the
type of `folder`, the ID of the folder, a URL to send webhook notifications to,
and a list of <Link href="/guides/webhooks/triggers">triggers</Link>.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X POST "https://api.box.com/2.0/webhooks" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "target": {
           "id": "21322",
           "type": "file"
         },
         "address": "https://example.com/webhooks",
         "triggers": [
           "FILE.PREVIEWED"
         ]
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.webhooks.createWebhook({
    target: {
      id: folder.id,
      type: 'folder' as CreateWebhookRequestBodyTargetTypeField,
    } satisfies CreateWebhookRequestBodyTargetField,
    address: 'https://example.com/new-webhook',
    triggers: ['FILE.UPLOADED' as CreateWebhookRequestBodyTriggersField],
  } satisfies CreateWebhookRequestBody);
  ```

  ```python Python v10 theme={null}
  client.webhooks.create_webhook(
      CreateWebhookTarget(id=folder.id, type=CreateWebhookTargetTypeField.FOLDER),
      "https://example.com/new-webhook",
      [CreateWebhookTriggers.FILE_UPLOADED],
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.Webhooks.CreateWebhookAsync(requestBody: new CreateWebhookRequestBody(target: new CreateWebhookRequestBodyTargetField() { Id = folder.Id, Type = CreateWebhookRequestBodyTargetTypeField.Folder }, address: "https://example.com/new-webhook", triggers: Array.AsReadOnly(new [] {new StringEnum<CreateWebhookRequestBodyTriggersField>(CreateWebhookRequestBodyTriggersField.FileUploaded)})));
  ```

  ```swift Swift v10 theme={null}
  try await client.webhooks.createWebhook(requestBody: CreateWebhookRequestBody(target: CreateWebhookRequestBodyTargetField(id: folder.id, type: CreateWebhookRequestBodyTargetTypeField.folder), address: "https://example.com/new-webhook", triggers: [CreateWebhookRequestBodyTriggersField.fileUploaded]))
  ```

  ```java Java v10 theme={null}
  client.getWebhooks().createWebhook(new CreateWebhookRequestBody(new CreateWebhookRequestBodyTargetField.Builder().id(folder.getId()).type(CreateWebhookRequestBodyTargetTypeField.FOLDER).build(), "https://example.com/new-webhook", Arrays.asList(CreateWebhookRequestBodyTriggersField.FILE_UPLOADED)))
  ```

  ```java Java v5 theme={null}
  // Listen for preview events for a file
  BoxFile file = new BoxFile(api, id);
  BoxWebHook.Info webhookInfo = BoxWebHook.create(file, url, BoxWebHook.Trigger.FILE.PREVIEWED);
  ```

  ```py Python v4 theme={null}
  file = client.file(file_id='12345')
  webhook = client.create_webhook(file, ['FILE.PREVIEWED'], 'https://example.com')
  print(f'Webhook ID is {webhook.id} and the address is {webhook.address}')
  ```

  ```csharp .NET v6 theme={null}
  var webhookParams = new BoxWebhookRequest()
  {
      Target = new BoxRequestEntity()
      {
          Type = BoxType.file,
          Id = "22222"
      },
      Triggers = new List<string>()
      {
          "FILE.PREVIEWED"
      },
      Address = "https://example.com/webhook"
  };
  BoxWebhook webhook = await client.WebhooksManager.CreateWebhookAsync(webhookParams);
  ```

  ```js Node v4 theme={null}
  // Attach a webhook that sends a notification to https://example.com/webhook when
  //   file 11111 is renamed or downloaded.
  client.webhooks.create(
   '11111',
   client.itemTypes.FILE,
   'https://example.com/webhook',
   [
    client.webhooks.triggerTypes.FILE.RENAMED,
    client.webhooks.triggerTypes.FILE.DOWNLOADED
   ])
   .then(webhook => {
    /* webhook -> {
     id: '12345',
     type: 'webhook',
     target: { id: '11111', type: 'file' },
     created_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' },
     created_at: '2016-05-09T17:41:27-07:00',
     address: 'https://example.com/webhook',
     triggers: [ 'FILE.RENAMED', 'FILE.UPLOADED' ] }
    */
   });
  ```
</CodeGroup>

<Note>
  Webhooks do cascade, so if a webhook is set on a parent folder,
  it will also monitor sub-folders for the selected triggers.
</Note>

## Ownership

It is best practice and strongly recommended to create webhooks with a
<Link href="/guides/getting-started/users#service-account">Service Account</Link>, or user that will not be deleted, to avoid potential
issues with webhook delivery due to loss of access to content.

Similar to files and folders, webhooks are owned by a user. If a user who owns a
webhook is deleted, they will lose access to all files and folders that they
previously had access to. Their webhooks will begin to fail validation, but the
webhook service will continue to send events and require retries.

## Webhook address

The notification URL specified in the `address` parameter must be a valid URL
that you specify when you create a webhook. Every time one of the triggers is
activated, this URL is called.

The notification URL must use standard port `443` and should return
an HTTP status in the range of `200` to `299` within 30 seconds of receiving
the webhook payload.

## Webhook triggers

The triggers are a list of strings that specify the events which cause the
webhook to fire. For example, if you want the webhook to be triggered
when a user uploads a file, use `FILE.UPLOADED`.

You can find a list of available triggers <Link href="/guides/webhooks/triggers">in this guide</Link>.

[console]: https://app.box.com/developers/console

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Delete webhooks (v2)
Source: https://developer.box.com/guides/webhooks/v2/delete-v2



<RelatedLinks title="REQUIRED GUIDES" />

You can delete a webhook using the [Developer Console][console] or API.

## Developer Console

To delete a webhook follow the steps below.

1. Navigate to the **Webhooks** tab in the [Developer Console][console].
2. Select the webhook you want to delete by clicking on its ID.
3. Click the **Delete** button.
4. Confirm the action by clicking **Delete** under the warning message.

## API

To remove a webhook from a file or folder, you need to use the
<Link href="/reference/delete-webhooks-id">remove webhook endpoint</Link> with the ID of the webhook. You can
get this value using the <Link href="/reference/get-webhooks">list all webhooks endpoint</Link>.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X DELETE "https://api.box.com/2.0/webhooks/3321123" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.webhooks.deleteWebhookById(webhook.id!);
  ```

  ```python Python v10 theme={null}
  client.webhooks.delete_webhook_by_id(webhook.id)
  ```

  ```csharp .NET v10 theme={null}
  await client.Webhooks.DeleteWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id));
  ```

  ```swift Swift v10 theme={null}
  try await client.webhooks.deleteWebhookById(webhookId: webhook.id!)
  ```

  ```java Java v10 theme={null}
  client.getWebhooks().deleteWebhookById(webhook.getId())
  ```

  ```py Python v4 theme={null}
  client.webhook(webhook_id='12345').delete()
  print('The webhook was successfully deleted!')
  ```

  ```csharp .NET v6 theme={null}
  await client.WebhooksManager.DeleteWebhookAsync("11111");
  ```

  ```js Node v4 theme={null}
  client.webhooks.delete('1234')
   .then(() => {
    // deletion succeeded — no value returned
   });
  ```
</CodeGroup>

## Automatic webhook deletion

Using <Link href="/reference/delete-webhooks-id">this</Link> endpoint is not the only way a webhook can be deleted.

The following reasons can cause webhooks to be deleted.

* Deleting a Box application automatically deletes all webhooks associated with it.
* Deleting all active Access Tokens associated with a webhook automatically deletes the webhook. This includes Developer Tokens and password.
* The last successful notification was delivered 30 days ago to the set URL and the period between the last successful notification delivery and the last user trigger event date exceeds 14 days.

  Let's go through a scenario
  in which the user downloads a file. This action
  triggers the webhook to use the set URL to
  delete a shared link.
  The diagram illustrates this scenario, showing
  when the webhook will be deleted.

  <Frame>
    <img alt="Delete webhooks" />
  </Frame>

  * **User event trigger**: when the user initiated the event, for example downloaded a file.
  * **Notification trigger**: when the notification was sent to the webhook, saying that the file was downloaded.
  * **Last notification delivery**: when the webhook sent a message to a specific URL, for example to delete a shared link.

In all of these cases Box sends a webhook payload with the
`WEBHOOK.DELETED` event name to the notification URL. The body of
the payload
includes the following additional information.

```json theme={null}
"additional_info": {
  "reason": "auto_cleanup"
}
```

[console]: https://app.box.com/developers/console

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# V2 webhooks
Source: https://developer.box.com/guides/webhooks/v2/index

Understand the payload headers, JSON body, and delivery retry behavior of Box V2 webhooks.

<RelatedLinks title="REQUIRED GUIDES" />

A V2 webhook sends an HTTP payload to your application when a triggering event
occurs on a file or folder. This guide describes the payload Box sends and how
Box handles failed deliveries.

## Flow

<Frame>
  <div>
    <img alt="Webhook flow" />
  </div>
</Frame>

When an event triggers a webhook for a file or a folder, Box makes an HTTP
call to the `address` specified when the webhook was created.
The payload of this call contains some request headers, and a JSON body.

## Payload headers

The payload sent by a webhook has the following Box-specific headers.

| Header | Description |
| - | - |
| `BOX-DELIVERY-ID` | A unique ID assigned by Box that identifies the delivered webhook payload. When Box retries a webhook, this ID changes, while the ID in the payload body remains the same. |
| `BOX-DELIVERY-TIMESTAMP` | An RFC-3339 timestamp that identifies when the payload was sent. |
| `BOX-SIGNATURE-PRIMARY` | A <Link href="/guides/webhooks/v2/signatures-v2">signature</Link> created using the primary signature key configured for this webhook. |
| `BOX-SIGNATURE-SECONDARY` | A <Link href="/guides/webhooks/v2/signatures-v2">signature</Link> created using the secondary signature key configured for this webhook. |
| `BOX-SIGNATURE-VERSION` | Value is always `1`. |
| `BOX-SIGNATURE-ALGORITHM` | Value is always `HmacSHA256`. |

For example:

```shell theme={null}
BOX-DELIVERY-ID:          673a081b-bb4b-4d45-b4f1-4131a29c1d07
BOX-DELIVERY-TIMESTAMP:   2016-07-11T10:10:33-07:00
BOX-SIGNATURE-PRIMARY:    isCeDp7mLR41/MjcSEFLag9bWmpJkgmN80Je4VIESdo=
BOX-SIGNATURE-SECONDARY:  1UbiiKS7/2o5vNIlyMh7e5QGCHq8lflWFgEF+YWBugI=
BOX-SIGNATURE-VERSION:    1
BOX-SIGNATURE-ALGORITHM:  HmacSHA256
USER-AGENT:               Box-WH-Client/0.1
```

<Note>
  We recommend <Link href="/guides/webhooks/v2/signatures-v2">setting up</Link> and <Link href="/guides/webhooks/v2/signatures-v2">verifying signatures</Link>
  of the webhook payloads.
</Note>

<Note>
  HTTP header names are case-insensitive. Your client should convert
  all header names to a standardized lowercase or uppercase format before trying
  to determine the value of a header.
</Note>

## Payload body

The body of a webhook payload is a JSON object that describes the file or folder
(target) that triggered the webhook, and the event that was triggered.

| Field | Description |
| - | - |
| `type` | Value is always `webhook_event`. |
| `id` | A unique ID assigned by Box that identifies an event. When Box retries a webhook, this ID does not change, while the ID in the header changes between calls. |
| `created_at` | The date and time when an event was triggered. |
| `trigger` | The name of the action that triggered an event, for example `FILE.UPLOADED`. |
| `webhook` | The webhook for which an event was triggered. |
| `created_by` | The user who triggered an event. |
| `source` | The item that triggered an event, for example the file that was uploaded to the target folder. |

Example:

```json theme={null}
{
  "type": "webhook_event",
  "id": "eb0c4e06-751f-442c-86f8-fd5bb404dbec",
  "created_at": "2016-07-11T10:10:32-07:00",
  "trigger": "FILE.UPLOADED",
  "webhook": {
    "id": "53",
    "type": "webhook"
  },
  "created_by": {
    "type": "user",
    "id": "226067247",
    "name": "John Q. Developer",
    "login": "johnq@dev.name"
  },
  "source": {
    "id": "73835521473",
    "type": "file",
    "file_version": {
      "type": "file_version",
      "id": "78096737033",
      "sha1": "2c61623e86bee78e6ab444af456bccc7a1164095"
    },
    "sequence_id": "0",
    "etag": "0",
    "sha1": "2c61623e86bee78e6ab444af456bccc7a1164095",
    "name": "Test-Image-3.png",
    "description": "",
    "size": 26458,
    "path_collection": {
      "total_count": 4,
      "entries": [
        {
          "type": "folder",
          "id": "0",
          "sequence_id": null,
          "etag": null,
          "name": "All Files"
        },
        {
          "type": "folder",
          "id": "2614853901",
          "sequence_id": "4",
          "etag": "4",
          "name": "Testing"
        },
        {
          "type": "folder",
          "id": "8290186265",
          "sequence_id": "0",
          "etag": "0",
          "name": "Webhooks Base"
        },
        {
          "type": "folder",
          "id": "8290188973",
          "sequence_id": "0",
          "etag": "0",
          "name": "Webhooks"
        }
      ]
    },
    "created_at": "2016-07-11T10:10:32-07:00",
    "modified_at": "2016-07-11T10:10:32-07:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2016-06-08T11:14:04-07:00",
    "content_modified_at": "2016-06-08T11:14:04-07:00",
    "created_by": {
      "type": "user",
      "id": "226067247",
      "name": "John Q. Developer",
      "login": "johnq@dev.name"
    },
    "modified_by": {
      "type": "user",
      "id": "226067247",
      "name": "John Q. Developer",
      "login": "johnq@dev.name"
    },
    "owned_by": {
      "type": "user",
      "id": "226067247",
      "name": "John Q. Developer",
      "login": "johnq@dev.name"
    },
    "shared_link": null,
    "parent": {
      "type": "folder",
      "id": "8290188973",
      "sequence_id": "0",
      "etag": "0",
      "name": "Webhooks"
    },
    "item_status": "active"
  },
  "additional_info": []
}
```

## Retries

Delivery of a webhook payload fails when Box does not receive a response with an
HTTP status code in the `200` to `299` range within 30 seconds of sending the
payload.

<Note>
  Box retries webhook deliveries up to 5 times over a period of 1 hour. These
  numbers could be subject to change.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Webhook limitations
Source: https://developer.box.com/guides/webhooks/v2/limitations-v2



## One webhook per item

There's a limit of one webhook for each item (file or folder), each application
and each authenticated user.

Once a webhook is attached to an item, no second webhook can be attached,
even if the second webhook would respond to a different trigger event.

Example: a webhook is set up by `John Doe` to watch
`FILE.UPLOADED` events in a folder with the name `Junk`, for an application
named `CleanupApp`. At that point, no second webhook can
be added to the `Junk` folder by the `CleanupApp` by `John Doe`, even if it
is to trigger for a `FILE.DOWNLOADED` event.

To listen to another event, <Link href="/guides/webhooks/v2/update-v2">update</Link> the existing webhook or create a
new application.

## 1000 webhooks limit

There is a limit of 1000 webhooks for each application and each user.

To create more webhooks for a user, create another application or
<Link href="/guides/webhooks/v2/update-v2">update existing webhooks</Link> to apply to higher levels in the folder tree.

## Notification URL restrictions

The notification URL or `address` for a webhook must be a valid HTTPS URL that
resolves to a valid IP address. It needs to have a certificate signed
by a reputable certificate authority. Box does not support self-signed SSL
certificates.

The IP address of the server must be publicly accessible from the internet and
cannot be a `(*.)box.com` address. The port used in the URL must be the
standard HTTPS port (`443`). Notifications will not be delivered to other ports.

The supported TLS protocol versions are `TLS 1.2` and `TLS 1.3` with FIPS-compliant cipher suites.

## No webhooks on root folder

V2 webhooks cannot be created on the root folder, which is the folder with ID
`0`. Instead, you will need to use a <Link href="/guides/webhooks/v1">v1 webhook</Link>.

<Note>
  When the permissions on an item prevent an action from occurring,
  no notification is sent for the attempted action.
</Note>

## `NO_ACTIVE_SESSION` is set in the webhook payload

If the auth session (access token) for the app you used to create a webhook
expires, that webhook no longer sends events with a full payload. In that
case, the event trigger is `NO_ACTIVE_SESSION`.

### JWT Auth

For webhooks created with the JWT Auth app, the session expires when
you delete the app authorization for this app in the Admin Console.
For more information, see [application authorization guide][app authorization].

### OAuth 2.0

For webhooks created with OAuth 2.0 Auth app, the session expires
when both the access token and the refresh token for the user and app
used for creating that webhook expire.

### Developer token

As the developer token cannot be refreshed and expires after 1 hour,
the event trigger `NO_ACTIVE_SESSION` is set in the webhook payload
after 1 hour.

## Reasons for webhook deletion

The following reasons can cause webhooks to be deleted.

1. Deleting a Box application automatically deletes all webhooks associated with it.
2. Deleting all active Access Tokens associated with a webhook automatically deletes the webhook. This includes Developer Tokens and password.
3. A webhook is automatically deleted if the last successful delivery was 30 days ago and the period between the last successful delivery and the last trigger date is more than 14 days.

In all of these cases Box sends a webhook payload with the
`WEBHOOK.DELETED` event name to the notification URL. The body of the payload
includes the following additional information.

```json theme={null}
"additional_info": {
  "reason": "auto_cleanup"
}
```

[app authorization]: https://support.box.com/hc/en-us/articles/360043697014-Authorizing-Apps-in-the-Box-App-Approval-Process

<RelatedLinks title="RELATED GUIDES" />


# List Webhooks for a User
Source: https://developer.box.com/guides/webhooks/v2/list-v2



To fetch all webhooks for the authenticated user, use the <Link href="/reference/get-webhooks">list all webhooks</Link>
endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/webhooks" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.webhooks.getWebhooks();
  ```

  ```python Python v10 theme={null}
  client.webhooks.get_webhooks()
  ```

  ```cs .NET v10 theme={null}
  await client.Webhooks.GetWebhooksAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.webhooks.getWebhooks()
  ```

  ```java Java v10 theme={null}
  client.getWebhooks().getWebhooks()
  ```

  ```java Java v5 theme={null}
  Iterable<BoxWebHook.Info> webhooks = BoxWebHook.all(api);
  for (BoxWebHook.Info webhookInfo: webhooks) {
      // Do something with the webhook.
  }
  ```

  ```python Python v4 theme={null}
  webhooks = client.get_webhooks()
  for webhook in webhooks:
      print(f'The webhook ID is {webhook.id} and the address is {webhook.address}')
  ```

  ```cs .NET v6 theme={null}
  BoxCollectionMarkerBased<BoxWebhook> webhooks = await client.WebhooksManager.GetWebhooksAsync();
  ```

  ```javascript Node v4 theme={null}
  client.webhooks.getAll()
  	.then(webhooks => {
  		/* webhooks -> {
  			next_marker: 'ZmlQZS0xLTE%3D',
  			entries: 
  			[ { id: '1234',
  				type: 'webhook',
  				target: { id: '22222', type: 'folder' } },
  				{ id: '5678',
  				type: 'webhook',
  				target: { id: '11111', type: 'file' } } ],
  			limit: 2 }
  		*/
  	});
  ```
</CodeGroup>

<Warning>
  This endpoint requires the application to have the **Manage Webhooks** scope
  enabled.
</Warning>

This API call will only list the webhooks for the authenticated user, not
for any other users in the enterprise.

<Note>
  This endpoint only returns V2 webhooks. <Link href="/guides/webhooks/v1">V1
  webhooks</Link> created in the Developer Console are not included in the
  response. They are only visible in the **Webhooks** tab of the Developer
  Console.

  Also, a Developer Token authenticates as the user logged in to the Developer
  Console, while a JWT or Client Credentials Grant app authenticates as its
  Service Account by default. Webhooks created with one of these identities
  will not appear when you list webhooks with a token for a different identity.
</Note>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Verify Box webhook signatures
Source: https://developer.box.com/guides/webhooks/v2/signatures-v2

Verify Box webhook payloads with HMAC signatures so you can reject requests that were not sent by Box.

Webhook signatures help ensure that a webhook payload was sent by Box and was
not tampered with. Signatures greatly reduce the likelihood of
a successful man-in-the-middle or replay attack.

When signatures are configured, Box generates a cryptographic digest of the
notification's body and attaches it to the header of the webhook payload. When
your application receives the payload, verify the signatures by calculating the
same digest and comparing it to the one received. If the digests do not match,
the payload should not be trusted.

You can achieve an extra level of protection by frequently changing the
signature keys. To enable a smooth transition between the old and new keys,
Box supports two simultaneous signature keys.

## Signature configuration

In order to attach signatures to an application's notifications, you must first
generate signature keys for the application.

To configure your application's keys follow the steps below.

1. Navigate to the application in the developer console.
2. Click on the **Webhooks** tab.
3. Click the **Manage signature keys** button.
4. Click the **Generate Key** button to configure your keys.

Once generating the primary or secondary key, copy the value. You will need
it to verify the webhook payloads. Every webhook will now include a
`BOX-SIGNATURE-PRIMARY` and `BOX-SIGNATURE-SECONDARY` header payload.

## Signature verification with SDKs

Although it is possible to verify signatures manually, methods are provided for
your convenience in the <Link href="/guides/tooling/sdks">official Box SDKs</Link>.

## Manual signature verification

The following steps describe the basics of how to verify a signature.

### Timestamp validation

Check if the timestamp in the `BOX-DELIVERY-TIMESTAMP` header of the payload is
not older than ten minutes.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    var timestamp = headers['BOX-DELIVERY-TIMESTAMP'];
    var date = Date.parse(timestamp);
    var expired = Date.now() - date > 10*60*1000;
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import dateutil.parser
    import pytz
    import datetime

    timestamp = headers["BOX-DELIVERY-TIMESTAMP"]
    date = dateutil.parser.parse(timestamp).astimezone(pytz.utc)

    now = datetime.datetime.now(pytz.utc)
    delta = datetime.timedelta(minutes=10)
    expiry_date = now - deltaMinutes

    expired = date >= expiry_date
    ```
  </Tab>
</Tabs>

### Calculate HMAC signature

Calculate the HMAC of the payload using either one of the two configured
signatures for the application in the [Developer Console][console].

Ensure you append the bytes of the payload body first, and then the bytes
of the timestamp found in the `BOX-DELIVERY-TIMESTAMP` header.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    var crypto = require('crypto');

    var primaryKey = '...';
    var secondaryKey = '...';

    var payload = '{"type":"webhook_event"...}';

    var hmac1 = crypto.createHmac('sha256', primaryKey);
    hmac1.update(payload);
    hmac1.update(timestamp);

    var hmac2 = crypto.createHmac('sha256', secondaryKey);
    hmac2.update(payload);
    hmac2.update(timestamp);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import hmac
    import hashlib

    primary_key = '...'
    secondary_key = '...'

    payload = "{\"type\":\"webhook_event\"...}"

    bytes = bytes(payload, 'utf-8') + bytes(timestamp, 'utf-8')

    hmac1 = hmac.new(primary_key, bytes, hashlib.sha256).digest()
    hmac2 = hmac.new(secondary_key, bytes, hashlib.sha256).digest()
    ```
  </Tab>
</Tabs>

### Base64 Conversion

Convert the HMAC to a `Base64` encoded digest.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    var digest1 = hmac1.digest('base64');
    var digest2 = hmac2.digest('base64');
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import base64

    digest1 = base64.b64encode(hmac1)
    digest2 = base64.b64encode(hmac2)
    ```
  </Tab>
</Tabs>

### Signature comparison

Compare the encoded digest with the value of the
`BOX-SIGNATURE-PRIMARY` or `BOX-SIGNATURE-SECONDARY` headers.

Compare the value of the `BOX-SIGNATURE-PRIMARY` header
to the digest created with the primary key, and the value of the
`BOX-SIGNATURE-SECONDARY` header to the digest created with the secondary key.
Make sure to use a timing-safe comparison between signatures to prevent timing attacks.

<Tabs>
  <Tab title="Node">
    ```js theme={null}
    const crypto = require('crypto');

    function compareSignatures(expectedSignature, receivedSignature) {
        const expectedBuffer = Buffer.from(expectedSignature, 'base64');
        const receivedBuffer = Buffer.from(receivedSignature, 'base64');

        if (expectedBuffer.length !== receivedBuffer.length) {
            return false;
        }

        return crypto.timingSafeEqual(expectedBuffer, receivedBuffer);
    }

    const signature1 = headers['BOX-SIGNATURE-SECONDARY'];
    const signature2 = headers['BOX-SIGNATURE-PRIMARY'];

    const primarySignatureValid = compareSignatures(digest1, signature1)
    const secondarySignatureValid = compareSignatures(digest2, signature2)

    const valid = !expired && (primarySignatureValid || secondarySignatureValid)
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import hmac

    def compare_signatures(expected_signature: Optional[str], received_signature: Optional[str]) -> bool:
        if not expected_signature or not received_signature:
            return False
        if len(expected_signature) != len(received_signature):
            return False
        return hmac.compare_digest(expected_signature, received_signature)

    signature1 = headers["BOX-SIGNATURE-SECONDARY"]
    signature2 = headers["BOX-SIGNATURE-PRIMARY"]

    primary_sig_valid = compare_signatures(digest1, signature1)
    secondary_sig_valid = compare_signatures(digest2, signature2)

    valid = not expired and (primary_sig_valid or secondary_sig_valid)
    ```
  </Tab>
</Tabs>

<Warning>
  HTTP header names are case insensitive. Your client should convert
  all header names to a standardized lowercase or uppercase format before trying
  to determine the value of a header.
</Warning>

## Rotate signatures

When enabled, Box sends two signatures with every webhook payload.
Your application can trust a payload as long as at least one of its signatures
is valid. When updating one signature key at a time your application will always
receive a payload with at least one valid signature.

### Rotation steps

These instructions assume that you have already created a primary and secondary
key in the [Developer Console][console] and you are ready to replace either of
them.

By following these steps you can configure your application with two new keys
without any conflicts.

1. Go to the **Webhooks** tab in the [Developer Console][console].
2. Click the **Manage signature keys**.
3. Click the **Reset** button to change the primary key.
4. Update your application with the new primary key. Your application can still receive notifications with the old primary key, but your webhooks should be processed correctly since the secondary key is still valid.
5. Once you are confident that no webhooks with the old primary key are in-flight, you can update the secondary key using the same process.

[console]: https://app.box.com/developers/console

<RelatedLinks title="RELATED APIS" />


# Update Webhooks
Source: https://developer.box.com/guides/webhooks/v2/update-v2



<RelatedLinks title="REQUIRED GUIDES" />

You can update a webhook using the [Developer Console][console] or API.

## Developer Console

To update a webhook in the [Developer Console][console], follow the steps below.

1. Go to the **Webhooks** tab in the [Developer Console][console] to display all webhooks.
2. Select the webhook you want to update by clicking on its ID.
3. Click the **Edit webhook** button.
4. Fill in the data you want to update.
5. Click the **Update** button to save your changes.

<Note>
  The list of webhooks contains the following fields:
  **ID**, **Address**, **Content**, **Created by**,
  and **Created date**.
</Note>

## API

To update a webhook, use the <Link href="/reference/put-webhooks-id">update webhook</Link> endpoint,
which requires the webhook ID. To find the ID of the webhook, use the
<Link href="/guides/webhooks/v2/list-v2">list all webhooks</Link> endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/webhooks/3321123" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -H "content-type: application/json" \
       -d '{
         "triggers": [
           "FILE.DOWNLOADED"
         ]
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.webhooks.updateWebhookById(webhook.id!, {
    requestBody: {
      address: 'https://example.com/updated-webhook',
    } satisfies UpdateWebhookByIdRequestBody,
  } satisfies UpdateWebhookByIdOptionalsInput);
  ```

  ```python Python v10 theme={null}
  client.webhooks.update_webhook_by_id(
      webhook.id, address="https://example.com/updated-webhook"
  )
  ```

  ```csharp .NET v10 theme={null}
  await client.Webhooks.UpdateWebhookByIdAsync(webhookId: NullableUtils.Unwrap(webhook.Id), requestBody: new UpdateWebhookByIdRequestBody() { Address = "https://example.com/updated-webhook" });
  ```

  ```swift Swift v10 theme={null}
  try await client.webhooks.updateWebhookById(webhookId: webhook.id!, requestBody: UpdateWebhookByIdRequestBody(address: "https://example.com/updated-webhook"))
  ```

  ```java Java v10 theme={null}
  client.getWebhooks().updateWebhookById(webhook.getId(), new UpdateWebhookByIdRequestBody.Builder().address("https://example.com/updated-webhook").build())
  ```

  ```java Java v5 theme={null}
  BoxWebHook webhook = new BoxWebHook(api, id);
  BoxWebHook.Info info = webhook.new Info();
  info.setAddress(url);
  webhook.update(info);
  ```

  ```py Python v4 theme={null}
  update_object = {
      'triggers': ['FILE.COPIED'],
      'address': 'https://newexample.com',
  }
  webhook = client.webhook(webhook_id='12345').update_info(data=update_object)
  print(f'Updated the webhook info for triggers: {webhook.triggers} and address: {webhook.address}')
  ```

  ```csharp .NET v6 theme={null}
  var updates = new BoxWebhookRequest()
  {
      Id = "12345",
      Address = "https://example.com/webhooks/fileActions
  };
  BoxWebhook updatedWebhook = await client.WebhooksManager.UpdateWebhookAsync(updates);
  ```

  ```js Node v4 theme={null}
  client.webhooks.update('678901', {address: "https://example.com/webhooks/fileActions"})
   .then(webhook => {
    /* webhook -> {
     id: '1234',
     type: 'webhook',
     target: { id: '22222', type: 'folder' },
     created_by: 
     { type: 'user',
      id: '33333',
      name: 'Example User',
      login: 'user@example.com' },
     created_at: '2016-05-09T17:41:27-07:00',
     address: 'https://example.com/webhooks/fileActions',
     triggers: [ 'FILE.DOWNLOADED', 'FILE.UPLOADED' ] }
    */
   });
  ```
</CodeGroup>

[console]: https://app.box.com/developers/console

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box AI API agent configurator
Source: https://developer.box.com/agent-configurator

Configure Box AI API agents with a visual configurator. Choose from multiple AI models from leading providers, all accessible through a single, easy-to-use platform. Fine-tune Box AI API and LLM parameters, then export a ready-to-use JSON configuration for your Box AI API requests.

<FeatureTilesEN />

<AIAgentConfig />


# Box Agent Skills
Source: https://developer.box.com/ai/agent-skills



Agent Skills are pre-built instruction sets that teach AI coding assistants how to perform
specific tasks. Box Agent Skills give your AI assistant the context
it needs to build Box integrations, work with Box content via MCP tools, configure
webhooks, and use Box AI retrieval. No manual configuration is required.

The skills follow the [Agent Skills](https://agentskills.io/) open standard and
can be installed as a plugin for [ChatGPT/Codex](https://chatgpt.com/plugins/plugin_asdk_app_695bfc98071c8191bac7bc479aa27de7),
[Cursor](https://cursor.com/dashboard/plugins?plugin-id=1092), or [Claude/Claude Code](https://claude.ai/directory/plugins/box%40knowledge-work-plugins). To get access to the full plugin with all the skills, ensure that you are logged in to the selected AI tool.

For detailed reference material, additional examples, and contributing guidelines,
see the [box-for-ai repository](https://github.com/box/box-for-ai) on GitHub.

<SignupCTA>
  A free developer account gives you access to the Box AI API, Developer Console, and everything you need to start building AI-powered workflows.
</SignupCTA>

## Install

<Note>
  Running `npx skills add` prompts you to install the `skills` package if
  not already present. Confirm the installation when prompted to continue.
</Note>

<Tabs>
  <Tab title="Agent Skills">
    Run this in your project directory (or from any directory for a user-level
    install) to add all Box Agent Skills:

    ```bash theme={null}
    npx skills add box/skills
    ```

    To browse the full list of available skills, see the [Box skills registry](https://skills.sh/box/skills).
  </Tab>

  <Tab title="Codex plugin">
    Box Agent Skills can also be installed as a Codex plugin. See the
    [Codex setup guide](https://github.com/box/box-for-ai/blob/main/.codex-plugin/README.md)
    for configuration instructions, including how to connect the Box MCP server.
  </Tab>

  <Tab title="Cursor plugin">
    Box Agent Skills can also be installed as a Cursor plugin. See the
    [Cursor setup guide](https://github.com/box/box-for-ai/blob/main/.cursor-plugin/README.md)
    for configuration instructions, including how to connect the Box MCP server.
  </Tab>

  <Tab title="Claude Code plugin">
    For Claude Code, install Box Agent Skills as a platform plugin. See the
    [Claude Code setup guide](https://github.com/box/box-for-ai/blob/main/.claude-plugin/README.md)
    for configuration instructions.
  </Tab>
</Tabs>

<Tip>
  To verify that your Box account is connected after installation, run
  `box users:get me --json` in the <Link href="/guides/cli">Box CLI</Link>.
  A successful response confirms your authentication is working.
</Tip>

## Usage

Skills are loaded automatically when your assistant detects a relevant task.
Ask your assistant to perform Box-related tasks in natural language and it will
select the appropriate skill.

<AccordionGroup>
  <Accordion title="Add file uploads, shared links, and webhooks">
    | What to prompt | What happens |
    | - | - |
    | "Add Box file upload to my app" | Scaffolds file upload integration using the Box SDK. |
    | "Create a shared link for this folder" | Generates code to create and configure shared links. |
    | "Set up Box webhooks for new file events" | Sets up webhook listeners for file creation events. |
  </Accordion>

  <Accordion title="Search, classify, and process documents">
    | What to prompt | What happens |
    | - | - |
    | "Search my Box account for invoices" | Uses the Box Search API to find matching files. |
    | "Use Box AI to classify documents" | Implements document classification with the Box AI API. |
    | "Wire webhooks to process new uploads" | Connects webhook events to document processing logic. |
  </Accordion>

  <Accordion title="Automate multi-step file processing">
    | What to prompt | What happens |
    | - | - |
    | "Extract invoice numbers and totals from these PDFs, and put them in a table" | Locates the PDFs, runs Box AI extraction on each, and formats results into a structured table. |
    | "Organize the files in this folder by type. Classify with Box AI and move into subfolders" | Inventories the folder, classifies files using Box AI, creates target subfolders, and moves files serially. |
    | "Build a search-first retrieval flow for invoice lookup that only downloads files when needed" | Searches Box with filters first, then retrieves content only for the matching shortlist. |
  </Accordion>

  <Accordion title="Troubleshoot integrations">
    | What to prompt | What happens |
    | - | - |
    | "Debug 401 errors with my Box JWT auth" | Walks through JWT authentication troubleshooting. |
    | "Fix webhook signature verification" | Diagnoses and resolves webhook signature issues. |
  </Accordion>
</AccordionGroup>

## Skill structure

Box Agent Skills follow the [Agent Skills open standard](https://agentskills.io/).
Each skill is a directory containing instruction files and supporting resources.

```text theme={null}
box/
  SKILL.md          # Skill manifest with frontmatter, routing table, workflow steps, and guardrails
  references/       # Feature-specific deep dives (auth, content workflows, MCP, AI/retrieval, etc.)
  examples/         # Example prompts
```

<Tip>
  Skills are concise by design. They use tables instead of prose and focus on the
  information an AI assistant needs to generate accurate code.
</Tip>


# Box AI API
Source: https://developer.box.com/ai/box-ai-api

Ask questions, extract metadata, generate text, and summarize files in Box with the Box AI API.

The Box AI API summarizes your
content, answers questions, generates text, and extracts structured metadata
through a single API. The API is available to all Box customers on Business plans and above.

<SignupCTA>
  A free developer account gives you access to the Box AI API. See the benefits of document
  summarization, question answering, and metadata extraction for yourself.
</SignupCTA>

## Capabilities

| Capability | Description | Endpoint |
| - | - | - |
| **Ask questions** | Get answers about document content or an entire [Box Hub](/guides/hubs-api/index) | <Link href="/reference/post-ai-ask">`POST /ai/ask`</Link> |
| **Generate text** | Create drafts, templates, and content from prompts | <Link href="/reference/post-ai-text-gen">`POST /ai/text_gen`</Link> |
| **Extract metadata** | Pull key-value pairs from unstructured documents using natural language prompts | <Link href="/reference/post-ai-extract">`POST /ai/extract`</Link> |
| **Extract structured metadata** | Extract data using metadata templates or field definitions | <Link href="/reference/post-ai-extract-structured">`POST /ai/extract_structured`</Link> |

## Quick starts

Get up and running with Box AI in minutes.

<CardGroup>
  <Card title="Summarize documents" href={localizeLink("/guides/box-ai/quick-start/box-ai-summarize")} icon="sparkles">
    Summarize document content using Box AI and the Python SDK.
  </Card>

  <Card title="Extract structured data" href={localizeLink("/guides/box-ai/quick-start/box-ai-extract")} icon="sparkles">
    Use metadata templates to extract structured data from documents.
  </Card>

  <Card title="Freeform extraction" href={localizeLink("/guides/box-ai/quick-start/box-ai-extract-freeform")} icon="sparkles">
    Extract data using natural language prompts or stringified data structures.
  </Card>

  <Card title="Enhanced Extract Agent" href={localizeLink("/guides/box-ai/quick-start/box-ai-extract-enhanced")} icon="sparkles">
    Use advanced reasoning models to extract data from complex documents.
  </Card>
</CardGroup>

## API reference

<CardGroup>
  <Card title="Ask" href={localizeLink("/reference/post-ai-ask")} icon="code">
    `POST /ai/ask`
  </Card>

  <Card title="Text generation" href={localizeLink("/reference/post-ai-text-gen")} icon="code">
    `POST /ai/text_gen`
  </Card>

  <Card title="Extract" href={localizeLink("/reference/post-ai-extract")} icon="code">
    `POST /ai/extract`
  </Card>

  <Card title="Extract structured" href={localizeLink("/reference/post-ai-extract-structured")} icon="code">
    `POST /ai/extract_structured`
  </Card>

  <Card title="Get AI agent config" href={localizeLink("/reference/get-ai-agent-default")} icon="code">
    `GET /ai/agent_default`
  </Card>

  <Card title="AI response schemas" href={localizeLink("/reference/resources/ai-response/")} icon="code">
    Response objects
  </Card>
</CardGroup>


# AI integrations
Source: https://developer.box.com/ai/integrations

Connect Box to LangChain, LlamaIndex, Pinecone, Weaviate, and other AI frameworks. Use Box Hubs and Box AI Ask for permission-aware RAG.

Connect Box content to the AI tools and frameworks your team already uses.
Build retrieval-augmented generation pipelines, power vector search, feed
data into analytics, and extend AI agent capabilities.

Start with [Box-managed retrieval](/ai/rag) (Hubs and Box AI Ask) when the
documents already live in Box and answers must respect Box permissions.
Use the loaders and vector databases below when you need a custom index.

<SignupCTA>
  A free developer account gives you access to the Box AI API and everything
  you need to build AI-powered workflows with these integrations.
</SignupCTA>

## Agent frameworks

Build AI agents that interact with Box content.

<CardGroup>
  <Card title="Box AI Agents Toolkit" href="https://pypi.org/project/box-ai-agents-toolkit/" icon="toolbox">
    A Python library for building AI agents that interact with Box. Provides
    authentication, content interaction, and more.
  </Card>

  <Card title="Pydantic AI" href="https://github.com/box-community/box-mcp-pydantic-ai" icon="link">
    Build AI agents using the Pydantic AI framework with the Box MCP server.
  </Card>
</CardGroup>

## RAG frameworks

Include Box content in retrieval-augmented generation pipelines. These
loaders copy file text into your index. After that, Box no longer
enforces who can open each file. Unless you filter results, a query can return content the current user cannot access in Box. See
[keep an exported index permission-aware](/ai/rag#keep-an-exported-index-permission-aware).

<CardGroup>
  <Card title="LangChain" href="https://python.langchain.com/docs/integrations/providers/box/" icon="link">
    Include Box content in your AI
    workflows.
  </Card>

  <Card title="LangChain.js" href="https://www.npmjs.com/package/langchainjs-box" icon="link">
    Use the Box loader for LangChain.js in JavaScript-based AI workflows.
  </Card>

  <Card title="LlamaIndex" href="https://github.com/run-llama/llama_index/tree/main/llama-index-integrations/readers/llama-index-readers-box#readme" icon="link">
    Ingest Box content into LlamaIndex retrieval pipelines.
  </Card>
</CardGroup>

## Vector databases

Connect Box content to vector databases for semantic search and similarity
matching.

<CardGroup>
  <Card title="Pinecone" href={localizeLink("/ai/vector-databases/pinecone")} icon="database">
    Connect Box content to Pinecone for vector search workflows.
  </Card>

  <Card title="Weaviate" href={localizeLink("/ai/vector-databases/weaviate")} icon="database">
    Build RAG workflows with Box content and the Weaviate vector database.
  </Card>
</CardGroup>

## Enterprise platforms

Connect Box to enterprise platforms for agent-based and data workflows.

<CardGroup>
  <Card title="Box for Agentforce" href={localizeLink("/guides/tooling/salesforce-toolkit/box-agentforce-package/")} icon="robot">
    Extend Box for Salesforce with reusable Agentforce actions that automate
    workflows and enhance agent-based processes.
  </Card>

  <Card title="Snowflake Openflow" href="https://docs.snowflake.com/en/user-guide/data-integration/openflow/connectors/box/setup" icon="link">
    Integrate Box with Snowflake using the Openflow Connector.
  </Card>

  <Card title="Airbyte" href="https://github.com/box-community/airbyte/blob/barduinor/source-box-devrel/docs/integrations/sources/box-data-extract.md" icon="link">
    Extract Box data using the Airbyte source connector for data pipelines.
  </Card>
</CardGroup>

## Learning resources

Tutorials and walkthroughs for building AI-powered workflows with Box.

<CardGroup>
  <Card title="Build AI Apps with MCP Servers" href="https://www.deeplearning.ai/short-courses/build-ai-apps-with-mcp-server-working-with-box-files/" icon="graduation-cap">
    Online course from DeepLearning.AI on building AI applications with MCP
    servers and Box files.
  </Card>

  <Card title="Multi-agent workflows with OpenAI" href="https://medium.com/box-developer-blog/building-multi-agent-workflows-with-openais-new-sdk-and-box-3e3c81cf4715" icon="link">
    Build multi-agent workflows using the OpenAI SDK and Box.
  </Card>

  <Card title="LangChain MCP Adapters" href="https://medium.com/box-developer-blog/using-an-existing-mcp-server-with-langchain-mcp-adapters-94cdd4af6d1b" icon="link">
    Use the Box MCP server with LangChain MCP Adapters for agent
    orchestration.
  </Card>

  <Card title="Document generation with Box MCP" href="https://medium.com/box-developer-blog/building-ai-powered-document-generation-with-box-mcp-and-pydantic-ai-48775b18ae32" icon="link">
    Build AI-powered document generation with the Box MCP server and Pydantic
    AI.
  </Card>
</CardGroup>


# Build RAG over enterprise documents stored in Box
Source: https://developer.box.com/ai/rag

Build retrieval-augmented generation (RAG) over documents in Box. Start with Box Hubs and Box AI Ask for permission-aware answers. Export to Pinecone or Weaviate, or use LangChain, when you need a custom retrieval stack.

Start with **Box-managed retrieval**: add files to a <Link href="/guides/hubs-api">Box Hub</Link> and call <Link href="/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub">Box AI Ask</Link>. Box retrieves content, grounds the answer, and checks the requesting user's permissions. You do not operate your own embedding pipeline or vector database for that path.

Build your own pipeline (chunk, embed, store, generate) only when Box-managed retrieval does not cover your use case.

<SignupCTA>
  A free developer account gives you access to the Box AI API, Hubs, and the content APIs you need to test both paths.
</SignupCTA>

## Which approach to use

| If you need… | Do this |
| - | - |
| Answers on documents already in Box, with citations and the same permissions as the web app | Hub + <Link href="/reference/post-ai-ask">`POST /2.0/ai/ask`</Link> |
| A governed knowledge base (staging, approval, then query) | <Link href="/guides/hubs-api/access-controlled-knowledge-base">Access-controlled AI knowledge base</Link> |
| An index that mixes Box with other sources, a custom embedding model, or custom chunking and ranking | Export Box content to LangChain, LlamaIndex, Pinecone, or Weaviate. Enforce permissions in your retrieval layer |

## Box-managed retrieval

Box AI Ask with a hub as the item:

* Indexes hub content. No vector store to host.
* Returns answers only from files the calling user or app can access.
* Includes citations to source files.
* Stays current as files and hub items change. No re-index job to run.

For a full walkthrough, see <Link href="/guides/hubs-api/access-controlled-knowledge-base">Access-controlled AI knowledge base</Link>. For working apps, see the <Link href="/tutorials/sales-rfp-answer-bank">RFP answer bank</Link> and <Link href="/tutorials/company-brain">company brain</Link> tutorials.

## Your own RAG pipeline

Export from Box when you need:

* A retrieval engine or embedding model Box AI does not offer.
* A single index that combines Box documents with other sources.
* Custom chunking, ranking, or evaluation.
* Model hosting you control.

Typical flow:

1. Choose folders or files the application can read. Do not index the enterprise root.
2. Pull text with Box representations or your own parsers. See the <Link href="/ai/vector-databases/pinecone">Pinecone</Link> and <Link href="/ai/vector-databases/weaviate">Weaviate</Link> tutorials.
3. Chunk text, generate embeddings, and store vectors with Box file IDs and permission metadata.
4. At query time, embed the question, search the index, then drop chunks the current user cannot access in Box.
5. Send the question plus allowed chunks to an LLM. Cite Box file IDs in the answer.

Framework loaders: <Link href="/ai/integrations">LangChain, LangChain.js, and LlamaIndex</Link>.

## Keep an exported index permission-aware

Box does not enforce permissions inside Pinecone, Weaviate, or your LLM prompt. After you copy text out of Box, your service is responsible for access control.

At a minimum:

* Store the Box file ID and version ID on every vector.
* Before returning results, check the querying user's Box permissions. Drop chunks from files the user cannot open.
* Refresh the index when files, collaborations, or sharing change. Use <Link href="/guides/events">events</Link> or <Link href="/guides/webhooks">webhooks</Link>, not a one-time crawl.
* Re-check access at query time even if you cached permissions at index time. Sharing changes faster than most batch jobs.

If your main requirement is permission-aware answers and the content is already in Box, use hubs and Ask instead. See <Link href="/guides/getting-started/why-box#box-managed-retrieval-or-your-own-rag-pipeline">Box-managed retrieval or your own RAG pipeline</Link>.

<RelatedLinks title="RELATED GUIDES" />


# Box and Pinecone
Source: https://developer.box.com/ai/vector-databases/pinecone

Build a RAG pipeline by connecting Box content to Pinecone for vector search and question answering.

This tutorial walks you through building a retrieval-augmented generation
(RAG) pipeline using [Pinecone](https://www.pinecone.io/) as a vector
database. You will create vector embeddings from files
stored in Box, store them in Pinecone, and query them through a large
language model (LLM) to answer questions about your content.

<SignupCTA>
  A free developer account gives you access to the Box API and everything
  you need to build AI-powered workflows with Pinecone.
</SignupCTA>

## RAG concept overview

### What is a vector database?

Pinecone is a managed, cloud-native
[vector database](https://www.pinecone.io/learn/vector-database/). A vector
database stores and retrieves representations of your data, called
embeddings, so you can find results that are similar in meaning rather
than literally identical. This is the foundation of semantic search.

### What are embeddings?

Embeddings are a mathematical representation of the meaning of your content.
They are generated by taking input data, splitting (or chunking) it, and
using an embedding model to produce a sequence of floating-point values —
for example, `[0.3, 0.4, 0.1, 1.8, 1.1, ...]`.

You can think of these values as mapping concepts to points in a
high-dimensional space. Similar concepts cluster together: "cat" is close
to "kitten," while "banana" and "dog" are far apart. Different embedding
models are trained on different data and may be specialized for specific
use cases.

### How does RAG work with Box and Pinecone?

In a typical RAG workflow:

* **Indexing**: Content from a Box folder is extracted, chunked, and
  converted into embeddings using an embedding model. These embeddings are
  stored in Pinecone along with metadata such as the file name and a
  reference back to the source file in Box.

* **Retrieval**: When a user asks a question, the question is converted
  into embeddings using the same model. Pinecone's query functionality
  retrieves the content chunks most relevant to the question.

* **Generation**: The original question and the retrieved content chunks
  are combined into a prompt and sent to an LLM, which generates an answer
  grounded in your Box content.

The LLM doesn't have direct access to your Box files. RAG bridges that gap
by providing the relevant context so the model can generate accurate answers
based on your data.

<Warning>
  Pinecone does not enforce Box permissions. After you embed file text, your
  application has to filter retrieval for the querying user, store Box file IDs
  on every vector, and re-index when files, versions, or collaborations change.
  If you only need permission-aware answers over Box content, use
  <Link href="/guides/hubs-api/access-controlled-knowledge-base">Hubs and Box AI Ask</Link>
  instead. See <Link href="/ai/rag">Build RAG over enterprise documents stored in Box</Link>.
</Warning>

## Prerequisites

Before you begin, make sure you have the following:

* A **Box folder** with files you want to query. The folder must be
  accessible by the user account that creates the Box application. Note the
  folder ID from the URL bar. You will need it later.
* A **Pinecone account**.
  [Sign up for a free starter plan](https://docs.pinecone.io/guides/get-started/quickstart)
  and generate an API key.
* For the purpose of this tutorial, an **OpenAI account**. This can be substituted for any other LLM.
  [Sign up for OpenAI](https://platform.openai.com/docs/quickstart) and
  generate an API key. You may need to attach billing information.
* [Python](https://www.python.org/downloads/) installed on your machine.

## Create a Box custom application

Create an OAuth application in the
[Box Developer Console](https://cloud.app.box.com/developers/console):

1. Click **New App** in the top right corner.
2. Enter an app name and select **OAuth 2.0** as the authentication method.
3. Click **Create App**.
4. Scroll down to **Redirect URIs** and add:
   `http://127.0.0.1:5000/callback`
5. Check all boxes under **Application Scopes**.
6. Click **Save Changes**.

Note the **Client ID** and **Client Secret**. You will need these for the
configuration file.

## Create a Pinecone index

1. Log in to the [Pinecone Console](https://app.pinecone.io/).
2. Click **Create Index**.
3. Give the index a name (for example, `pinecone-demo`).
4. Set the **Dimensions** field to `1024`.
5. Leave all other settings at their defaults and click **Create Index**.

<Frame>
  <img alt="Create a Pinecone index" />
</Frame>

Note the index name. You will add it to the configuration file.

<Frame>
  <img alt="Pinecone index screen" />
</Frame>

<Tip>
  You can also create an index programmatically via the
  [Pinecone API](https://docs.pinecone.io/reference/api/latest/control-plane/create_index).
</Tip>

## Initialize the code repository

Clone the [sample code](https://github.com/box-community/box-pinecone-sample)
to your local machine:

```bash theme={null}
git clone https://github.com/box-community/box-pinecone-sample.git
cd box-pinecone-sample
```

Create and activate a virtual environment:

```bash theme={null}
python3 -m venv venv
source venv/bin/activate
```

Install the dependencies:

```bash theme={null}
pip install -r requirements.txt
```

Copy the sample configuration file and update it with your credentials:

```bash theme={null}
cp sample_config.py config.py
```

Open `config.py` in your editor and fill in:

* Your Box **Client ID** and **Client Secret**
* Your **Box folder ID**
* Your **Pinecone API key** and **index name**
* Your **OpenAI API key**

<Frame>
  <img alt="Configuration file" />
</Frame>

<Warning>
  Do **not** set the folder ID to `0`. This would attempt to index your entire
  Box account, which is not recommended. It would exceed rate limits, consume
  significant resources, and likely fail to complete.
</Warning>

## Create and store embeddings

With the configuration complete, run the main script to create embeddings
from your Box content:

```bash theme={null}
python main.py
```

The first time you run the application, a browser window opens asking you to
grant access. This is the standard OAuth 2.0 authorization flow. Click
**Grant Access to Box**.

<Note>
  The OAuth tokens are stored in a `.oauth.json` file in the project
  directory. The refresh token remains valid for 60 days of inactivity.
</Note>

The script processes each file in the specified Box folder, extracts its
<Link href="/guides/representations/text">text representation</Link>,
chunks it, generates embeddings using the
[Pinecone Inference API](https://docs.pinecone.io/reference/api/latest/inference/generate-embeddings),
and stores them in Pinecone. Metadata, including a reference back to the
source file in Box, is attached to each vector.

Once complete, you can view the embeddings in the Pinecone Console along
with the associated metadata (file name, plain text of the chunk, and more).
This metadata is useful for filtering responses and managing document
versions.

<Frame>
  <img alt="Embeddings in Pinecone Console" />
</Frame>

## Query the LLM

With the embeddings stored, you can ask questions about your Box content.
This part of the project uses OpenAI as the LLM provider.

Run the query script:

```bash theme={null}
python query.py
```

Enter a question at the prompt. The script converts your question to an
embedding, retrieves the most relevant content chunks from Pinecone, and
sends them along with your question to OpenAI to generate an answer.

<Frame>
  <img alt="Query answer from the service" />
</Frame>

## Enhancement ideas

<AccordionGroup>
  <Accordion title="Keep the index permission-aware">
    Store the Box file ID on every vector. At query time, drop chunks from
    files the current user cannot open in Box. Subscribe to
    <Link href="/guides/events">events</Link> or
    <Link href="/guides/webhooks">webhooks</Link> so you re-embed on upload,
    version change, move, delete, and collaboration updates. Cached
    permission metadata goes stale; re-check access when you retrieve.
  </Accordion>

  <Accordion title="Automate indexing with events">
    The sample runs indexing on demand. You could create a scheduled task or
    an event-driven service using
    <Link href="/guides/events">Box events</Link> that triggers when files
    in the Box folder change. The script uses upserts, so re-running it
    updates existing records.
  </Accordion>

  <Accordion title="Add a user interface">
    The query script runs via the command line. You could build a web UI for
    a more user-friendly question-and-answer experience.
  </Accordion>

  <Accordion title="Use different authentication methods">
    The demo uses OAuth 2.0. You could integrate
    <Link href="/guides/authentication/jwt">JWT</Link> or
    <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>
    authentication for server-to-server use cases.
  </Accordion>

  <Accordion title="Swap models or configuration">
    The embeddings use the Pinecone Inference API, and the query script
    uses OpenAI. You can substitute different embedding models, LLM
    providers, vector dimensions, distance metrics, and chunk sizes to fit
    your use case.
  </Accordion>

  <Accordion title="Expand file type support">
    The script processes files that have a
    <Link href="/guides/representations/text">text representation</Link>
    in Box (automatically created for supported file types under 500 MB).
    You could add third-party libraries to handle additional content types
    or larger files.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup>
  <Card title="Sample code" href="https://github.com/box-community/box-pinecone-sample" icon="github">
    Clone the Box + Pinecone sample repository on GitHub.
  </Card>

  <Card title="Pinecone documentation" href="https://www.pinecone.io/learn/vector-database/" icon="database">
    Learn more about vector databases and how Pinecone works.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED RESOURCES" />


# Box and Weaviate
Source: https://developer.box.com/ai/vector-databases/weaviate

Build an end-to-end RAG workflow by embedding Box content into Weaviate and querying it with the Weaviate Query Agent.

This tutorial walks you through building a retrieval-augmented generation
(RAG) workflow by embedding Box content into a
[Weaviate](https://weaviate.io/) vector database and using Weaviate's
[Query Agent](https://weaviate.io/blog/weaviate-agents) to answer questions
about your data.

The complete recipe is available as a Jupyter Notebook in the
[Weaviate recipes repository](https://github.com/weaviate/recipes/tree/main/integrations/data-platforms/box).

<SignupCTA>
  A free developer account gives you access to the Box API and everything
  you need to build AI-powered workflows with Weaviate.
</SignupCTA>

## Overview

### What is Weaviate?

[Weaviate](https://weaviate.io/) is an open-source vector database built for
speed, scale, and AI-driven search. It stores data as objects and vectors,
letting you combine semantic search via embeddings with structured filtering.
Weaviate is cloud native, fault tolerant, and integrates directly with large
language models (LLMs).

### How Box and Weaviate create an end-to-end RAG solution

RAG is a technique that pairs vector search (retrieval) with a language model
(generation) to answer questions using your own data. The flow works as
follows:

* **Content storage**: Box holds your files (PDFs, docs, text reports,
  and other supported formats).
* **Embedding creation**: Text is extracted from your Box files, chunked,
  and converted into vector embeddings using
  [Weaviate Embeddings](https://weaviate.io/developers/wcs/embeddings).
* **Querying**: Weaviate's Query Agent takes a natural language question,
  generates the necessary search and aggregation queries, and returns a
  single answer — all using agentic RAG.

<Warning>
  Weaviate does not enforce Box permissions. After you embed file text, your
  application has to filter retrieval for the querying user, store Box file IDs
  on every object, and re-index when files, versions, or collaborations change.
  If you only need permission-aware answers over Box content, use
  [Hubs and Box AI Ask](/guides/hubs-api/access-controlled-knowledge-base)
  instead. See [Build RAG over enterprise documents stored in Box](/ai/rag).
</Warning>

## Prerequisites

Before you begin, make sure you have the following:

* A Box developer account. If you don't already have one,
  [sign up for a free developer account](https://account.box.com/signup/developer).
* A Jupyter Notebook environment such as
  [Visual Studio Code](https://code.visualstudio.com/docs/datascience/jupyter-notebooks)
  with the Jupyter extension, or a local Jupyter installation.
* A Weaviate Cloud account.
  [Sign up for a free sandbox tier](https://console.weaviate.cloud/).

## Get a Box developer token

1. Click **New App** in the top right corner.
2. Enter an app name and select **OAuth 2.0** as the authentication method.
3. Click **Create App**.
4. Under **Application Scopes**, add read/write scopes for files if not already enabled, then
   click **Save Changes**.
5. From the **Configuration** tab, copy and save the developer token. You will need it for the notebook.

<Note>
  Developer tokens are valid for 60 minutes. If your session takes longer,
  you will need to generate a new token.
</Note>

## Create a Weaviate cluster

1. Log in to [Weaviate Cloud](https://console.weaviate.cloud/).
2. Create a new cluster from the dashboard. You can name it whatever you
   like.
3. Once the cluster is ready, go to the **Details** tab and note the
   **cluster URL** and **API key**.

## Run the recipe

### Clone the repository

Clone or download the
[Weaviate recipes repository](https://github.com/weaviate/recipes):

```bash theme={null}
git clone https://github.com/weaviate/recipes.git
```

Navigate to the Box integration folder:

```bash theme={null}
cd recipes/integrations/data-platforms/box
```

Open the Jupyter Notebook (`weaviate_box.ipynb`) in your development
environment.

<Frame>
  <img alt="Weaviate recipes repository structure" />
</Frame>

### Configure authentication

The notebook includes a step to set authentication variables. Update the
code block in **step 3** with:

* Your **Box developer token**
* Your **Weaviate cluster URL** and **API key**

<Frame>
  <img alt="Authentication variables in the notebook" />
</Frame>

### Run the notebook

Execute each cell in the notebook sequentially. The notebook:

1. Uploads demo files to Box (or uses files you provide).
2. Extracts text content from the Box files.
3. Chunks the text and creates vector embeddings in Weaviate.
4. Uses the Weaviate Query Agent to answer questions about the content.

<Tip>
  The repository includes a `demo_files` folder with four 10-K financial
  reports for testing. You can replace these with your own files if you prefer
  to work with different content.
</Tip>

The final cell demonstrates querying your data. You can modify the query in
**step 7** to ask different questions based on your content.

<Frame>
  <img alt="Final answer from the Weaviate Query Agent" />
</Frame>

## Next steps

<AccordionGroup>
  <Accordion title="Keep the index permission-aware">
    Store the Box file ID on every Weaviate object. At query time, drop
    results from files the current user cannot open in Box. Re-run embedding
    when files change, and when collaborations change, using
    [events](/guides/events) or [webhooks](/guides/webhooks).
  </Accordion>

  <Accordion title="Expand your data">
    Upload additional files to Box such as annual reports, articles, or any
    documents you want to search, and rerun the notebook to embed them in
    Weaviate.
  </Accordion>

  <Accordion title="Customize the Query Agent">
    Adjust the `system_prompt` parameter to change the agent's behavior.
    For example, you can request more detailed analysis or a specific
    response format.
  </Accordion>

  <Accordion title="Explore other Weaviate agents">
    Weaviate offers additional agent types. The
    [Transformation Agent](https://docs.weaviate.io/agents#transformation-agent) can
    preprocess your data, and the
    [Personalization Agent](https://docs.weaviate.io/agents#personalization-agent) can
    tailor responses to individual users.
  </Accordion>
</AccordionGroup>

## Resources

<CardGroup>
  <Card title="Weaviate recipe" href="https://github.com/weaviate/recipes/tree/main/integrations/data-platforms/box" icon="github">
    The complete Jupyter Notebook in the Weaviate recipes repository.
  </Card>

  <Card title="Weaviate Query Agent" href="https://weaviate.io/blog/weaviate-agents" icon="robot">
    Learn about Weaviate's agentic RAG capabilities.
  </Card>

  <Card title="Weaviate Embeddings" href="https://weaviate.io/developers/wcs/embeddings" icon="brain">
    Documentation for Weaviate's embedding service.
  </Card>

  <Card title="Box Developer Community" href="https://community.box.com/box-platform-5" icon="comments">
    Share feedback and get support from other Box developers.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED RESOURCES" />


# Create agents
Source: https://developer.box.com/guides/ai-studio/ai-studio-agents/create-agents

Create a custom AI agent using the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

The `POST /2.0/ai_agents` endpoint creates a new custom <Link href="/guides/box-ai/ai-agents/index">AI agent</Link> with configurable capabilities for asking questions, generating text, or extracting metadata.

## Before you start

Make sure you have completed the steps in <Link href="/guides/ai-studio/getting-started-ai-studio">Getting started with AI Studio</Link> to create a platform app and generate a developer token.

## Send a request

<CodeGroup>
  ```typescript Node/TypeScript v10 theme={null}
  await client.aiStudio.createAiAgent({
    name: agentName,
    accessState: 'enabled',
    ask: new AiStudioAgentAsk({ accessState: 'enabled', description: 'desc1' }),
  } satisfies CreateAiAgentInput);
  ```

  ```python Python v10 theme={null}
  client.ai_studio.create_ai_agent(
      agent_name,
      "enabled",
      ask=AiStudioAgentAsk(access_state="enabled", description="desc1"),
  )
  ```

  ```cs .NET v10 theme={null}
  await client.AiStudio.CreateAiAgentAsync(requestBody: new CreateAiAgent(name: agentName, accessState: "enabled") { Ask = new AiStudioAgentAsk(accessState: "enabled", description: "desc1") });
  ```

  ```swift Swift v10 theme={null}
  try await client.aiStudio.createAiAgent(requestBody: CreateAiAgent(name: agentName, accessState: "enabled", ask: AiStudioAgentAsk(accessState: "enabled", description: "desc1")))
  ```

  ```java Java v10 theme={null}
  client.getAiStudio().createAiAgent(new CreateAiAgent.Builder(agentName, "enabled").ask(new AiStudioAgentAsk("enabled", "desc1")).build())
  ```
</CodeGroup>

### Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

| Parameter | Description | Example |
| - | - | - |
| **`type`** | The type of agent used to handle queries. | `ai_agent` |
| **`name`** | The name of the AI Agent. | `My AI Agent` |
| **`access_state`** | The state of the AI Agent. Value is one of `enabled` `disabled`. | `enabled` |
| `icon_reference` | The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name>`, where the possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`, `logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png` `logo_analytics.png`,`logo_classification.png`. | `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg` |
| `allowed_entities` | List of allowed users or groups. | |
| `ask` | The AI Agent to be used for ask. | `ask` |
| `extract` | The AI Agent to be used for extraction. | |
| `text_gen` | The AI agent used for generating text. | |

<RelatedLinks title="RELATED GUIDES" />


# Delete AI agents
Source: https://developer.box.com/guides/ai-studio/ai-studio-agents/delete-agents

Permanently delete a custom AI agent using the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

The `DELETE /2.0/ai_agents/{id}` endpoint permanently removes a custom AI agent. This action cannot be undone.

## Before you start

Make sure you have completed the steps in <Link href="/guides/ai-studio/getting-started-ai-studio">Getting started with AI Studio</Link> to create a platform app and generate a developer token.

## Send a request

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X DELETE "https://api.box.com/2.0/ai_agents/12345" \
        -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.aiStudio.deleteAiAgentById(createdAgent.id);
  ```

  ```python Python v10 theme={null}
  client.ai_studio.delete_ai_agent_by_id(created_agent.id)
  ```

  ```cs .NET v10 theme={null}
  await client.AiStudio.DeleteAiAgentByIdAsync(agentId: createdAgent.Id);
  ```

  ```swift Swift v10 theme={null}
  try await client.aiStudio.deleteAiAgentById(agentId: createdAgent.id)
  ```

  ```java Java v10 theme={null}
  client.getAiStudio().deleteAiAgentById(createdAgent.getId())
  ```
</CodeGroup>

### Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

| Parameter | Description | Example |
| - | - | - |
| **`agent_id`** | The ID of the agent to delete. | `1234` |

<RelatedLinks title="RELATED GUIDES" />


# Get AI agent by ID
Source: https://developer.box.com/guides/ai-studio/ai-studio-agents/get-agent-id

Retrieve a specific AI agent's configuration using the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

The `GET /2.0/ai_agents/{id}` endpoint returns the configuration for a specific AI agent.

## Before you start

Make sure you have completed the steps in <Link href="/guides/ai-studio/getting-started-ai-studio">Getting started with AI Studio</Link> to create a platform app and generate a developer token.

## Send a request

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/ai_agents/1234567890" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.aiStudio.getAiAgentById(createdAgent.id, {
    queryParams: { fields: ['ask'] } satisfies GetAiAgentByIdQueryParams,
  } satisfies GetAiAgentByIdOptionalsInput);
  ```

  ```python Python v10 theme={null}
  client.ai_studio.get_ai_agent_by_id(created_agent.id, fields=["ask"])
  ```

  ```cs .NET v10 theme={null}
  await client.AiStudio.GetAiAgentByIdAsync(agentId: createdAgent.Id, queryParams: new GetAiAgentByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"ask"}) });
  ```

  ```swift Swift v10 theme={null}
  try await client.aiStudio.getAiAgentById(agentId: createdAgent.id, queryParams: GetAiAgentByIdQueryParams(fields: ["ask"]))
  ```

  ```java Java v10 theme={null}
  client.getAiStudio().getAiAgentById(createdAgent.getId(), new GetAiAgentByIdQueryParams.Builder().fields(Arrays.asList("ask")).build())
  ```
</CodeGroup>

### Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

| Parameter | Description | Example |
| - | - | - |
| **`agent_id`** | The agent id to get. | `1234` |
| `fields` | The fields to return in the response. | `ask` |

<RelatedLinks title="RELATED GUIDES" />


# List agents
Source: https://developer.box.com/guides/ai-studio/ai-studio-agents/get-agents

List all AI agents in your enterprise using the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

The `GET /2.0/ai_agents` endpoint lists all AI agents in your enterprise, with optional filters for mode, state, and fields.

## Before you start

Make sure you have completed the steps in <Link href="/guides/ai-studio/getting-started-ai-studio">Getting started with AI Studio</Link> to create a platform app and generate a developer token.

## Send a request

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X GET "https://api.box.com/2.0/ai_agents" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.aiStudio.getAiAgents();
  ```

  ```python Python v10 theme={null}
  client.ai_studio.get_ai_agents()
  ```

  ```csharp .NET v10 theme={null}
  await client.AiStudio.GetAiAgentsAsync();
  ```

  ```swift Swift v10 theme={null}
  try await client.aiStudio.getAiAgents()
  ```

  ```java Java v10 theme={null}
  client.getAiStudio().getAiAgents()
  ```
</CodeGroup>

### Parameters

To make a call, you can pass the following parameters.

| Parameter | Description | Example |
| - | - | - |
| `mode` | The mode to filter the agent configuration to return. Possible values are: `ask`, `text_gen`, and `extract`. | `ask` |
| `fields` | The fields to return in the response. Value is one of `ask`, `text_gen`, `extract`. | `ask` |
| `agent_state` | The state of the agent to return. Value is one of `enabled`, `disabled`. | `enabled` |
| `include_box_default` | Whether to include the Box default agents in the response. | `true` |
| `limit` | The maximum number of items to return per page. | `1000` |
| `marker` | Defines the position marker at which to begin returning results. | `JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii` |

<RelatedLinks title="RELATED GUIDES" />


# AI Studio agents
Source: https://developer.box.com/guides/ai-studio/ai-studio-agents/index

Create, list, update, and delete custom AI agents through the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

The AI Studio API provides full CRUD operations for managing custom AI agents. Each agent can be configured with specific capabilities (`ask`, `text_gen`, `extract`), access controls, and custom instructions.

<CardGroup>
  <Card title="Create an agent" icon="plus" href={localizeLink("/guides/ai-studio/ai-studio-agents/create-agents")}>
    `POST /2.0/ai_agents`: define a new agent with capabilities, access state, and allowed entities.
  </Card>

  <Card title="List all agents" icon="list" href={localizeLink("/guides/ai-studio/ai-studio-agents/get-agents")}>
    `GET /2.0/ai_agents`: retrieve agents filtered by mode, state, or fields.
  </Card>

  <Card title="Get agent by ID" icon="magnifying-glass" href={localizeLink("/guides/ai-studio/ai-studio-agents/get-agent-id")}>
    `GET /2.0/ai_agents/{id}`: fetch a specific agent's configuration.
  </Card>

  <Card title="Update an agent" icon="pen-to-square" href={localizeLink("/guides/ai-studio/ai-studio-agents/update-agents")}>
    `PUT /2.0/ai_agents/{id}`: modify an agent's name, state, or capabilities.
  </Card>

  <Card title="Delete an agent" icon="trash" href={localizeLink("/guides/ai-studio/ai-studio-agents/delete-agents")}>
    `DELETE /2.0/ai_agents/{id}`: permanently remove an agent.
  </Card>
</CardGroup>


# Update AI agents
Source: https://developer.box.com/guides/ai-studio/ai-studio-agents/update-agents

Update a custom AI agent's configuration using the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

The `PUT /2.0/ai_agents/{id}` endpoint updates a custom AI agent's name, state, capabilities, or access controls.

## Before you start

Make sure you have completed the steps in <Link href="/guides/ai-studio/getting-started-ai-studio">Getting started with AI Studio</Link> to create a platform app and generate a developer token.

## Send a request

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -X PUT "https://api.box.com/2.0/ai_agents/1234567890" \
       -H "authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.aiStudio.updateAiAgentById(createdAgent.id, {
    name: agentName,
    accessState: 'enabled',
    ask: new AiStudioAgentAsk({ accessState: 'disabled', description: 'desc2' }),
  } satisfies CreateAiAgentInput);
  ```

  ```python Python v10 theme={null}
  client.ai_studio.update_ai_agent_by_id(
      created_agent.id,
      agent_name,
      "enabled",
      ask=AiStudioAgentAsk(access_state="disabled", description="desc2"),
  )
  ```

  ```cs .NET v10 theme={null}
  await client.AiStudio.UpdateAiAgentByIdAsync(agentId: createdAgent.Id, requestBody: new CreateAiAgent(name: agentName, accessState: "enabled") { Ask = new AiStudioAgentAsk(accessState: "disabled", description: "desc2") });
  ```

  ```swift Swift v10 theme={null}
  try await client.aiStudio.updateAiAgentById(agentId: createdAgent.id, requestBody: CreateAiAgent(name: agentName, accessState: "enabled", ask: AiStudioAgentAsk(accessState: "disabled", description: "desc2")))
  ```

  ```java Java v10 theme={null}
  client.getAiStudio().updateAiAgentById(createdAgent.getId(), new CreateAiAgent.Builder(agentName, "enabled").ask(new AiStudioAgentAsk("disabled", "desc2")).build())
  ```
</CodeGroup>

### Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

| Parameter | Description | Example |
| - | - | - |
| **`type`** | The type of agent used to handle queries. | `ai_agent` |
| **`name`** | The name of the AI Agent. | My AI Agent |
| **`access_state`** | The state of the AI Agent. Value is one of `enabled` `disabled`. | `enabled` |
| `icon_reference` | The icon reference of the AI Agent. It should have format of the URL `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/<file_name>`, where possible values of `file_name` are: `logo_boxAi.png`,`logo_stamp.png`,`logo_legal.png`,`logo_finance.png`,`logo_config.png`,`logo_handshake.png`,`logo_analytics.png`,`logo_classification.png` | `https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg` |
| `allowed_entities` | List of allowed users or groups. | |
| `ask` | The AI Agent to be used for ask. | `ask` |
| `extract` | The AI Agent to be used for extraction. | |
| `text_gen` | The AI agent used for generating text. | |

<RelatedLinks title="RELATED GUIDES" />


# Get started with AI Studio
Source: https://developer.box.com/guides/ai-studio/getting-started-ai-studio

Set up a platform app and authenticate to start creating custom AI agents with the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

To create custom AI agents with AI Studio, you need a platform application with the Box AI scope enabled and a token to authenticate your API calls.

<Note>
  The setup steps below are similar to the <Link href="/guides/box-ai/ai-tutorials/prerequisites">Box AI API prerequisites</Link>. If you have already completed those steps, confirm that the **Manage AI** scope is enabled and that your admin has enabled AI Studio, then skip ahead to [next steps](#next-steps).
</Note>

<Steps>
  <Step title="Create a platform application">
    Create a platform application to make API calls. Follow the guide on <Link href="/guides/applications/platform-apps/create">creating platform apps</Link>.
  </Step>

  <Step title="Enable AI Studio">
    Ask a Box admin to enable AI Studio in the Admin Console. For admin instructions, see [Enabling Box AI Studio and Managing Agents][enable].
  </Step>

  <Step title="Add the AI scope">
    To interact with the Box AI API, add the `ai.readwrite` <Link href="/guides/api-calls/permissions-and-errors/scopes">scope</Link> to your application.

    1. Open your application in the Developer Console.
    2. Go to **Configuration** > **Required Access Scopes** > **Content Actions**.
    3. Select **Manage AI**.

    <Frame>
      <img alt="box ai scopes" />
    </Frame>

    <Note>
      If you do not see the **Manage AI** option, contact your admin to grant access to the Box AI API.
      If you see the scope checked and grayed out, the app owner has it enabled but you cannot change the setting.
    </Note>
  </Step>

  <Step title="Authorize the application">
    Submit your app for <Link href="/guides/authorization">authorization or enablement</Link>. If you are enabling Box AI for an existing application, you must <Link href="/guides/authorization/platform-app-approval#re-authorization-on-changes">re-authorize</Link> it.
  </Step>

  <Step title="Generate a developer token">
    Generate a developer token to authenticate your requests.

    1. Go to **Developer Console** > **My Platform Apps**.
    2. Hover over a platform app and select the **Options menu** button (...) on the right.
    3. Select **Generate Developer Token**. The token is automatically copied to your clipboard.

    <Warning>
      A developer token is only valid for one hour. In production, use your app's configured authentication method (for example, <Link href="/guides/authentication/oauth2">OAuth 2.0</Link> or <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>).
    </Warning>

    For more details, see <Link href="/guides/authentication/tokens/developer-tokens">developer tokens</Link>.
  </Step>
</Steps>

## Next steps

With your application configured and a token generated, you can start creating custom AI agents. Use cURL, Postman, or any of the <Link href="/sdks-and-tools">Box SDKs</Link> to make API calls.

<CardGroup>
  <Card title="Create an agent" icon="robot" href={localizeLink("/guides/ai-studio/ai-studio-agents/create-agents")}>
    Define a custom AI agent with specific capabilities and access controls.
  </Card>

  <Card title="List agents" icon="list" href={localizeLink("/guides/ai-studio/ai-studio-agents/get-agents")}>
    Retrieve all AI agents in your enterprise.
  </Card>
</CardGroup>

[enable]: https://support.box.com/hc/en-us/articles/37228079461267-Enabling-Box-AI-Studio-and-Managing-Agents/#h_01JH9HAMP43YYN6VWM51QCK413


# Box AI Studio
Source: https://developer.box.com/guides/ai-studio/index

Create, manage, and deploy custom AI agents through the Box AI Studio API.

<Warning>
  Box AI Studio is available only for Enterprise Advanced accounts.
</Warning>

Box AI Studio lets you create custom AI agents through the API. Unlike the standard <Link href="/ai/box-ai-api">Box AI API</Link> endpoints that use Box's default agent configurations, AI Studio agents let you define purpose-built agents with custom instructions, model selections, and access controls.

For example, you can create an agent that acts as a compliance consultant -- answering questions about customer documentation with FedRAMP Moderate compliance in mind -- and restricts access to specific users or groups.

## Enabling Box AI Studio

Enable Box AI Studio in the Admin Console to start creating agents. For admin instructions, see <Link href="https://support.box.com/hc/en-us/articles/37228079461267-Enabling-Box-AI-Studio-and-Managing-Agents">Enabling Box AI Studio and Managing Agents</Link>.

Step-by-step instructions are available in the <Link href="/guides/ai-studio/getting-started-ai-studio">Get started with AI Studio</Link> guide.

## How Box AI Studio relates to Box AI

| Feature | Box AI API | Box AI Studio |
| - | - | - |
| **Use case** | Provides endpoints for Q\&A, text generation, and metadata extraction against files in Box | Lets you create and manage custom AI agents with tailored behavior |
| **Customization** | Override model and prompt per-request using the `ai_agent` parameter | Define persistent agent configurations with custom instructions, models, and access controls |
| **Access** | Business plans and above | Enterprise Advanced only |
| **API endpoints** | `POST /ai/ask`, `POST /ai/text_gen`, `POST /ai/extract`, `POST /ai/extract_structured` | `POST /ai_agents`, `GET /ai_agents`, `GET /ai_agents/{id}`, `PUT /ai_agents/{id}`, `DELETE /ai_agents/{id}` |

## Capabilities

You can configure AI Studio agents for the following modes:

| Mode | Parameter | Description |
| - | - | - |
| **Ask** | `ask` | Answer user questions about documents |
| **Text generation** | `text_gen` | Generate text based on file content and prompts |
| **Extraction** | `extract` | Extract metadata from documents |

<Frame>
  <img alt="ai agent capabilities" />
</Frame>

## Get started

<CardGroup>
  <Card title="Set up AI Studio" icon="gear" href={localizeLink("/guides/ai-studio/getting-started-ai-studio")}>
    Create a platform app, enable the AI scope, and generate credentials to
    start making AI Studio API calls.
  </Card>

  <Card title="Create an agent" icon="robot" href={localizeLink("/guides/ai-studio/ai-studio-agents/create-agents")}>
    Use `POST /ai_agents` to create a custom AI agent with specific
    capabilities and access controls.
  </Card>

  <Card title="List agents" icon="list" href={localizeLink("/guides/ai-studio/ai-studio-agents/get-agents")}>
    Retrieve all AI agents in your enterprise, filtered by mode or state.
  </Card>

  <Card title="Manage agents" icon="wrench" href={localizeLink("/guides/ai-studio/ai-studio-agents/index")}>
    Get, update, and delete agents by ID.
  </Card>
</CardGroup>

For admin setup instructions, see [Enabling Box AI Studio and Managing Agents][ai-studio].

[ai-studio]: https://support.box.com/hc/en-us/articles/37228079461267-Enabling-Box-AI-Studio-and-Managing-Agents


# AI model configuration override reference
Source: https://developer.box.com/guides/box-ai/ai-agents/ai-agent-overrides

Full ai_agent parameter reference with sample configurations and parameter details.

The `ai_agent` configuration allows you to override the default AI model configuration. It is available for the following endpoints:

* <Link href="/reference/post-ai-ask#param-ai-agent">`POST ai/ask`</Link>
* <Link href="/reference/post-ai-text-gen#param-ai-agent">`POST ai/text_gen`</Link>
* <Link href="/reference/post-ai-extract#param-ai-agent">`POST ai/extract`</Link>
* <Link href="/reference/post-ai-extract-structured#param-ai-agent">`POST ai/extract_structured`</Link>

<Tip>
  Use the <Link href="/reference/get-ai-agent-default">`GET ai_agent_default`</Link> endpoint to fetch the default configuration before applying overrides.
</Tip>

The override examples include:

* Replacing the default AI model with a custom one based on your organization's needs.
* Tweaking the base `prompt` to allow a more customized user experience.
* Changing a parameter, such as `temperature`, to make the results more or less creative.

## Sample configuration

A complete configuration for `ai/ask` is as follows:

```sh theme={null}
{
  "type": "ai_agent_ask",
  "basic_text": {
    "llm_endpoint_params": {
      "type": "openai_params",
      "frequency_penalty": 1.5,
      "presence_penalty": 1.5,
      "stop": "<|im_end|>",
      "temperature": 0,
      "top_p": 1
    },
    "model": "openai__gpt_5_mini",
    "num_tokens_for_completion": 8400,
    "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
    "system_message": "You are a helpful travel assistant specialized in budget travel"
  },
  "basic_text_multi": {
    "llm_endpoint_params": {
      "type": "openai_params",
      "frequency_penalty": 1.5,
      "presence_penalty": 1.5,
      "stop": "<|im_end|>",
      "temperature": 0,
      "top_p": 1
    },
    "model": "openai__gpt_5_mini",
    "num_tokens_for_completion": 8400,
    "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
    "system_message": "You are a helpful travel assistant specialized in budget travel"
  },
  "long_text": {
    "embeddings": {
      "model": "openai__text_embedding_ada_002",
      "strategy": {
        "id": "basic",
        "num_tokens_per_chunk": 64
      }
    },
    "llm_endpoint_params": {
      "type": "openai_params",
      "frequency_penalty": 1.5,
      "presence_penalty": 1.5,
      "stop": "<|im_end|>",
      "temperature": 0,
      "top_p": 1
    },
    "model": "openai__gpt_5_mini",
    "num_tokens_for_completion": 8400,
    "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
    "system_message": "You are a helpful travel assistant specialized in budget travel"
  },
  "long_text_multi": {
    "embeddings": {
      "model": "openai__text_embedding_ada_002",
      "strategy": {
        "id": "basic",
        "num_tokens_per_chunk": 64
      }
    },
    "llm_endpoint_params": {
      "type": "openai_params",
      "frequency_penalty": 1.5,
      "presence_penalty": 1.5,
      "stop": "<|im_end|>",
      "temperature": 0,
      "top_p": 1
    },
    "model": "openai__gpt_5_mini",
    "num_tokens_for_completion": 8400,
    "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
    "system_message": "You are a helpful travel assistant specialized in budget travel"
  }
}
```

### Differences in parameter sets

The set of parameters available for `ask`, `text_gen`, `extract`, `extract_structured` differs slightly, depending on the API call.

* The agent configuration for the `ask` endpoint includes `basic_text`, `basic_text_multi`, `long_text` and `long_text_multi` parameters. This is because of the `mode` parameter you use to specify if the request is for a single item or multiple items. If you selected `multiple_item_qa` as the `mode`, you can also use `multi` parameters for overrides.

* The agent configuration for `text_gen` includes the `basic_gen` parameter
  that is used to generate text.

### LLM endpoint params

The `llm_endpoint_params` configuration options differ depending on the overall AI model being <Link href="/reference/resources/ai-llm-endpoint-params-google">Google</Link>, <Link href="/reference/resources/ai-llm-endpoint-params-openai">OpenAI</Link> or <Link href="/reference/resources/ai-llm-endpoint-params-aws">AWS</Link> based.

For example, both `llm_endpoint_params` objects accept a `temperature` parameter, but the outcome differs depending on the model.

For Google and AWS models, the [`temperature`][google-temp] is used for sampling during response generation, which occurs when `top-P` and `top-K` are applied. Temperature controls the degree of randomness in the token selection.

For OpenAI models, [`temperature`][openai-temp] is the sampling temperature with values between 0 and 2. Higher values like 0.8 make the output more random, while lower values like 0.2 make it more focused and deterministic. When introducing your own configuration, use `temperature` or `top_p` but not both.

### System message

The `system_message` parameter's aim is to help the LLM understand its role and what it’s supposed to do.
For example, if your solution is processing travel itineraries, you can add a system message saying:

```sh theme={null}
You are a travel agent aid. You are going to help support staff process large amounts of schedules, tickets, etc.
```

This message is separate from the content you send in, but it can improve the results.

### Number of tokens for completion

The `num_tokens_for_completion` parameter represents the number of [tokens][openai-tokens] Box AI can return. This number can vary based on the model used.

[openai-tokens]: https://help.openai.com/en/articles/4936856-what-are-tokens-and-how-to-count-them

[google-temp]: https://ai.google.dev/gemini-api/docs/models/generative-models#model-parameters

[openai-temp]: https://community.openai.com/t/temperature-top-p-and-top-k-for-chatbot-responses/295542

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# AI agent configuration versioning
Source: https://developer.box.com/guides/box-ai/ai-agents/ai-agent-versioning

See how Box versions AI agent snapshots, the 12-month support guarantee, and transition timelines.

<Note>
  Box updates the default models across the endpoints on a regular basis in order to stay up to date with the most advanced options. If a default model is updated, it will be posted in the developer changelog.
</Note>

AI agent configuration versioning gives the developers more control over AI agent versioning and ensures consistent responses.

AI agent configuration versioning adopts the following principles:

* Each AI agent snapshot is supported for at least 12 months, unless there are factors outside of Box's control. For example, a Large Language Model (LLM) may get deprecated.
* An AI agent snapshot is available unless a new, stable agent version is released.
* A 6-month window is provided to test and transition to the new snapshot.

## Historical AI agent configuration

The values in the <Link href="/guides/box-ai/ai-agents/get-agent-default-config">default agent configuration</Link> used by the LLM gateway often change to achieve the best possible answer quality.

To make sure your configurations are not affected in a negative way, you can use the historical AI agent configuration provided below to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default one</Link>.

``````json theme={null}
{
    "ask": {
        "type": "ai_agent_ask",
        "longText": {
            "model": "openai__gpt_5_mini",
            "systemMessage": "",
            "promptTemplate": "Reply as if it's {current_date}.\nI will ask you for help and provide subsections of one document delimited by five backticks (`````) at the beginning and at the end.\nIf I make a reference to \"this\", I am referring to the document I provided between the five backticks. I may ask you a question where the answer is contained within the document.  In that case, do your best to answer using only the document, but if you cannot, feel free to mention that you couldn't find an answer in the document, but you have some answer from your general knowledge.\nI may ask you to perform some kind of computation or symbol manipulation such as filtering a list, counting something, summing, averaging, and other aggregation/grouping functions or some combination of them.  In these cases, first list the plan of how you plan to perform such a computation, then follow that plan step by step, keeping track of intermediate results, and at the end tell me the final answer.\nI may ask you to enumerate or somehow list people, places, characters, or other important things from the document, if I do so, please only use the document provided to list them.\nTEXT FROM DOCUMENT STARTS\n`````\n{content}\n`````\nTEXT FROM DOCUMENT ENDS\nNever mention five backticks in your response. Unless you are told otherwise, a one paragraph response is sufficient for any requested summarization tasks.\nHere is how I need help from you: {user_question}",
            "numTokensForCompletion": 6000,
            "llmEndpointParams": {
                "type": "openai_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 1.5,
                "stop": "<|im_end|>"
            },
            "embeddings": {
                "model": "azure__openai__text_embedding_ada_002",
                "strategy": {
                    "id": "basic",
                    "numTokensPerChunk": 64
                }
            }
        },
        "basicText": {
            "model": "openai__gpt_5_mini",
            "systemMessage": "",
            "promptTemplate": "Reply as if it's {current_date}.\nI will ask you for help and provide the entire text of one document delimited by five backticks (`````) at the beginning and at the end.\nIf I make a reference to \"this\", I am referring to the document I provided between the five backticks. I may ask you a question where the answer is contained within the document.  In that case, do your best to answer using only the document, but if you cannot, feel free to mention that you couldn't find an answer in the document, but you have some answer from your general knowledge.\nI may ask you to perform some kind of computation or symbol manipulation such as filtering a list, counting something, summing, averaging, and other aggregation/grouping functions or some combination of them.  In these cases, first list the plan of how you plan to perform such a computation, then follow that plan step by step, keeping track of intermediate results, and at the end tell me the final answer.\nI may ask you to enumerate or somehow list people, places, characters, or other important things from the document, if I do so, please only use the document provided to list them.\nTEXT FROM DOCUMENT STARTS\n`````\n{content}\n`````\nTEXT FROM DOCUMENT ENDS\nNever mention five backticks in your response. Unless you are told otherwise, a one paragraph response is sufficient for any requested summarization tasks.\nHere is how I need help from you: {user_question}",
            "numTokensForCompletion": 6000,
            "llmEndpointParams": {
                "type": "openai_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 1.5,
                "stop": "<|im_end|>"
            }
        },
        "longTextMulti": {
            "model": "openai__gpt_5_mini",
            "systemMessage": "Role and Goal: You are an assistant designed to analyze and answer a question based on provided snippets from multiple documents, which can include business-oriented documents like docs, presentations, PDFs, etc. The assistant will respond concisely, using only the information from the provided documents.\n\nConstraints: The assistant should avoid engaging in chatty or extensive conversational interactions and focus on providing direct answers. It should also avoid making assumptions or inferences not supported by the provided document snippets.\n\nGuidelines: When answering, the assistant should consider the file's name and path to assess relevance to the question. In cases of conflicting information from multiple documents, it should list the different answers with citations. For summarization or comparison tasks, it should concisely answer with the key points. It should also consider the current date to be the date given.\n\nPersonalization: The assistant's tone should be formal and to-the-point, suitable for handling business-related documents and queries.\n",
            "promptTemplate": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.",
            "numTokensForCompletion": 6000,
            "llmEndpointParams": {
                "type": "openai_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 1.5,
                "stop": "<|im_end|>"
            },
            "embeddings": {
                "model": "azure__openai__text_embedding_ada_002",
                "strategy": {
                    "id": "basic",
                    "numTokensPerChunk": 64
                }
            }
        },
        "basicTextMulti": {
            "model": "openai__gpt_5_mini",
            "systemMessage": "",
            "promptTemplate": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.",
            "numTokensForCompletion": 6000,
            "llmEndpointParams": {
                "type": "openai_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 1.5,
                "stop": "<|im_end|>"
            }
        },
    },
    "extract": {
        "type": "ai_agent_extract",
        "longText": {
            "model": "google__gemini_1_5_flash_001",
            "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
            "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
            "numTokensForCompletion": 4096,
            "llmEndpointParams": {
                "type": "google_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 0.0
            },
            "embeddings": {
                "model": "azure__openai__text_embedding_ada_002",
                "strategy": {
                    "id": "basic",
                    "numTokensPerChunk": 64
                }
            }
        },
        "basicText": {
            "model": "google__gemini_1_5_flash_001",
            "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
            "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
            "numTokensForCompletion": 4096,
            "llmEndpointParams": {
                "type": "google_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 0.0
            }
        }
    },
    "textGen": {
        "type": "ai_agent_text_gen",
        "basicGen": {
            "model": "openai__gpt_5_mini",
            "systemMessage": "\nIf you need to know today's date to respond, it is {current_date}.\nThe user is working in a collaborative document creation editor called Box Notes.\nAssume that you are helping a business user create documents or to help the user revise existing text.\nYou can help the user in creating templates to be reused or update existing documents, you can respond with text that the user can use to place in the document that the user is editing.\nIf the user simply asks to \"improve\" the text, then simplify the language and remove jargon, unless the user specifies otherwise.\nDo not open with a preamble to the response, just respond.\n",
            "promptTemplate": "{user_question}",
            "numTokensForCompletion": 12000,
            "llmEndpointParams": {
                "type": "openai_params",
                "temperature": 0.1,
                "topP": 1.0,
                "frequencyPenalty": 0.75,
                "presencePenalty": 0.75,
                "stop": "<|im_end|>"
            },
            "embeddings": {
                "model": "azure__openai__text_embedding_ada_002",
                "strategy": {
                    "id": "basic",
                    "numTokensPerChunk": 64
                }
            },
            "contentTemplate": "`````{content}`````"
        }
    },
    "extractStructured": {
        "type": "ai_agent_extract_structured",
        "longText": {
            "model": "google__gemini_1_5_flash_001",
            "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
            "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
            "numTokensForCompletion": 4096,
            "llmEndpointParams": {
                "type": "google_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 0.0
            },
            "embeddings": {
                "model": "google__textembedding_gecko_003",
                "strategy": {
                    "id": "basic",
                    "numTokensPerChunk": 64
                }
            }
        },
        "basicText": {
            "model": "google__gemini_1_5_flash_001",
            "systemMessage": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
            "promptTemplate": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
            "numTokensForCompletion": 4096,
            "llmEndpointParams": {
                "type": "google_params",
                "temperature": 0.0,
                "topP": 1.0,
                "frequencyPenalty": 0.0,
                "presencePenalty": 0.0
            }
        }
    }
}
``````

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Get default AI agent configuration
Source: https://developer.box.com/guides/box-ai/ai-agents/get-agent-default-config

Fetch the current default agent configuration for ask, text_gen, extract, and extract_structured modes.

The `GET /2.0/ai_agent_default` endpoint allows you to fetch the default configuration for AI services.
Once you get the configuration details you can override them using the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">`ai_agent`</Link> parameter.

## Send a request

To send a request, use the
`GET /2.0/ai_agent_default` endpoint.

Make sure you have generated the developer token
to authorize your app. See <Link href="/guides/box-ai/ai-tutorials/prerequisites">getting started with Box AI</Link>
for details.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X GET "https://api.box.com/2.0/ai_agent_default?mode=text_gen" \
       -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.ai.getAiAgentDefaultConfig({
    mode: 'ask' as GetAiAgentDefaultConfigQueryParamsModeField,
    language: 'en-US',
  } satisfies GetAiAgentDefaultConfigQueryParams);
  ```

  ```python Python v10 theme={null}
  client.ai.get_ai_agent_default_config(GetAiAgentDefaultConfigMode.ASK, language="en-US")
  ```

  ```cs .NET v10 theme={null}
  await client.Ai.GetAiAgentDefaultConfigAsync(queryParams: new GetAiAgentDefaultConfigQueryParams(mode: GetAiAgentDefaultConfigQueryParamsModeField.Ask) { Language = "en-US" });
  ```

  ```swift Swift v10 theme={null}
  try await client.ai.getAiAgentDefaultConfig(queryParams: GetAiAgentDefaultConfigQueryParams(mode: GetAiAgentDefaultConfigQueryParamsModeField.ask, language: "en-US"))
  ```

  ```java Java v10 theme={null}
  client.getAi().getAiAgentDefaultConfig(new GetAiAgentDefaultConfigQueryParams.Builder(GetAiAgentDefaultConfigQueryParamsModeField.ASK).language("en-US").build())
  ```

  ```java Java v5 theme={null}
  BoxAIAgentConfig config = BoxAI.getAiAgentDefaultConfig(
      api,
      BoxAIAgent.Mode.ASK,
      "en",
      "openai__gpt_3_5_turbo"
  );
  ```

  ```python Python v4 theme={null}
  config = client.get_ai_agent_default_config(
      mode='text_gen',
      language='en',
      model='openai__gpt_3_5_turbo'
  )
  print(config)
  ```

  ```javascript Node v4 theme={null}
  client.ai.getAiAgentDefaultConfig({
      mode: 'ask',
      language: 'en',
      model:'openai__gpt_3_5_turbo'
  }).then(response => {
      /* response -> {
          "type": "ai_agent_ask",
          "basic_text": {
              "llm_endpoint_params": {
              "type": "openai_params",
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>",
              "temperature": 0,
              "top_p": 1
              },
              "model": "openai__gpt_3_5_turbo",
              "num_tokens_for_completion": 8400,
              "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. What should I see?",
              "system_message": "You are a helpful travel assistant specialized in budget travel"
          },
          ...
      } */
  });
  ```
</CodeGroup>

### Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

| Parameter | Description | Example |
| - | - | - |
| `language` | The language code the agent configuration is returned for. If the language is not supported, the default configuration is returned. | `ja-JP` |
| **`mode`** | The mode used to filter the agent configuration. The value can be `ask`, `text_gen`, `extract`, or `extract_structured` depending on the result you want to achieve. | `ask` |
| `model` | The model you want to get the configuration for. To make sure your chosen model is supported, see the <Link href="/guides/box-ai/ai-models">list of models</Link>. | `openai__gpt_5_mini` |

## Responses

The responses to the call may vary depending on the `mode` parameter value you choose.

<Tabs>
  <Tab title="Ask">
    When you set the `mode` parameter to `ask` the response will be as follows:

    ```sh theme={null}
    {
         "type": "ai_agent_ask",
         "basic_text": {
              "model": "openai__gpt_5_mini",
              "system_message": "",
              "prompt_template": "prompt_template": "{user_question}Write it in an informal way.{content}"
            },
              "num_tokens_for_completion": 6000,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "frequency_penalty": 0,
                   "presence_penalty": 1.5,
                   "stop": "<|im_end|>",
                   "type": "openai_params"
              }
         },
         "long_text": {
              "model": "openai__gpt_5_mini",
              "system_message": "",
              "prompt_template": "prompt_template": "{user_question}Write it in an informal way.{content}"
            },
              "num_tokens_for_completion": 6000,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "frequency_penalty": 0,
                   "presence_penalty": 1.5,
                   "stop": "<|im_end|>",
                   "type": "openai_params"
              },
              "embeddings": {
                   "model": "azure__openai__text_embedding_ada_002",
                   "strategy": {
                        "id": "basic",
                        "num_tokens_per_chunk": 64
                   }
              }
         },
         "basic_text_multi": {
              "model": "openai__gpt_5_mini",
              "system_message": "",
              "prompt_template": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.",
              "num_tokens_for_completion": 6000,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "frequency_penalty": 0,
                   "presence_penalty": 1.5,
                   "stop": "<|im_end|>",
                   "type": "openai_params"
              }
         },
         "long_text_multi": {
              "model": "openai__gpt_5_mini",
              "system_message": "Role and Goal: You are an assistant designed to analyze and answer a question based on provided snippets from multiple documents, which can include business-oriented documents like docs, presentations, PDFs, etc. The assistant will respond concisely, using only the information from the provided documents.\n\nConstraints: The assistant should avoid engaging in chatty or extensive conversational interactions and focus on providing direct answers. It should also avoid making assumptions or inferences not supported by the provided document snippets.\n\nGuidelines: When answering, the assistant should consider the file's name and path to assess relevance to the question. In cases of conflicting information from multiple documents, it should list the different answers with citations. For summarization or comparison tasks, it should concisely answer with the key points. It should also consider the current date to be the date given.\n\nPersonalization: The assistant's tone should be formal and to-the-point, suitable for handling business-related documents and queries.\n",
              "prompt_template": "Current date: {current_date}\n\nTEXT FROM DOCUMENTS STARTS\n{content}\nTEXT FROM DOCUMENTS ENDS\n\nHere is how I need help from you: {user_question}\n.",
              "num_tokens_for_completion": 6000,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "frequency_penalty": 0,
                   "presence_penalty": 1.5,
                   "stop": "<|im_end|>",
                   "type": "openai_params"
              },
              "embeddings": {
                   "model": "azure__openai__text_embedding_ada_002",
                   "strategy": {
                        "id": "basic",
                        "num_tokens_per_chunk": 64
                   }
              }
         }
    }
    ```
  </Tab>

  <Tab title="Text gen">
    When you set the `mode` parameter to `text_gen` the response will be as follows:

    ``````sh theme={null}
    {
         "type": "ai_agent_text_gen",
         "basic_gen": {
              "model": "openai__gpt_5_mini",
              "system_message": "\nIf you need to know today's date to respond, it is {current_date}.\nThe user is working in a collaborative document creation editor called Box Notes.\nAssume that you are helping a business user create documents or to help the user revise existing text.\nYou can help the user in creating templates to be reused or update existing documents, you can respond with text that the user can use to place in the document that the user is editing.\nIf the user simply asks to \"improve\" the text, then simplify the language and remove jargon, unless the user specifies otherwise.\nDo not open with a preamble to the response, just respond.\n",
              "prompt_template": "{user_question}",
              "num_tokens_for_completion": 12000,
              "llm_endpoint_params": {
                   "temperature": 0.1,
                   "top_p": 1,
                   "frequency_penalty": 0.75,
                   "presence_penalty": 0.75,
                   "stop": "<|im_end|>",
                   "type": "openai_params"
              },
              "embeddings": {
                   "model": "azure__openai__text_embedding_ada_002",
                   "strategy": {
                        "id": "basic",
                        "num_tokens_per_chunk": 64
                   }
              },
              "content_template": "`````{content}`````"
         }
    }
    ``````
  </Tab>

  <Tab title="Extract">
    When you set the `mode` parameter to `extract` the response will be as follows:

    `````sh theme={null}
    {
         "type": "ai_agent_extract",
         "basic_text": {
              "model": "google__gemini_1_5_flash_001",
              "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
              "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
              "num_tokens_for_completion": 4096,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "top_k": null,
                   "type": "google_params"
              }
         },
         "long_text": {
              "model": "google__gemini_1_5_flash_001",
              "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"displayName\": \"key display name\", \"type\": \"string\", \"description\": \"key description\"}]}. Leverage key description and key display name to identify where the key and value pairs are in the document. In certain cases, key description can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
              "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
              "num_tokens_for_completion": 4096,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "top_k": null,
                   "type": "google_params"
              },
              "embeddings": {
                   "model": "azure__openai__text_embedding_ada_002",
                   "strategy": {
                        "id": "basic",
                        "num_tokens_per_chunk": 64
                   }
              }
         }
    }
    `````
  </Tab>

  <Tab title="Extract structured">
    When you set the `mode` parameter to `extract_structured` the response will be as follows:

    `````sh theme={null}
    {
         "type": "ai_agent_extract_structured",
         "basic_text": {
              "model": "google__gemini_1_5_flash_001",
              "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
              "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
              "num_tokens_for_completion": 4096,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "top_k": null,
                   "type": "google_params"
              }
           },
         "long_text": {
              "model": "google__gemini_1_5_flash_001",
              "system_message": "Respond only in valid json. You are extracting metadata that is name, value pairs from a document. Only output the metadata in valid json form, as {\"name1\":\"value1\",\"name2\":\"value2\"} and nothing else. You will be given the document data and the schema for the metadata, that defines the name, description and type of each of the fields you will be extracting. Schema is of the form {\"fields\": [{\"key\": \"key_name\", \"prompt\": \"prompt to extract the value\", \"type\": \"date\"}]}. Leverage prompt for each key to identify where the key and value pairs are in the document. In certain cases, prompt can also indicate the instructions to perform on the document to obtain the value. Prompt will be in the form of Schema is ``schema`` \n document is ````document````",
              "prompt_template": "If you need to know today's date to respond, it is {current_date}. Schema is ``{user_question}`` \n document is ````{content}````",
              "num_tokens_for_completion": 4096,
              "llm_endpoint_params": {
                   "temperature": 0,
                   "top_p": 1,
                   "top_k": null,
                   "type": "google_params"
                 },
              "embeddings": {
                   "model": "google__textembedding_gecko_003",
                   "strategy": {
                        "id": "basic",
                        "num_tokens_per_chunk": 64
                   }
              }
         }
    }
    `````
  </Tab>
</Tabs>

[override-tutorials]: /guides/box-ai/ai-agents/ai-agent-overrides

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# AI model overrides
Source: https://developer.box.com/guides/box-ai/ai-agents/index

Override the default AI model, prompt, and LLM parameters used by Box AI API endpoints.

These guides explain how to inspect and customize the AI agent configurations that Box AI uses behind the scenes. For an overview of the override system, including when to use overrides, the configuration structure by endpoint, and LLM parameter differences by provider, see the <Link href="/guides/box-ai/index#the-ai_agent-override-system">Box AI overview</Link>.

<CardGroup>
  <Card title="Override configuration" icon="sliders" href={localizeLink("/guides/box-ai/ai-agents/ai-agent-overrides")}>
    Full `ai_agent` parameter reference with sample payloads for `ask`,
    `text_gen`, `extract`, and `extract_structured`.
  </Card>

  <Card title="Get default configuration" icon="gear" href={localizeLink("/guides/box-ai/ai-agents/get-agent-default-config")}>
    Fetch the current defaults with `GET /2.0/ai_agent_default` so you know
    what you are overriding.
  </Card>

  <Card title="Configuration versioning" icon="clock-rotate-left" href={localizeLink("/guides/box-ai/ai-agents/ai-agent-versioning")}>
    See how Box versions agent snapshots, the 12-month support guarantee, and
    transition timelines.
  </Card>

  <Card title="Supported models" icon="microchip" href={localizeLink("/guides/box-ai/ai-models/index")}>
    Full list of core and customer-enabled models with capability tiers,
    compliance badges, and API names.
  </Card>
</CardGroup>


# AWS Claude Haiku 4.5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-5-haiku-model-card



According to Anthropic, the **AWS Claude Haiku 4.5** model is optimized for high-volume, low-latency applications. It provides strong coding performance with improved speed and cost efficiency compared to larger models.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Haiku 4.5** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_4_5_haiku` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **October 15th, 2025** | The release date for the model. |
| Knowledge cutoff date | **February 2025** | The date after which the model does not get any information updates. |
| Input context window | **200k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Haiku 4.5 documentation][aws-claude].

[aws-claude]: https://aws.amazon.com/bedrock/anthropic/

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Opus 4.5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-5-opus-model-card



According to Anthropic, the **AWS Claude Opus 4.5** model is designed for developers building sophisticated AI agents that can reason, plan, and perform complex tasks with minimal oversight.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Opus 4.5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_4_5_opus` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **November 24th, 2025** | The release date for the model. |
| Knowledge cutoff date | **March 2025** | The date after which the model does not get any information updates. |
| Input context window | **200k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Opus 4.5 documentation][aws-claude].

[aws-claude]: https://aws.amazon.com/bedrock/anthropic/

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Sonnet 4.5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-5-sonnet-model-card



According to Anthropic, the **AWS Claude Sonnet 4.5** model is a high-performance model designed for building complex agents, delivering leading coding capabilities, and executing across development tasks. It excels at autonomously planning and executing complex, multi-step workflows and is particularly effective in areas like finance, research, and cybersecurity.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Sonnet 4.5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_4_5_sonnet` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **September 29th, 2025** | The release date for the model. |
| Knowledge cutoff date | **January 2025** | The date after which the model does not get any information updates. |
| Input context window | **200k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Sonnet 4.5 documentation][aws-claude].

[aws-claude]: https://aws.amazon.com/bedrock/anthropic/

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Opus 4.6
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-6-opus-model-card



According to Anthropic, **AWS Claude Opus 4.6** is the next generation of Anthropic's most intelligent model designed for coding, enterprise agents, and professional work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Opus 4.6** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_4_6_opus` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **February 5th, 2026** | The release date for the model. |
| Knowledge cutoff date | **May 2025** | The date after which the model does not get any information updates. |
| Input context window | **200k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Opus 4.6 documentation][aws-claude].

[aws-claude]: https://platform.claude.com/docs/en/about-claude/models/overview

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Sonnet 4.6
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-6-sonnet-model-card



## Overview

According to Anthropic, **AWS Claude Sonnet 4.6** is a powerful, versatile model built for daily use, scaled production, and complex tasks across coding, agents, and professional workflows.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Sonnet 4.6** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_4_6_sonnet` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **February 17th, 2026** | The release date for the model. |
| Knowledge cutoff date | **August 2025** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **64k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see <Link href="https://aws.amazon.com/bedrock/claude/">official AWS Claude documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Opus 4.7
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-7-opus-model-card



According to Anthropic, **AWS Claude Opus 4.7** is a highly autonomous model which performs well on long-horizon agentic work, knowledge work, vision tasks, and memory tasks.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Opus 4.7** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_4_7_opus` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **April 16th, 2026** | The release date for the model. |
| Knowledge cutoff date | **January 2026** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Opus 4.7 documentation][aws-claude].

[aws-claude]: https://aws.amazon.com/bedrock/anthropic/

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Opus 4.8
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-8-opus-model-card



According to Anthropic, **AWS Claude Opus 4.8** is Anthropic's most capable model for complex reasoning, long-horizon agentic coding, and high-autonomy work.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Opus 4.8** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_4_8_opus` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **May 28th, 2026** | The release date for the model. |
| Knowledge cutoff date | **January 2026** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see [official AWS Claude Opus 4.8 documentation][claude-opus-4-8].

[claude-opus-4-8]: https://platform.claude.com/docs/en/about-claude/models/overview

<RelatedLinks title="RELATED GUIDES" />


# AWS Claude Sonnet 5
Source: https://developer.box.com/guides/box-ai/ai-models/aws-claude-sonnet-5-model-card



## Overview

According to Anthropic, **AWS Claude Sonnet 5** offers the best combination of speed and intelligence. It is the most agentic Sonnet model yet, able to make plans, use tools such as browsers and terminals, and run autonomously.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **AWS Claude Sonnet 5** | The name of the model. |
| Model category | **Premium** | The category of the model: Standard or Premium. |
| API model name | `aws__claude_sonnet_5` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **ISMAP, FedRAMP Moderate** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Amazon Web Services (AWS)** | The trusted organization that securely hosts the LLM. |
| Model provider | **Anthropic** | The organization that provides this model. |
| Release date | **June 30th, 2026** | The release date for the model. |
| Knowledge cutoff date | **January 2026** | The date after which the model does not get any information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **128k tokens** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |

## Additional documentation

For additional information, see <Link href="https://aws.amazon.com/bedrock/claude/">official AWS Claude documentation</Link>.

<RelatedLinks title="RELATED GUIDES" />


# IBM Llama 4 Maverick
Source: https://developer.box.com/guides/box-ai/ai-models/ibm-llama-4-maverick-model-card



According to Meta, **IBM Llama 4 Maverick** is a natively multimodal AI model using a mixture-of-experts architecture, designed for high-performance text and image understanding with support for 12 languages.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **IBM Llama 4 Maverick** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `ibm__llama_4_maverick` | The name of the model that is used in the [Box AI API for model overrides]. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **IBM** | The trusted organization that securely hosts the LLM. |
| Model provider | **Meta** | The organization that provides this model. |
| Release date | **April 5th, 2025** | The release date for the model. |
| Knowledge cutoff date | **August 2024** | The date after which the model does not get any information updates. |
| Input context window | **1m** | The number of tokens supported by the input context window. |
| Maximum output tokens | **Not specified** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **Yes** | Specifies if the model's code is available for public use. |
| IP infringement protection | **No** | Use of this model does not come with any intellectual property rights assurances or protections from Box. Please consider any potential IP issues that might arise from using the model’s outputs. |

## Additional documentation

For additional information, see [official IBM Llama 4 Maverick documentation][IBM].

[Box AI API for model overrides]: /guides/box-ai/ai-agents/ai-agent-overrides

[IBM]: https://www.ibm.com/docs/en/watsonx/w-and-w/2.2.0?topic=models-third-party-foundation#llama-4


# IBM Mistral Medium 3
Source: https://developer.box.com/guides/box-ai/ai-models/ibm-mistral-medium-3-model-card



According to Mistral AI, the **IBM Mistral Medium 3** model is a high-performance enterprise-grade model that delivers frontier-level capabilities, excelling in coding, STEM reasoning, and multimodal understanding.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **IBM Mistral Medium 3** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `ibm__mistral_medium_2505` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **IBM** | The trusted organization that securely hosts the LLM. |
| Model provider | **Mistral AI** | The organization that provides this model. |
| Release date | **May 2025** | The release date for the model. |
| Knowledge cutoff date | **Not specified** | The date after which the model does not get any information updates. |
| Input context window | **128k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **Not specified** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies if the model's code is available for public use. |
| IP infringement protection | **No** | Use of this model does not come with any intellectual property rights assurances or protections from Box. Please consider any potential IP issues that might arise from using the model’s outputs. |

## Additional documentation

For additional information, see [official Mistral AI documentation][mistral-ai].

[mistral-ai]: https://docs.mistral.ai/getting-started/models/models_overview/

<RelatedLinks title="RELATED GUIDES" />


# IBM Mistral Small 3.1
Source: https://developer.box.com/guides/box-ai/ai-models/ibm-mistral-small-3-1-model-card



According to Mistral AI, the **IBM Mistral Small 3.1** model is a fast, efficient open-source model with multimodal capabilities and extended context window. It delivers strong performance across text and vision tasks while maintaining low latency, making it suitable for a wide range of applications from conversational AI to document processing.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **IBM Mistral Small 3.1** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard or Premium. |
| API model name | `ibm__mistral_small_3_1_24b_instruct_2503` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. The user must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **IBM** | The trusted organization that securely hosts the LLM. |
| Model provider | **Mistral AI** | The organization that provides this model. |
| Release date | **March 2025** | The release date for the model. |
| Knowledge cutoff date | **Not specified** | The date after which the model does not get any information updates. |
| Input context window | **128k tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **Not specified** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **150** | The number of tokens the model can generate per second. |
| Open source | **Yes** | Specifies if the model's code is available for public use. |
| IP infringement protection | **No** | Use of this model does not come with any intellectual property rights assurances or protections from Box. Please consider any potential IP issues that might arise from using the model’s outputs. |

## Additional documentation

For additional information, see [official Mistral AI documentation][mistral-ai].

[mistral-ai]: https://docs.mistral.ai/getting-started/models/models_overview/

<RelatedLinks title="RELATED GUIDES" />


# Meta Muse Spark 1.2
Source: https://developer.box.com/guides/box-ai/ai-models/meta-muse-spark-1-2-model-card



According to Meta, **Meta Muse Spark 1.2** is a multimodal model designed for general-purpose text and image understanding.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Muse Spark 1.2** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `meta__muse_spark_1_2` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Meta** | The trusted organization that securely hosts the LLM. |
| Model provider | **Meta** | The organization that provides this model. |
| Release date | **August 5th, 2026** | The release date for the model. |
| Knowledge cutoff date | **Not specified** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **Not specified** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official Meta Muse Spark 1.2 documentation][meta-muse-spark].

[meta-muse-spark]: https://dev.meta.ai/docs/overview#muse-spark

<RelatedLinks title="RELATED GUIDES" />


# Meta Muse Spark 1.3
Source: https://developer.box.com/guides/box-ai/ai-models/meta-muse-spark-1-3-model-card



According to Meta, **Meta Muse Spark 1.3** is a multimodal model designed for general-purpose text and image understanding.

## Model details

| Item | Value | Description |
| - | - | - |
| Model name | **Muse Spark 1.3** | The name of the model. |
| Model category | **Standard** | The category of the model: Standard, Premium, or Ultra. |
| API model name | `meta__muse_spark_1_3` | The name of the model that is used in the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">Box AI API for model overrides</Link>. You must provide this exact name for the API to work. |
| Compliance | **N/A** | Government compliance frameworks and authorizations applicable to this model. |
| Hosting layer | **Meta** | The trusted organization that securely hosts the LLM. |
| Model provider | **Meta** | The organization that provides this model. |
| Release date | **September 2nd, 2026** | The release date for the model. |
| Knowledge cutoff date | **Not specified** | The date after which the model does not receive information updates. |
| Input context window | **1m tokens** | The number of tokens supported by the input context window. |
| Maximum output tokens | **Not specified** | The number of tokens that can be generated by the model in a single request. |
| Empirical throughput | **Not specified** | The number of tokens the model can generate per second. |
| Open source | **No** | Specifies whether the model's code is available for public use. |

## Additional documentation

For additional information, see [official Meta Muse Spark 1.3 documentation][meta-muse-spark].

[meta-muse-spark]: https://dev.meta.ai/models/muse-spark

<RelatedLinks title="RELATED GUIDES" />


# Ask questions to Box AI
Source: https://developer.box.com/guides/box-ai/ai-tutorials/ask-questions

Use the POST /ai/ask endpoint to ask questions about one or more files stored in Box.

Box AI API allows you to
ask a question about a supplied file or
a set of files, and get a response based on
the content.
For example, while viewing a document in Box,
you can ask Box AI to summarize the content.

You can also ask questions against a <Link href="/guides/hubs-api/index">Box Hub</Link>. When you pass a hub as the item, Box AI searches the hub's indexed content and returns answers grounded in the curated documents the querying user has access to. See <Link href="#ask-questions-about-a-hub">Ask questions about a hub</Link> below.

## Before you start

Make sure you followed the steps listed in <Link href="/guides/box-ai/ai-tutorials/prerequisites">getting started with Box AI</Link> to create a platform app and authenticate.

## Send a request

To send a request containing your question,
use the `POST /2.0/ai/ask` endpoint and
provide the mandatory parameters.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
       -H "content-type: application/json" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
           "mode": "single_item_qa",
           "prompt": "What is the value provided by public APIs based on this document?",
           "items": [
              {
              "type": "file",
              "id": "9842787262"
              }
           ],
           "dialogue_history": [
                {
                "prompt": "Make my email about public APIs sound more professional",
                "answer": "Here is the first draft of your professional email about public APIs",
                "created_at": "2013-12-12T10:53:43-08:00"
                }
            ],
            "include_citations": true,
            "ai_agent": {
              "type": "ai_agent_ask",
              "long_text": {
                "model": "openai__gpt_5_mini",
                "prompt_template": "It is `{current_date}`. Use this content: `{content}`. Answer: `{user_question}`"
              },
              "basic_text": {
                "model": "openai__gpt_5_mini"
              }
            }
        }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.ai.createAiAsk({
    mode: 'single_item_qa' as AiAskModeField,
    prompt: 'which direction sun rises',
    items: [
      {
        id: fileToAsk.id,
        type: 'file' as AiItemAskTypeField,
        content: 'Sun rises in the East',
      } satisfies AiItemAsk,
    ],
    aiAgent: aiAskAgentConfig,
  } satisfies AiAsk);
  ```

  ```python Python v10 theme={null}
  client.ai.create_ai_ask(
      CreateAiAskMode.SINGLE_ITEM_QA,
      "which direction sun rises",
      [
          AiItemAsk(
              id=file_to_ask.id,
              type=AiItemAskTypeField.FILE,
              content="Sun rises in the East",
          )
      ],
      ai_agent=ai_ask_agent_config,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Ai.CreateAiAskAsync(requestBody: new AiAsk(mode: AiAskModeField.SingleItemQa, prompt: "which direction sun rises", items: Array.AsReadOnly(new [] {new AiItemAsk(id: fileToAsk.Id, type: AiItemAskTypeField.File) { Content = "Sun rises in the East" }})));
  ```

  ```swift Swift v10 theme={null}
  try await client.ai.createAiAsk(requestBody: AiAsk(mode: AiAskModeField.singleItemQa, prompt: "which direction sun rises", items: [AiItemAsk(id: fileToAsk.id, type: AiItemAskTypeField.file, content: "Sun rises in the East")]))
  ```

  ```java Java v10 theme={null}
  client.getAi().createAiAsk(new AiAsk.Builder(AiAskModeField.SINGLE_ITEM_QA, "which direction sun rises", Arrays.asList(new AiItemAsk.Builder(fileToAsk.getId(), AiItemAskTypeField.FILE).content("Sun rises in the East").build())).aiAgent(aiAskAgentConfig).build())
  ```

  ```java Java v5 theme={null}
  BoxAIResponse response = BoxAI.sendAIRequest(
      api,
      "What is the content of the file?",
      Collections.singletonList("123456", BoxAIItem.Type.FILE),
      BoxAI.Mode.SINGLE_ITEM_QA
  );
  ```

  ```python Python v4 theme={null}
  items = [{
      "id": "1582915952443",
      "type": "file",
      "content": "More information about public APIs"
  }]
  ai_agent = {
      'type': 'ai_agent_ask',
      'basic_text_multi': {
          'model': 'openai__gpt_3_5_turbo'
      }
  }
  answer = client.send_ai_question(
      items=items, 
      prompt="What is this file?",
      mode="single_item_qa",
      ai_agent=ai_agent
  )
  print(answer)
  ```

  ```cs .NET v6 theme={null}
  BoxAIResponse response = await client.BoxAIManager.SendAIQuestionAsync(
      new BoxAIAskRequest
      {
          Prompt = "What is the name of the file?",
          Items = new List<BoxAIAskItem>() { new BoxAIAskItem() { Id = "12345" } },
          Mode = AiAskMode.single_item_qa
      };
  );
  ```

  ```javascript Node v4 theme={null}
  client.ai.ask(
      {
          prompt: 'What is the capital of France?',
          items: [
              {
                  type: 'file',
                  id: '12345'
              }
          ],
          mode: 'single_item_qa'
      })
      .then(response => {
          /* response -> {
              "answer": "Paris",
              "created_at": "2021-10-01T00:00:00Z",
              "completion_reason": "done"
          } */
      });
  ```
</CodeGroup>

### Parameters

To make a call, you need to pass the following parameters.
Mandatory parameters are in **bold**.

| Parameter | Description | Available values | Example |
| - | - | - | - |
| **`mode`** | The type of request. Use `single_item_qa` for a single file (the `items` array must contain exactly one element) or `multiple_item_qa` for up to 25 files. For full details on file size, image, and prompt limits, see <Link href="/guides/box-ai/index#input-limits">input limits</Link>. | `single_item_qa`, `multiple_item_qa` | `single_item_qa` |
| **`prompt`** | The question about your document or content. Maximum 10,000 characters. | | `What is this document about?` |
| `dialogue_history.prompt` | The prompt previously provided by the client and answered by the Large Language Model (LLM). | | `Make my email about public APIs sound more professional` |
| `dialogue_history.answer` | The answer previously provided by the LLM. | | `Here is a draft of your professional email about public APIs.` |
| `dialogue_history.created_at` | The ISO date formatted timestamp of when the previous answer to the prompt was created. | | `2012-12-12T10:53:43-08:00` |
| `include_citations` | Specifies if the citations should be returned in the answer. | `true`, `false` | `true` |
| **`items.id`** | The ID of the file or hub you want to provide as input. | | `112233445566` |
| **`items.type`** | The type of the provided input. Use `file` for one or more files, or `hubs` to query a Box Hub. A `hubs` item must be the only item in the request. | `file`, `hubs` | `file` |
| `items.content` | The content of the item. Usually it is the text representation. | | `An application programming interface (API) is a way for two or more computer programs or components to communicate with each other. It is a type of software interface...` |
| `ai_agent` | Override the default model configuration. Lets you change the model, prompt template, system message, or LLM parameters. See <Link href="/guides/box-ai/index#the-ai_agent-override-system">the override system</Link> for how it works and <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">AI model overrides</Link> for examples. | | |

## Use cases

## Ask questions about an item

This example shows how to ask a question about one or more items using the `POST ask/ai` API. When using this endpoint, remember to specify the `mode` parameter depending on the number of items you want to supply.

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'
```

The response will be as follows:

```sh theme={null}
{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview.\n2. If questions fall outside the scope of the document, Box AI will inform you that it cannot answer.\n3. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n4. Aim to stay within the scope of the document.\n5. Focus on text-based responses only.",
    "created_at": "2024-11-04T02:30:09.557-08:00",
    "completion_reason": "done"
}
```

## Ask questions about a hub

Instead of supplying individual files, you can point Box AI at an entire <Link href="/guides/hubs-api/index">Box Hub</Link> and ask questions across all of its curated content. This is useful for knowledge bases such as RFP answer banks, policy libraries, and product documentation portals, where you want natural language answers grounded in an approved set of materials without managing file IDs yourself.

To query a hub, set `items.type` to `hubs` and `items.id` to the hub ID. A hub must be supplied as the only item in the request. The example below uses `single_item_qa` mode, which is the pattern shown in the <Link href="/tutorials/sales-rfp-answer-bank">Sales RFP answer bank tutorial</Link>.

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "98765432",
            "type": "hubs"
        }
    ],
    "prompt": "What is our standard SLA for enterprise support?"
}'
```

Box AI searches the hub's indexed content and returns an answer grounded in your approved materials. Because hubs inherit Box permissions, Box AI only references documents the querying user has access to. The hub must have AI features enabled (see <Link href="/guides/hubs-api/hubs/update-hub">Update a hub</Link>).

For an end-to-end walkthrough that provisions a hub, populates it with content, and queries it with Box AI, see the <Link href="/tutorials/sales-rfp-answer-bank">Build a sales RFP answer bank with Box Hubs and AI</Link> tutorial.

## Ask questions with `content` parameter

If you use the `content` parameter as the source of input for Box AI, it will use it as the primary source.

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "single_item_qa",
    "items": [
        {
            "id": "12345678",
            "type": "file",
            "content": "This is a document about Box AI For documents. It consists of the functionality summary and guidelines on how to work with Box AI. Additionally, it provides a set of best practices for creating questions."
        }
    ],
    "prompt": "List the guidelines on creating questions in Box AI for Documents"
}'
```

The response to this request is based on the `content` parameter instead of the file's content:

```sh theme={null}
{
    "answer": "The document does not provide specific guidelines on working with questions in Box AI for Documents. It only mentions that it includes a set of best practices for creating questions, but the details of those guidelines are not included in the text provided. If you have more information or another document, I can help further!",
    "created_at": "2024-11-04T02:31:51.125-08:00",
    "completion_reason": "done"
}
```

## Ask questions with `citations` parameter

Setting the `citations` parameter to `true` causes the response to include excerpts from source file or files Box AI used to compile the answer.

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "mode": "multiple_item_qa",
    "include_citations": true,
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "List the guidelines on working with responses in Box AI for Documents"
}'
```

The resulting answer includes the source file and direct content citations.

```sh theme={null}
{
    "answer": "The guidelines for working with questions in Box AI for Documents are as follows:\n\n1. Box AI pulls information only from the document loaded in preview, and cannot answer questions outside its scope.\n2. Be specific when asking questions; use parameters like numbered lists, brevity, tables, and central themes or key points.\n3. Examples of better phrasing include asking for a numbered list of key points instead of just \"list key points,\" and requesting a succinct outline of important points rather than a general inquiry about the document's purpose.\n4. Stay within the scope of the document and focus on text-based responses only.",
    "created_at": "2024-11-04T02:35:00.578-08:00",
    "completion_reason": "done",
    "citations": [
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Guidelines for Box AI questions\nBox AI pulls information only from the document you loaded in preview."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "If you ask any questions outside of the scope of the document, Box AI informs you that it cannot answer the question with the information provided."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "As you ask Box AI to analyze your document, consider these suggestions:\n· Be as specific as possible."
        },
        {
            "type": "file",
            "id": "12345678",
            "name": "Box AI for Documents.docx",
            "content": "Box AI for Documents\n\nWhen viewing a document in Box, you can ask Box AI to summarize document content, search key points, and write outline drafts based on your document files."
        }
    ]
}
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Override AI model configuration
Source: https://developer.box.com/guides/box-ai/ai-tutorials/default-agent-overrides

Step-by-step examples of overriding prompts and models for ask, text_gen, and extract endpoints.

## Before you start

Make sure you followed the steps listed in <Link href="/guides/box-ai/ai-tutorials/prerequisites">getting started with Box AI</Link> to create a platform app and authenticate.
To get more context, read about <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">agent overrides</Link>.

## Override prompt

This example shows how to use the `prompt_template` parameter to change the
query result.
The first step is to ask Box AI to summarize a document about Box AI for Documents.
The `mode` parameter is set to `single_item_qa` because only one document is supplied.

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/ask" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "mode": "single_item_qa",
       "prompt": "Summarize this article about Box AI for Documents",
       "items": [
         {
           "type": "file",
           "id": "123467890"
         }
       ]
     }'
```

You will get a response similar to the following:

```sh theme={null}
{
    "answer": "Box AI for Documents is a tool that enhances document analysis by allowing users to summarize content, identify key points, and draft outlines directly from files in Box. It supports various file types, including text documents, spreadsheets, and presentation slides. Users can initiate interactions with Box AI through the web app, where they can select suggestions or type specific questions. Responses are generated in real time, and users have options to save or clear chat history. The document also provides guidelines for effective inquiries and troubleshooting tips for potential issues with using Box AI.",
    "created_at": "2024-10-08T00:29:07.283-07:00",
    "completion_reason": "done"
}
```

To further improve the result, you can use the `prompt_template` parameter to add some more instructions for Box AI. In this example, let's change the tone of the response.

```sh theme={null}
{
    "prompt": "Summarize this article about Box AI for Documents",
    "mode": "single_item_qa",
    "items": [
        {
            "id": "123467890",
            "type": "file"
        }
    ],
    "ai_agent": {
        "type": "ai_agent_ask",
        "basic_text": {
            "prompt_template": "{user_question} Write the summary in an informal way.{content}"
        }
    }
}
```

The response would be slightly less formal:

```sh theme={null}
{
    "answer": "Box AI for Documents is a tool that helps you analyze and gain insights from your documents in Box. You can use it to summarize content, identify key points, and draft outlines, making it easier to handle meeting notes, reports, and marketing materials. To get started, just open a file in the Box web app and click the Box AI button. It offers quick suggestions like summarizing the document or checking for next steps. Responses are generated in real time, and you can save them or clear chat history as needed. Just remember, Box AI only pulls info from the document you're viewing, so be specific with your questions!",
    "created_at": "2024-10-08T00:38:01.767-07:00",
    "completion_reason": "done"
}
```

## Override AI model (text generation)

This example shows you how changing the AI model in the `ai_agent` options can influence the way the text is generated.

First let's generate some text using the `POST ai/text_gen` endpoint. This endpoint is using the OpenAI 3.5 turbo model by default.

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/text_gen" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "prompt": "Write a short post about Box AI for documents.Make it highlight the benefits of the solution. You can add some emoticons.",
       "items": [
         {
           "id": "123467890",
           "type": "file"
         }
       ]
     }'
```

The response is as follows:

```sh theme={null}
{
    "answer": "🌟 Exciting News! 🌟\n\nIntroducing Box AI for documents - your new best friend in creating smarter, more efficient content! 🤖💡\n\n🔹 Say goodbye to manual searching and organizing - Box AI does it all for you!\n🔹 Enjoy lightning-fast document analysis and categorization.\n🔹 Boost productivity with automated suggestions and smart recommendations.\n🔹 Collaborate seamlessly with real-time insights and intelligent tagging.\n\nExperience the future of document creation with Box AI - making work easier, faster, and more fun! 🚀💻 #BoxAI #SmartDocuments",
    "created_at": "2024-10-08T01:19:06.22-07:00",
    "completion_reason": "done"
}
```

Let's change the model using the `ai_agent` configuration:

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/text_gen" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "prompt": "Write a short post about Box AI for documents.Make it highlight the benefits of the solution. You can add some emoticons.",
       "items": [
         {
           "id": "123467890",
           "type": "file"
         }
       ],
       "ai_agent": {
         "type": "ai_agent_text_gen",
         "basic_gen": {
           "model": "openai__gpt_5"
         }
       }
     }'
```

After the model switch, the response is slightly different:

```sh theme={null}
{
    "answer": "🚀 **Boost Your Productivity with Box AI for Documents!** 📄✨\n\nSay goodbye to tedious document creation and editing! With Box AI, you can streamline your workflow and focus on what truly matters. Here’s why you’ll love it:\n\n1. **Smart Suggestions** 🤖: Get real-time recommendations to enhance your content.\n2. **Automated Formatting** 📝: Ensure consistency across all your documents effortlessly.\n3. **Collaboration Made Easy** 👥: Work seamlessly with your team, no matter where they are.\n4. **Time-Saving Templates** ⏳: Use pre-built templates to speed up document creation.\n5. **Enhanced Accuracy** ✅: Reduce errors with intelligent proofreading.\n\nTransform the way you work with documents and experience a new level of efficiency with Box AI! 🌟",
    "created_at": "2024-10-08T01:28:36.777-07:00",
    "completion_reason": "done"
}
```

As you can see the responses differ to some extent. Thanks to the model switch, you can optimize your interaction with Box AI and choose the most suitable model for your needs.

## Override AI model (metadata extraction)

Switching models can also give us different results for metadata extraction.
Let's use a sample contract to extract the metadata. In this example, the model used is Google Gemini.

```sh theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/ai/extract' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
        "prompt": "Extract any data that would be good metadata to save for future contracts.",
        "items": [
          {
            "type": "file",
            "id": "123456789"
          }
        ]
      }'
```

The response is a set of metadata:

```sh theme={null}
{
    "answer": "{\"Buyer Legal Entity Name\": \"Acme Retail Corp.\", \"Supplier Legal Entity Name\": \"Acme Manufacturing Inc.\", \"Buyer Contact Person\": \"Jane Doe\", \"Supplier Contact Person\": \"Eva Smith\", \"Payment Term\": \"payment in full before pickup of goods\", \"Invoice Currency\": \"Euro\", \"Incoterm\": \"FCA Amsterdam\", \"Governing Law\": \"laws state jurisdiction in which supplier is located\", \"Effective Date\": \"March 27, 2024\", \"Buyer Signature Date\": \"March 28th, 2024\", \"Supplier Signature Date\": \"March 28th, 2024\"}",
    "created_at": "2024-10-08T01:53:14.993-07:00",
    "completion_reason": "done"
}
```

Let's change the model to the most recent OpenAI option:

```sh theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/ai/extract' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer <ACCESS_TOKEN>' \
     -d '{
        "prompt": "Extract any data that would be good metadata to save for future contracts.",
        "items": [
          {
            "type": "file",
            "id": "123456789"
          }
        ],
          "ai_agent": {
            "type": "ai_agent_extract",
            "basic_text": {
                "model": "openai__gpt_5"
            }
         }
      }'
```

Using this model results in a response listing more metadata entries:

```sh theme={null}
{
    "answer": "{\"Effective Date\": \"March 27, 2024\", \"Supplier Legal Entity Name\": \"Acme Manufacturing Inc.\", \"Supplier Registered Office Address\": \"123 Main Street\", \"Supplier Contact Person(s)\": \"Eva Smith\", \"Buyer Legal Entity Name\": \"Acme Retail Corp.\", \"Buyer Registered Office Address\": \"456 Market Avenue\", \"Buyer Contact Person(s)\": \"Jane Doe\", \"Incoterm\": \"FCA Amsterdam\", \"Payment Term\": \"payment in full before pickup of goods\", \"Invoice Currency\": \"Euro\", \"Buyer Printed Name\": \"Jane Doe\", \"Buyer Date\": \"March 28th, 2024\", \"Buyer Title / Position\": \"CEO\", \"Seller Printed Name\": \"Eve Smith\", \"Seller Date\": \"March 28th, 2024\", \"Seller Title / Position\": \"Sales Manager\"}",
    "created_at": "2024-10-08T01:54:28.099-07:00",
    "completion_reason": "done"
}
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Extract metadata from file (freeform)
Source: https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata

Use the POST /ai/extract endpoint to extract metadata from documents using natural language prompts.

Box AI API allows you to query a document and extract metadata based on a provided prompt.
**Freeform** means that the prompt can include a stringified version of formats such as JSON or XML, or even plain text.

<Note>
  The **Extract metadata (freeform)** endpoint doesn't support OCR. To extract metadata from image files (TIFF, PNG, JPEG) or documents in languages other than English, use the <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured">Extract metadata (structured)</Link> endpoint.
</Note>

## Before you start

Make sure you followed the steps listed in <Link href="/guides/box-ai/ai-tutorials/prerequisites">getting started with Box AI</Link> to create a platform app and authenticate.

## Send a request

To send a request, use the
`POST /2.0/ai/extract` endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST 'https://api.box.com/2.0/ai/extract' \
       -H 'content-type: application/json' \
       -H 'authorization: Bearer <ACCESS_TOKEN>' \
       -d '{
          "prompt": "Extract data related to contract conditions",
          "items": [
            {
              "type": "file",
              "id": "1497741268097"
            }
          ],
          "ai_agent": {
            "type": "ai_agent_extract",
            "long_text": {
              "model": "openai__gpt_5_mini",
              "prompt_template": "It is `{current_date}`. Use this content: `{content}`. Answer: `{user_question}`"
            },
            "basic_text": {
              "model": "openai__gpt_5_mini"
            }
          }
        }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.ai.createAiExtract({
    prompt: 'firstName, lastName, location, yearOfBirth, company',
    items: [new AiItemBase({ id: file.id })],
    aiAgent: agentIgnoringOverridingEmbeddingsModel,
  } satisfies AiExtract);
  ```

  ```python Python v10 theme={null}
  client.ai.create_ai_extract(
      "firstName, lastName, location, yearOfBirth, company",
      [AiItemBase(id=file.id)],
      ai_agent=agent_ignoring_overriding_embeddings_model,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Ai.CreateAiExtractAsync(requestBody: new AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})));
  ```

  ```swift Swift v10 theme={null}
  try await client.ai.createAiExtract(requestBody: AiExtract(prompt: "firstName, lastName, location, yearOfBirth, company", items: [AiItemBase(id: file.id)]))
  ```

  ```java Java v10 theme={null}
  client.getAi().createAiExtract(new AiExtract.Builder("firstName, lastName, location, yearOfBirth, company", Arrays.asList(new AiItemBase(file.getId()))).aiAgent(agentIgnoringOverridingEmbeddingsModel).build())
  ```

  ```java Java v5 theme={null}
  BoxAIResponse response = BoxAI.extractMetadataFreeform(
      api,
      "firstName, lastName, location, yearOfBirth, company",
      Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE))
  );
  ```
</CodeGroup>

### Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

The `items` array must contain exactly one element. For prompt and file limits, see <Link href="/guides/box-ai/index#input-limits">input limits</Link>.

| Parameter | Description | Example |
| - | - | - |
| **`prompt`** | The request for Box AI to extract metadata. Maximum 10,000 characters. | Create a meeting agenda for a weekly sales meeting. |
| **`items.id`** | Box file ID of the document. The ID must reference an actual file with an extension. | `1233039227512` |
| **`items.type`** | The type of the supplied input. | `file` |
| `items.content` | The content of the item, often the text representation. | `This article is about Box AI`. |
| `ai_agent` | Override the default model configuration. Lets you change the model, prompt template, system message, or LLM parameters. See <Link href="/guides/box-ai/index#the-ai_agent-override-system">the override system</Link> for how it works and <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">AI model overrides</Link> for examples. | |

## Use cases

This example shows you how to extract metadata from a sample invoice.

### Create the request

To get the response from Box AI, call `POST /2.0/ai/extract` endpoint with the following parameters:

* `prompt` that can be a query, or a structured or unstructured list of fields to extract.
* `type` and `id` of the file to extract the data from.

### Create the prompt

Depending on the use case and the level of detail, you can construct various prompts.

#### Use plain text

Because this endpoint allows freeform prompts, you can use plain text to get the information.

```bash theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "prompt": "find the document type (invoice or po), vendor, total, and po number",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'
```

In such a case, the response will be based on the keywords included in the text:

```bash theme={null}
{
    "answer": "{\"Document Type\": \"Invoice\", \"Vendor\": \"Quasar Innovations\", \"Total\": \"$1,050\", \"PO Number\": \"003\"}",
    "created_at": "2024-05-31T10:30:51.223-07:00",
    "completion_reason": "done"
}
```

#### Use specific terms

If you don't want to write the entire sentence, the prompt can consist of terms that you expect to find in an invoice:

```bash theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "prompt": "{\"vendor\",\"total\",\"doctype\",\"date\",\"PO\"}",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'
```

Using this approach results in a list of terms provided in the request and their values:

```bash theme={null}
{
    "answer": "{\"vendor\": \"Quasar Innovations\", \"total\": \"$1,050\", \"doctype\": \"Invoice\", \"PO\": \"003\"}",
    "created_at": "2024-05-31T10:28:51.906-07:00",
    "completion_reason": "done"
}
```

#### Use key-value pairs

The prompt can also be a list of key-value pairs that helps Box AI to come up with the metadata structure. This approach requires listing the key-value pairs within a `fields` array.

```bash theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/ai/extract' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
          "prompt": "{\"fields\":[{\"key\":\"vendor\",\"displayName\":\"Vendor\",\"type\":\"string\",\"description\":\"Vendorname\"},{\"key\":\"documentType\",\"displayName\":\"Type\",\"type\":\"string\",\"description\":\"\"}]}",
    "items": [
        {
            "type": "file",
            "id": "1443721424754"
        }
    ]
}'
```

The response includes the `fields` present in the file, along with their values:

```bash theme={null}
{
    "answer": "{\"vendor\": \"Quasar Innovations\", \"documentType\": \"Invoice\"}",
    "created_at": "2024-05-31T10:15:38.17-07:00",
    "completion_reason": "done"
}
```

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Extract metadata from file (structured)
Source: https://developer.box.com/guides/box-ai/ai-tutorials/extract-metadata-structured

Use the POST /ai/extract_structured endpoint to extract metadata using templates, field definitions, or the Enhanced Extract Agent.

With the Box AI API, you can extract file metadata as key-value pairs.
As input, you can create a structure with the `fields` parameter, or use an existing metadata template.
To learn more about creating templates, see [customizing metadata templates in the Admin Console][templates-console] or use the <Link href="/guides/metadata/templates/create">metadata template API</Link>. You can also [autofill metadata in templates][autofill-metadata] with the Standard Extraction Agent or the Enhanced Extraction Agent.

## Supported file formats

The endpoint supports the following file formats:

<AccordionGroup>
  <Accordion title="Documents">
    * PDF
    * DOC
    * DOCX
    * GDOC
    * ODT
    * Box Note
    * TEXT
    * RTF
    * XDW
    * AS
  </Accordion>

  <Accordion title="Images">
    * TIFF
    * TIF
    * PNG
    * JPEG
    * JPG
    * WEBP
  </Accordion>

  <Accordion title="Presentations and spreadsheets">
    * PPT
    * PPTX
    * GSLIDE
    * GSLIDES
    * ODP
    * OTP
    * XLS
    * XLSX
    * XLSM
    * ODS
    * CSV
  </Accordion>

  <Accordion title="Code files">
    * Languages: `.js`, `.py`, `.css`, `.php`, `.sql`
    * JSON
    * HTML
    * XML
    * MD
  </Accordion>
</AccordionGroup>

Box AI applies optical character recognition (OCR) when processing image files and scanned documents. This removes the need to convert images to PDF before extraction.

## Supported languages

Box AI can extract metadata from documents in the following languages:

* English
* Japanese
* Chinese
* Korean

- Cyrillic-based languages (such as Russian, Ukrainian, Bulgarian, and Serbian)

You don't need additional configuration to use different languages or image formats. Box AI detects the language and applies OCR when needed.

## Before you start

Complete the steps in <Link href="/guides/box-ai/ai-tutorials/prerequisites">getting started with Box AI</Link> to create a platform app and authenticate.

## Send a request

To send a request, use the
`POST /2.0/ai/extract_structured` endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST 'https://api.box.com/2.0/ai/extract_structured' \
       -H 'content-type: application/json' \
       -H 'authorization: Bearer <ACCESS_TOKEN>' \
       -d '{
          "items": [
            {
              "id": "12345678",
              "type": "file",
              "content": "This is file content."
            }
          ],
          "fields": [
            {
              "key": "name",
              "description": "The name of the person.",
              "displayName": "Name",
              "prompt": "The name is the first and last name from the email address.",
              "type": "string",
              "options": [
                {
                  "key": "First Name"
                },
                {
                  "key": "Last Name"
                }
              ]
            }
          ],
          "ai_agent": {
            "type": "ai_agent_extract_structured",
            "long_text": {
              "model": "openai__gpt_5_mini"
            },
            "basic_text": {
              "model": "openai__gpt_5_mini"
            }
          }
        }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.ai.createAiExtractStructured({
    fields: [
      {
        key: 'firstName',
        displayName: 'First name',
        description: 'Person first name',
        prompt: 'What is your first name?',
        type: 'string',
      } satisfies AiExtractStructuredFieldsField,
      {
        key: 'lastName',
        displayName: 'Last name',
        description: 'Person last name',
        prompt: 'What is your last name?',
        type: 'string',
      } satisfies AiExtractStructuredFieldsField,
      {
        key: 'dateOfBirth',
        displayName: 'Birth date',
        description: 'Person date of birth',
        prompt: 'What is the date of your birth?',
        type: 'date',
      } satisfies AiExtractStructuredFieldsField,
      {
        key: 'age',
        displayName: 'Age',
        description: 'Person age',
        prompt: 'How old are you?',
        type: 'float',
      } satisfies AiExtractStructuredFieldsField,
      {
        key: 'hobby',
        displayName: 'Hobby',
        description: 'Person hobby',
        prompt: 'What is your hobby?',
        type: 'multiSelect',
        options: [
          { key: 'guitar' } satisfies AiExtractStructuredFieldsOptionsField,
          { key: 'books' } satisfies AiExtractStructuredFieldsOptionsField,
        ],
      } satisfies AiExtractStructuredFieldsField,
    ],
    items: [new AiItemBase({ id: file.id })],
    aiAgent: agentIgnoringOverridingEmbeddingsModel,
  } satisfies AiExtractStructured);
  ```

  ```python Python v10 theme={null}
  client.ai.create_ai_extract_structured(
      [AiItemBase(id=file.id)],
      fields=[
          CreateAiExtractStructuredFields(
              key="firstName",
              display_name="First name",
              description="Person first name",
              prompt="What is your first name?",
              type="string",
          ),
          CreateAiExtractStructuredFields(
              key="lastName",
              display_name="Last name",
              description="Person last name",
              prompt="What is your last name?",
              type="string",
          ),
          CreateAiExtractStructuredFields(
              key="dateOfBirth",
              display_name="Birth date",
              description="Person date of birth",
              prompt="What is the date of your birth?",
              type="date",
          ),
          CreateAiExtractStructuredFields(
              key="age",
              display_name="Age",
              description="Person age",
              prompt="How old are you?",
              type="float",
          ),
          CreateAiExtractStructuredFields(
              key="hobby",
              display_name="Hobby",
              description="Person hobby",
              prompt="What is your hobby?",
              type="multiSelect",
              options=[
                  CreateAiExtractStructuredFieldsOptionsField(key="guitar"),
                  CreateAiExtractStructuredFieldsOptionsField(key="books"),
              ],
          ),
      ],
      ai_agent=agent_ignoring_overriding_embeddings_model,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Ai.CreateAiExtractStructuredAsync(requestBody: new AiExtractStructured(items: Array.AsReadOnly(new [] {new AiItemBase(id: file.Id)})) { Fields = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsField(key: "firstName") { DisplayName = "First name", Description = "Person first name", Prompt = "What is your first name?", Type = "string" },new AiExtractStructuredFieldsField(key: "lastName") { DisplayName = "Last name", Description = "Person last name", Prompt = "What is your last name?", Type = "string" },new AiExtractStructuredFieldsField(key: "dateOfBirth") { DisplayName = "Birth date", Description = "Person date of birth", Prompt = "What is the date of your birth?", Type = "date" },new AiExtractStructuredFieldsField(key: "age") { DisplayName = "Age", Description = "Person age", Prompt = "How old are you?", Type = "float" },new AiExtractStructuredFieldsField(key: "hobby") { DisplayName = "Hobby", Description = "Person hobby", Prompt = "What is your hobby?", Type = "multiSelect", Options = Array.AsReadOnly(new [] {new AiExtractStructuredFieldsOptionsField(key: "guitar"),new AiExtractStructuredFieldsOptionsField(key: "books")}) }}) });
  ```

  ```swift Swift v10 theme={null}
  try await client.ai.createAiExtractStructured(requestBody: AiExtractStructured(fields: [AiExtractStructuredFieldsField(key: "firstName", displayName: "First name", description: "Person first name", prompt: "What is your first name?", type: "string"), AiExtractStructuredFieldsField(key: "lastName", displayName: "Last name", description: "Person last name", prompt: "What is your last name?", type: "string"), AiExtractStructuredFieldsField(key: "dateOfBirth", displayName: "Birth date", description: "Person date of birth", prompt: "What is the date of your birth?", type: "date"), AiExtractStructuredFieldsField(key: "age", displayName: "Age", description: "Person age", prompt: "How old are you?", type: "float"), AiExtractStructuredFieldsField(key: "hobby", displayName: "Hobby", description: "Person hobby", prompt: "What is your hobby?", type: "multiSelect", options: [AiExtractStructuredFieldsOptionsField(key: "guitar"), AiExtractStructuredFieldsOptionsField(key: "books")])], items: [AiItemBase(id: file.id)]))
  ```

  ```java Java v10 theme={null}
  client.getAi().createAiExtractStructured(new AiExtractStructured.Builder(Arrays.asList(new AiItemBase(file.getId()))).fields(Arrays.asList(new AiExtractStructuredFieldsField.Builder("firstName").description("Person first name").displayName("First name").prompt("What is your first name?").type("string").build(), new AiExtractStructuredFieldsField.Builder("lastName").description("Person last name").displayName("Last name").prompt("What is your last name?").type("string").build(), new AiExtractStructuredFieldsField.Builder("dateOfBirth").description("Person date of birth").displayName("Birth date").prompt("What is the date of your birth?").type("date").build(), new AiExtractStructuredFieldsField.Builder("age").description("Person age").displayName("Age").prompt("How old are you?").type("float").build(), new AiExtractStructuredFieldsField.Builder("hobby").description("Person hobby").displayName("Hobby").prompt("What is your hobby?").type("multiSelect").options(Arrays.asList(new AiExtractStructuredFieldsOptionsField("guitar"), new AiExtractStructuredFieldsOptionsField("books"))).build())).aiAgent(agentIgnoringOverridingEmbeddingsModel).build())
  ```

  ```java Java v5 theme={null}
  BoxAIExtractMetadataTemplate template = new BoxAIExtractMetadataTemplate("templateKey", "enterprise");
  BoxAIExtractStructuredResponse result = BoxAI.extractMetadataStructured(
      api,
      Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)),
      template
  );
  JsonObject sourceJson = result.getSourceJson();
  ```
</CodeGroup>

### Parameters

The following parameters apply to this request. Mandatory parameters are in **bold**.

The `items` array must contain exactly one element. For prompt and file limits, see <Link href="/guides/box-ai/index#input-limits">input limits</Link>.

| Parameter | Description | Example |
| - | - | - |
| **`metadata_template`** | The metadata template containing the fields to extract. For your request to work, you must provide either `metadata_template` or `fields`, but not both. | |
| **`metadata_template.type`** | The type of metadata template. | `metadata_template` |
| **`metadata_template.scope`** | The scope of the metadata template, which can be `global` or `enterprise`. Global templates are available to any Box enterprise. Enterprise templates are bound to a specific enterprise. | `enterprise` |
| **`metadata_template.template_key`** | The name of your metadata template. | `invoice` |
| **`items.id`** | The Box file ID of the document. The ID must reference a file with an extension. | `1233039227512` |
| **`items.type`** | The type of the supplied input. | `file` |
| `ai_agent` | Overrides the default model configuration. You can change the model, prompt template, system message, or LLM parameters. See <Link href="/guides/box-ai/index#the-ai_agent-override-system">the override system</Link> for how it works and <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">AI model overrides</Link> for examples. | |
| `include_confidence_score` | A flag to indicate whether to include the confidence score for every extracted field. | `true` |
| `include_reference` | A flag to indicate whether to include references for every extracted field. | `true` |
| `items.content` | The content of the item, often the text representation. | `This article is about Box AI`. |
| `fields.description` | A description of the field. | `The person's name.` |
| `fields.displayName` | The display name of the field. | `Name` |
| `fields.key` | A unique identifier for the field. | `name` |
| `fields.namespace` | The namespace of the taxonomy source. Required when you use a `taxonomy` field from an existing taxonomy. | `string` |
| `fields.options` | A list of options for this field. This is most often used in combination with the `enum` and `multiSelect` field types. | `[{"key":"First Name"},{"key":"Last Name"}]` |
| `fields.options.key` | A unique identifier for the option. | `First Name` |
| `fields.prompt` | Additional context about the key (identifier) that can include how to find and format it. | `Name is the first and last name from the email address` |
| `fields.type` | The type of the field. Types include, but are not limited to, `string`, `float`, `date`, `enum`, `multiSelect`, `struct`, and `table`. | `string` |
| `fields.taxonomy_key` | The identifier for a taxonomy, which corresponds to the `key` of the taxonomy source. Required when you use a `taxonomy` field. | `string` |

### `struct` and `table` field types

The Box AI `extract_structured` API supports two complex field types, `struct` and
`table`, in addition to the scalar types (`string`, `float`, `date`, `enum`,
and `multiSelect`).
The `struct` and `table` types enable you to extract grouped and repeating structured
data from documents.

<Tip>
  For best results, use the [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent).
</Tip>

#### `struct` field type

Use the `struct` type to group multiple related sub-fields into a single named JSON object.
This is useful when you want to extract a set of related values that belong together and
receive them as one structured object rather than separate flat fields.
For example, use it for an address or a person's contact details.

A `struct` field requires a `fields` array that defines its sub-fields. Each sub-field is an
object with the following properties:

* `key`: The unique identifier for the sub-field.
* `type`: The type of the sub-field. Supported types are `string`, `text`, `number`, `float`, `boolean`, `date`, `enum`, `multiSelect`, and `array[<simple_type>]` (for example, `array[string]`). Nested `struct` or `table` types are not supported as sub-fields.
* `displayName`: The display name of the sub-field.
* `description`: A description of the sub-field.
* `prompt`: Additional context about the sub-field that can include how to find and format it.

<Tip>
  You can add a prompt at the `struct` field level when instructions apply to the whole grouped object.
</Tip>

The output is a single JSON object containing the extracted sub-field values.

Example request for the `struct` field type:

```json theme={null}
{
  "fields": [
    {
      "key": "address",
      "displayName": "Address",
      "type": "struct",
      "fields": [
        { "key": "street_name", "type": "string" },
        { "key": "home_number", "type": "string" },
        { "key": "postal_code", "type": "string" },
        { "key": "city", "type": "string" }
      ]
    }
  ]
}
```

Response:

```json theme={null}
{
  "answer": {
    "address": {
      "street_name": "Main St",
      "home_number": "123",
      "postal_code": "94105",
      "city": "San Francisco"
    }
  }
}
```

#### `table` field type

Use the `table` type to extract repeating rows of structured data as an array of JSON objects,
where each object represents one row.

This is useful when a document contains multiple instances of the same data structure,
for example, line items in an invoice or entries in a tax table.

A `table` field requires a `fields` array that defines the columns (sub-fields) of each row.
The sub-field properties and supported types are identical to those of `struct`.

<Tip>
  Table extraction is not limited to visually formatted tables. The `table` type extracts repeating data from a grid, key-value pairs, a form layout, or plain prose.
</Tip>

The output is an array of JSON objects, where each object represents one extracted row.

Example request for the `table` field type:

```json theme={null}
{
  "fields": [
    {
      "key": "line_items",
      "displayName": "Line Items",
      "type": "table",
      "fields": [
        { "key": "description", "type": "string" },
        { "key": "quantity", "type": "float" },
        { "key": "amount", "type": "float" }
      ]
    }
  ]
}
```

Response:

```json theme={null}
{
  "answer": {
    "line_items": [
      { "description": "Desk", "quantity": 2.0, "amount": 399.99 },
      { "description": "Chair", "quantity": 4.0, "amount": 149.99 }
    ]
  }
}
```

#### Supported sub-field types

Both `struct` and `table` fields support the following types.

| Type | Notes |
| - | - |
| `string` | Scalar or array\[string] |
| `text` | Scalar or array\[text] |
| `number` | Scalar or array\[number] |
| `float` | Scalar or array\[float] |
| `boolean` | Scalar or array\[boolean] |
| `date` | Scalar or array\[date] |
| `enum` | Single occurrence only |
| `multiSelect` | Single occurrence only |

<Warning>
  Nested `struct` and `table` types are not supported as sub-fields.
</Warning>

<Card title="Tutorial: Turn supplier agreements into structured procurement data" icon="file-contract" href="/tutorials/supplier-agreements">
  See the `struct` and `table` field types in action. Extract grouped vendor details and a repeating delivery schedule from a supplier agreement, then map the result to a downstream procurement record.
</Card>

### `include_confidence_score` parameter

The `include_confidence_score` parameter returns confidence scores for each extracted field. These scores show how likely it is that the extracted information is correct. Box provides both a number score and a simple rating (Low, Medium, or High) so you and automated tools can quickly see how reliable the results are.

To calculate confidence, Box generates multiple answers for the same request in slightly different ways (such as changing settings, rephrasing prompts, or rearranging fields) and evaluates the consistency and frequency of the returned values. Box then turns these signals into probabilities that reflect actual accuracy.

* High confidence (0.90 or higher) means the value is very likely correct, and little or no human review is needed.
* Medium confidence (0.70 – 0.89) means the value is likely correct, and a quick check is recommended, depending on your risk tolerance.
* Low confidence (below 0.70) means the value is uncertain, and a human review is strongly recommended.

### `include_reference` parameter

The `include_reference` parameter returns supporting citations and bounding boxes for extracted values. These help you validate extracted values against the source document.

A **reference** is a short text excerpt from the source file that supports an extracted value.
A **bounding box** identifies the region on the page where that supporting text is located.

Box AI calculates bounding boxes from the page-based OCR representation and returns them only for [files supported by OCR](/guides/box-ai/index#ocr-and-file-format-support).

To include references in the response, set `include_reference` to `true`.

```json theme={null}
{
  "items": [...],
  "fields": [...],
  "include_reference": true
}
```

#### Response structure

The response includes:

* `answer`: The extracted metadata fields.
* `references`: Supporting citations for each extracted field.

Each reference contains:

* `item_id`: The source file ID.
* `page`: The zero-indexed page number.
* `bounding_box`: The location of the cited text, when available.
* `text`: The cited text excerpt.

#### Response schema example

```json theme={null}
{
  "answer": {
    "vendor": "Quasar Innovations",
    "document_total": 1050,
    "document_type": "Purchase Order"
  },
  "references": {
    "document_type": [
      {
        "item_id": "314",
        "page": 0,
        "bounding_box": {
          "left": 0.1,
          "top": 0.1,
          "right": 0.3,
          "bottom": 0.5
        },
        "text": "Vendor Company: Acme"
      }
    ],
    "contract": [
      {
        "item_id": "314",
        "page": 0,
        "bounding_box": {
          "left": 0.1,
          "top": 0.1,
          "right": 0.3,
          "bottom": 0.5
        },
        "text": "For: $1234"
      }
    ],
    "start_date": [
      {
        "item_id": "314",
        "page": 0,
        "bounding_box": {
          "left": 0.1,
          "top": 0.1,
          "right": 0.3,
          "bottom": 0.5
        },
        "text": "Contracted on: 2023-12-02"
      }
    ],
    "services": [
      [
        {
          "item_id": "314",
          "page": 1,
          "bounding_box": {
            "left": 0.1,
            "top": 0.1,
            "right": 0.3,
            "bottom": 0.5
          },
          "text": "Cloud Computing"
        }
      ],
      [
        {
          "item_id": "314",
          "page": 1,
          "bounding_box": {
            "left": 0.1,
            "top": 0.1,
            "right": 0.3,
            "bottom": 0.5
          },
          "text": "Data Analytics"
        }
      ],
      [
        {
          "item_id": "314",
          "page": 1,
          "bounding_box": {
            "left": 0.1,
            "top": 0.1,
            "right": 0.3,
            "bottom": 0.5
          },
          "text": "Technical Support"
        }
      ]
    ]
  }
}
```

#### Bounding box format

A bounding box is an object with four normalized coordinates:

* `left`: The normalized x-coordinate of the left edge of the bounding box.
* `top`: The normalized y-coordinate of the top edge of the bounding box.
* `right`: The normalized x-coordinate of the right edge of the bounding box.
* `bottom`: The normalized y-coordinate of the bottom edge of the bounding box.

These values range from 0 to 1, where (0,0) is the top-left corner and (1,1) is the bottom-right corner of the page.

For example:

```json theme={null}
{
  "left": 0.20,
  "top": 0.10,
  "right": 0.60,
  "bottom": 0.30
}
```

<Note>
  Every extracted metadata field has an associated list of references.
  For multi-value fields, each extracted value has its own list of references, resulting in a nested list structure.
  `bounding_box` is optional and can be `null`.
</Note>

## Use cases

This example shows you how to extract metadata from a sample invoice.
Extract the vendor name, invoice number, and a few more details.

<Frame>
  <img alt="Invoice for Quasar Innovations with a vendor, invoice number, purchase order number, two line items, and a total of $1,050" />
</Frame>

### Create the request

To get the response from Box AI, call the `POST /2.0/ai/extract_structured` endpoint with the following parameters:

* `items.type` and `items.id` to specify the file to extract data from
* `fields` to specify the data to extract from the file
* `metadata_template` to supply an existing metadata template

<Note>
  You can use either `fields` or `metadata_template` to specify your structure, but not both.
</Note>

### Use `fields` parameter

The `fields` parameter enables you to specify the data you want to extract. Each `fields` object includes parameters you can use to describe that data.
For example, you can add the field type, description, or a prompt with additional context.

```bash theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/ai/extract_structured' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "items": [
        {
            "id": "1517628697289",
            "type": "file"
        }
    ],
    "fields": [
        {
            "key": "document_type",
            "type": "enum",
            "prompt": "What type of document is this?",
            "options": [
                {
                    "key": "Invoice"
                },
                {
                    "key": "Purchase Order"
                },
                {
                    "key": "Unknown"
                }
            ]
        },
        {
            "key": "document_date",
            "type": "date"
        },
        {
            "key": "vendor",
            "description": "The name of the entity.",
            "prompt": "Which vendor is sending this document?",
            "type": "string"
        },
        {
            "key": "document_total",
            "type": "float"
        }
    ]
  }'
```

The response lists the specified fields and their values:

```json theme={null}
{
    "document_date": "2024-02-13",
    "vendor": "Quasar Innovations",
    "document_total": 1050,
    "document_type": "Purchase Order"
}
```

### Use metadata template

If you prefer to use a metadata template, you can provide its `template_key`, `type`, and `scope`.

```bash theme={null}
curl -i -L -X POST 'https://api.box.com/2.0/ai/extract_structured' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--data '{
    "items": [
        {
            "id": "1517628697289",
            "type": "file"
        }
    ],
    "metadata_template": {
        "template_key": "rbInvoicePO",
        "type": "metadata_template",
        "scope": "enterprise_1134207681"
    }
}'
```

The response lists the fields included in the metadata template and their values:

```json theme={null}
{
  "documentDate": "February 13, 2024",
  "total": "$1050",
  "documentType": "Purchase Order",
  "vendor": "Quasar Innovations",
  "purchaseOrderNumber": "003"
}
```

### Enhanced Extract Agent

To use the Enhanced Extract Agent, specify the `ai_agent` object as follows:

```json theme={null}
{
  "ai_agent": {
    "type": "ai_agent_id",
    "id": "enhanced_extract_agent"
  }
}
```

To extract data using the Enhanced Extract Agent, you need one of the following:

* [Inline field definitions][inline-field] (best when fields change frequently)
* [Metadata template][metadata-template] (best when fields stay consistent)

See the following sample, which uses the Box Python SDK:

```python theme={null}
from box_sdk_gen import (
    AiAgentReference,
    AiAgentReferenceTypeField,
    AiItemBase,
    AiItemBaseTypeField,
    BoxClient,
    BoxCCGAuth,
    CCGConfig,
    CreateAiExtractStructuredMetadataTemplate
)

# Create your client credentials grant config from the Developer Console
ccg_config = CCGConfig(
    client_id="my_box_client_id", # replace with your client ID
    client_secret="my_box_client_secret", # replace with your client secret
    user_id="my_box_user_id", # replace with the Box user ID that has access
                              # to the file you are referencing
)
auth = BoxCCGAuth(config=ccg_config)
client = BoxClient(auth=auth)
# Create the agent config referencing the Enhanced Extract Agent
enhanced_extract_agent_config = AiAgentReference(
    id="enhanced_extract_agent",
    type=AiAgentReferenceTypeField.AI_AGENT_ID
)
# Use the Box SDK to call the extract_structured endpoint
box_ai_response = client.ai.create_ai_extract_structured(
    # Create the items array containing the file information to extract from
    items=[
        AiItemBase(
            id="my_box_file_id", # replace with the file ID
            type=AiItemBaseTypeField.FILE
        )
    ],
    # Reference the Box metadata template
    metadata_template=CreateAiExtractStructuredMetadataTemplate(
        template_key="InvoicePO",
        scope="enterprise"
    ),
    # Attach the agent config you created earlier
    ai_agent=enhanced_extract_agent_config,
)
print(f"box_ai_response: {box_ai_response.answer}")
```

[templates-console]: https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates

[changelog]: /changelog

[blog]: https://medium.com/box-developer-blog

[inline-field]: #use-fields-parameter

[metadata-template]: #use-metadata-template

[autofill-metadata]: https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata#h_01JJSRYKDKXHGJT9ZHCW1E9RX5

<Card title="Tutorial: Automate invoice intake with Box AI Extract" icon="file-invoice" href={localizeLink("/tutorials/invoice-intake")}>
  See structured extraction in action. Build an end-to-end automation that watches a folder, extracts invoice fields, and writes metadata back to each file.
</Card>

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Extract APIs overview and use cases
Source: https://developer.box.com/guides/box-ai/ai-tutorials/extract-use-cases

Explore Box AI Extract use cases including structured and freeform metadata extraction, and how to run extraction jobs across many documents in parallel with one file per request.

Data extraction can be challenging because source content varies widely with different layouts, templates, and file types. The Box Extract API provides two AI-powered endpoints: structured extraction and freeform extraction that standardize how you extract metadata from files in Box. With these endpoints, you can:

* Extract specific fields into a consistent schema or Box metadata template (structured extraction).
* Use enhanced extraction for more complex use cases and improved accuracy powered by advanced AI models (structured extraction).
* Extract content when the target fields are not known ahead of time (freeform extraction).
* Extract from files the caller can access, without a separate permission system around the model.
* Extract data from documents in various languages, file formats, scanned documents, or photos.

To explore the possibilities of these endpoints, discover the following use cases in various industries:

<AccordionGroup>
  <Accordion title="Sales and finance operations">
    **Recommended endpoint:** structured metadata extraction (`POST /2.0/ai/extract_structured`)

    Ideal for high-volume, standardized documents where you need predictable data types:

    * **Automated data entry:** Structured metadata extraction ensures a consistent JSON response every time thanks to a preconfigured metadata template.
    * **Invoices and purchase orders:** Extract line items, totals, and dates.
    * **Client contracts:** Parse standardized fields like "Effective Date" or "Total Contract Value" to update CRM records.
  </Accordion>

  <Accordion title="Legal and HR">
    **Recommended endpoint:** freeform metadata extraction (`POST /2.0/ai/extract`)

    Ideal for queries where document structure is not known ahead of time or varies:

    * **HR onboarding:** Extract key personal details from diverse offer letters or candidate resumes.
    * **NDA clauses:** Extract specific NDA clauses from legal documents.
  </Accordion>

  <Accordion title="Industry-specific solutions">
    Use advanced features like Optical Character Recognition (OCR) and enhanced extraction agent for regulated sectors:

    <AccordionGroup>
      <Accordion title="Financial services">
        * **Know Your Customer (KYC) documents:** Verify user’s identity by extracting text from scanned passports or driver's licenses.
        * **Loan origination:** Automate income verification by pulling data from scanned utility bills or pay stubs.
      </Accordion>

      <Accordion title="Life Sciences">
        * **Clinical Trial Enrollment:** Extract patient criteria from medical forms to match candidates with trials.
        * **Regulatory submissions:** Organize and validate the data required for submissions such as FDA or EMA.
      </Accordion>

      <Accordion title="Public Sector">
        * **Permit applications:** Accelerate zoning approvals by validating required documentation.
        * **Public records requests:** Automatically classify and prioritize documents for public requests such as Freedom of Information Act (FOIA).
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

## Core benefits of using the Box Extract API

* **Managed scaling:** The Box Extract API is designed to handle queues and rate limits, so you can run high-volume processing.
* **No defensive code:** The Box Extract API is model-agnostic, which enables switching between supported LLMs with minimal code changes and minimizing vendor lock-in.
* **Security and compliance:** All extracted data inherits the enterprise-grade security and governance policies of Box.

## Run extraction across thousands of documents

There is no batch extract endpoint. `POST /2.0/ai/extract` and `POST /2.0/ai/extract_structured` accept exactly one file per request. To process a large repository, list the files and call extract per file, up to your rate limits:

1. Watch an inbox folder with a <Link href="/guides/webhooks">webhook</Link> (`FILE.UPLOADED`), poll folder items, or start from a <Link href="/guides/box-automate/index">Box Automate</Link> workflow.
2. Use an identity that is collaborated on those files. Extraction does not bypass Box permissions.
3. For each file ID, call <Link href="/reference/post-ai-extract-structured">`POST /2.0/ai/extract_structured`</Link> (or <Link href="/reference/post-ai-extract">`POST /2.0/ai/extract`</Link> for freeform). Run many requests concurrently.
4. If the API returns `429 Too Many Requests` with a `Retry-After` header, wait a moment and retry. See <Link href="/guides/api-calls/permissions-and-errors/rate-limits">Box API rate limits</Link> (allows around 1000 general requests per minute per user, plus enterprise licensing).
5. Store the JSON on the file as a <Link href="/guides/metadata/instances">metadata instance</Link> so downstream search and workflows can use the fields.

Use Box Automate when you want extraction as a workflow step with branching and human review.

<CardGroup>
  <Card title="Invoice intake automation" icon="file-invoice" href={localizeLink("/tutorials/invoice-intake")}>
    Webhook on a folder, one structured extract per PDF, metadata write-back — the same fan-out pattern at a smaller scale.
  </Card>

  <Card title="Supplier agreement extraction" icon="file-contract" href={localizeLink("/tutorials/supplier-agreements")}>
    Structured extract with `struct` and `table` fields for complex contracts. Repeat per file for a contract library.
  </Card>
</CardGroup>

## Next steps

Get started with the Box Extract API with practical example-led quick start guides, API reference pages, and extensive developer guides:

<RelatedLinks title="RELATED GUIDES" />


# Generate text with Box AI
Source: https://developer.box.com/guides/box-ai/ai-tutorials/generate-text

Use the POST /ai/text_gen endpoint to generate or refine text based on file content stored in Box.

You can use Box AI to generate text
based on provided content.
For example, you can ask Box AI to
generate a template based
on the content you read or create in Box Notes.
Then you can embed the generated text
directly into your document.

## Before you start

Make sure you followed the steps listed in <Link href="/guides/box-ai/ai-tutorials/prerequisites">getting started with Box AI</Link> to create a platform app and authenticate.

## Send a request

To send a request, use the
`POST /2.0/ai/text_gen` endpoint.

<CodeGroup>
  ```sh cURL theme={null}
  curl -i -L -X POST "https://api.box.com/2.0/ai/text_gen" \
       -H "content-type: application/json" \
       -H "authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
            "prompt": "Write a social media post about protein powder.",
            "items": [
              {
                "id": "12345678",
                "type": "file",
                "content": "More information about protein powders"
              }
            ],
            "dialogue_history": [
              {
                "prompt": "Can you add some more information?",
                "answer": "Public API schemas provide necessary information to integrate with APIs...",
                "created_at": "2013-12-12T11:20:43-08:00"
              }
            ],
            "ai_agent": {
              "type": "ai_agent_text_gen",
              "basic_gen": {
                "model": "openai__gpt_5_mini"
              }
            }
       }'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.ai.createAiTextGen({
    prompt: 'Parapharse the document.s',
    items: [
      new AiTextGenItemsField({
        id: fileToAsk.id,
        type: 'file' as AiTextGenItemsTypeField,
        content:
          'The Earth goes around the sun. Sun rises in the East in the morning.',
      }),
    ],
    dialogueHistory: [
      {
        prompt: 'What does the earth go around?',
        answer: 'The sun',
        createdAt: dateTimeFromString('2021-01-01T00:00:00Z'),
      } satisfies AiDialogueHistory,
      {
        prompt: 'On Earth, where does the sun rise?',
        answer: 'East',
        createdAt: dateTimeFromString('2021-01-01T00:00:00Z'),
      } satisfies AiDialogueHistory,
    ],
    aiAgent: aiTextGenAgentConfig,
  } satisfies AiTextGen);
  ```

  ```python Python v10 theme={null}
  client.ai.create_ai_text_gen(
      "Parapharse the document.s",
      [
          CreateAiTextGenItems(
              id=file_to_ask.id,
              type=CreateAiTextGenItemsTypeField.FILE,
              content="The Earth goes around the sun. Sun rises in the East in the morning.",
          )
      ],
      dialogue_history=[
          AiDialogueHistory(
              prompt="What does the earth go around?",
              answer="The sun",
              created_at=date_time_from_string("2021-01-01T00:00:00Z"),
          ),
          AiDialogueHistory(
              prompt="On Earth, where does the sun rise?",
              answer="East",
              created_at=date_time_from_string("2021-01-01T00:00:00Z"),
          ),
      ],
      ai_agent=ai_text_gen_agent_config,
  )
  ```

  ```cs .NET v10 theme={null}
  await client.Ai.CreateAiTextGenAsync(requestBody: new AiTextGen(prompt: "Parapharse the document.s", items: Array.AsReadOnly(new [] {new AiTextGenItemsField(id: fileToAsk.Id, type: AiTextGenItemsTypeField.File) { Content = "The Earth goes around the sun. Sun rises in the East in the morning." }})) { DialogueHistory = Array.AsReadOnly(new [] {new AiDialogueHistory() { Prompt = "What does the earth go around?", Answer = "The sun", CreatedAt = Utils.DateTimeFromString(dateTime: "2021-01-01T00:00:00Z") },new AiDialogueHistory() { Prompt = "On Earth, where does the sun rise?", Answer = "East", CreatedAt = Utils.DateTimeFromString(dateTime: "2021-01-01T00:00:00Z") }}) });
  ```

  ```swift Swift v10 theme={null}
  try await client.ai.createAiTextGen(requestBody: AiTextGen(prompt: "Parapharse the document.s", items: [AiTextGenItemsField(id: fileToAsk.id, type: AiTextGenItemsTypeField.file, content: "The Earth goes around the sun. Sun rises in the East in the morning.")], dialogueHistory: [AiDialogueHistory(prompt: "What does the earth go around?", answer: "The sun", createdAt: try Utils.Dates.dateTimeFromString(dateTime: "2021-01-01T00:00:00Z")), AiDialogueHistory(prompt: "On Earth, where does the sun rise?", answer: "East", createdAt: try Utils.Dates.dateTimeFromString(dateTime: "2021-01-01T00:00:00Z"))]))
  ```

  ```java Java v10 theme={null}
  client.getAi().createAiTextGen(new AiTextGen.Builder("Parapharse the document.s", Arrays.asList(new AiTextGenItemsField.Builder(fileToAsk.getId()).type(AiTextGenItemsTypeField.FILE).content("The Earth goes around the sun. Sun rises in the East in the morning.").build())).dialogueHistory(Arrays.asList(new AiDialogueHistory.Builder().prompt("What does the earth go around?").answer("The sun").createdAt(dateTimeFromString("2021-01-01T00:00:00Z")).build(), new AiDialogueHistory.Builder().prompt("On Earth, where does the sun rise?").answer("East").createdAt(dateTimeFromString("2021-01-01T00:00:00Z")).build())).aiAgent(aiTextGenAgentConfig).build())
  ```

  ```java Java v5 theme={null}
  List<BoxAIDialogueEntry> dialogueHistory = new ArrayList<>();
  dialogueHistory.add(
          new BoxAIDialogueEntry(
              "Make my email about public APIs sound more professional",
              "Here is the first draft of your professional email about public APIs.",
              BoxDateFormat.parse("2013-05-16T15:26:57-07:00")
          )
      );
  BoxAIResponse response = BoxAI.sendAITextGenRequest(
      api,
      "Write an email to a client about the importance of public APIs.",
      Collections.singletonList(new BoxAIItem("123456", BoxAIItem.Type.FILE)),
      dialogueHistory
  );
  ```

  ```python Python v4 theme={null}
  items = [{
      "id": "1582915952443",
      "type": "file",
      "content": "More information about public APIs"
  }]
  dialogue_history = [{
          "prompt": "Make my email about public APIs sound more professional",
          "answer": "Here is the first draft of your professional email about public APIs",
          "created_at": "2013-12-12T10:53:43-08:00"
      },
      {
          "prompt": "Can you add some more information?",
          "answer": "Public API schemas provide necessary information to integrate with APIs...",
          "created_at": "2013-12-12T11:20:43-08:00"
  }]
  ai_agent = {
      'type': 'ai_agent_text_gen',
      'basic_gen': {
          'model': 'openai__gpt_3_5_turbo_16k'
      }
  }
  answer = client.send_ai_text_gen(
      dialogue_history=dialogue_history,
      items=items,
      prompt="Write an email to a client about the importance of public APIs.",
      ai_agent=ai_agent
  )
  print(answer)
  ```

  ```cs .NET v6 theme={null}
  BoxAIResponse response = await client.BoxAIManager.SendAITextGenRequestAsync(
      new BoxAITextGenRequest
      {
          Prompt = "What is the name of the file?",
          Items = new List<BoxAITextGenItem>() { new BoxAITextGenItem() { Id = "12345" } },
          DialogueHistory = new List<BoxAIDialogueHistory>()
          {
              new BoxAIDialogueHistory() { Prompt = "What is the name of the file?", Answer = "MyFile", CreatedAt = DateTimeOffset.Parse("2024-05-16T15:26:57-07:00") }
              new BoxAIDialogueHistory() { Prompt = "What is the size of the file?", Answer = "10kb", CreatedAt =  DateTimeOffset.Parse("2024-05-16T15:26:57-07:00") }
          }
      };
  );
  ```

  ```javascript Node v4 theme={null}
  client.ai.textGen(
      {
          prompt: 'What is the capital of France?',
          items: [
              {
                  type: 'file',
                  id: '12345'
              }
          ],
          dialogue_history: [
              {
                  prompt: 'What is the capital of France?',
                  answer: 'Paris',
                  created_at: '2021-10-01T00:00:00Z'
              },
              {
                  prompt: 'What is the capital of Germany?',
                  answer: 'Berlin',
                  created_at: '2021-10-01T00:00:00Z'
              }
          ]
      })
      .then(response => {
          /* response -> {
              "answer": "The capital of France is Paris.",
              "created_at": "2021-10-01T00:00:00Z",
              "completion_reason": "done"
          } */
      });
  ```
</CodeGroup>

### Parameters

To make a call, you must pass the following parameters. Mandatory parameters are in **bold**.

The `items` array must contain exactly one element. For full details on prompt and file limits, see <Link href="/guides/box-ai/index#input-limits">input limits</Link>.

| Parameter | Description | Example |
| - | - | - |
| **`prompt`** | The request for Box AI to generate or refine the text. Maximum 10,000 characters. | Create a meeting agenda for a weekly sales meeting. |
| **`items.id`** | Box file ID of the document. | `1233039227512` |
| **`items.type`** | The type of the supplied input. | `file` |
| `items.content` | The content of the item, often the text representation. | `This article is about Box AI`. |
| `dialogue_history.prompt` | The prompt previously provided by the client and answered by the Large Language Model (LLM). | `Make my email about public APIs sound more professional` |
| `dialogue_history.answer` | The answer previously provided by the LLM. | `Here is a draft of your professional email about public APIs.` |
| `dialogue_history.created_at` | The ISO date formatted timestamp of when the previous answer to the prompt was created. | `2012-12-12T10:53:43-08:00` |
| `ai_agent` | Override the default model configuration. Lets you change the model, prompt template, system message, or LLM parameters. See <Link href="/guides/box-ai/index#the-ai_agent-override-system">the override system</Link> for how it works and <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">AI model overrides</Link> for examples. | |

## Use cases

Generate text based on the provided file content and a prompt.

```sh theme={null}
curl -i -L -X POST "https://api.box.com/2.0/ai/text_gen" \
     -H "content-type: application/json" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
    "items": [
        {
            "id": "12345678",
            "type": "file"
        }
    ],
    "prompt": "Create a short blog post that provides information on Box AI for Documents and focuses on best practices for asking questions. You can add emoticons, but not too many."
}'
```

The result will be as follows:

```sh theme={null}
{
    "answer": "📝 **Box AI for Documents: Best Practices for Asking Questions** 🤔\n\n---\n\nWelcome to our blog post on Box AI for Documents! 🎉 Today, we're going to dive into some best practices when it comes to asking questions within this innovative platform.\n\n1. **Be Clear and Concise**: When formulating a question in Box Notes, make sure your query is clear and to the point. This helps Box AI understand exactly what you're looking for.\n\n2. **Provide Context**: Giving context around your question can significantly improve the accuracy of the response generated by Box AI. Include relevant details or background information.\n\n3. **Use Keywords**: Utilize keywords related to your query within the question itself. This can help Box AI better identify the main topic of your inquiry.\n\n4. **Avoid Ambiguity**: Try to avoid vague or ambiguous questions that could lead to misunderstandings. The more precise you are, the better Box AI can assist you.\n\n5. **Review Suggestions Carefully**: After receiving suggestions from Box AI, take the time to review them carefully before incorporating them into your document. Ensure they align with your intended message.\n\nBy following these best practices, you can maximize the effectiveness of Box AI for Documents and streamline your workflow like never before! 💼✨\n\nStay tuned for more tips and tricks on leveraging technology for enhanced productivity! 👩‍💻🚀",
    "created_at": "2024-11-04T02:46:23.459-08:00",
    "completion_reason": "done"
}
```

<RelatedLinks title="RELATED GUIDES" />


# Get started with Box AI
Source: https://developer.box.com/guides/box-ai/ai-tutorials/prerequisites

Create a platform app, enable the AI scope, and generate a developer token to start using the Box AI API.

To implement Box AI API in your solutions, you need
to make sure you have access to the functionality.
You will also need a platform application with
enabled Box AI scope, and a developer token to
authenticate your calls.

<SignupCTA>
  A free developer account gives you access to the Box AI API. Try document summarization, question answering, and metadata extraction through the API.
</SignupCTA>

<Note>
  To use Box AI API, make sure it is enabled by an
  admin in the Admin Console. If you want to use
  the Box AI APIs in your sandbox, request access
  from the Box AI team using [this form][form].
</Note>

## Create a platform application

First you need to create a platform application
you will use to make calls. To create
an application, follow the guide
on <Link href="/guides/applications/platform-apps/create">creating platform apps</Link>.

## Enable Box AI API access

To interact with Box AI API,
you need the `ai.readwrite` <Link href="/guides/api-calls/permissions-and-errors/scopes">scope</Link>
added for your application.
Before you add the scope,
make sure that the Box Admin has granted you
the access to Box AI API. If you can't see the
**Manage AI** option in your app configuration
settings, contact your admin.

To add a scope:

1. Open your application in Developer Console.

2. Go to **Configuration** > **Required Access Scopes** > **Content Actions**.

3. Select the **Manage AI** scope. Box automatically includes the scope when making the call. If you are added as a collaborator for a given app, but do not have Box AI API access, you see the **Manage AI** scope checked and grayed out. This means the app owner has the AI scope enabled but you cannot change this setting.

   <Frame>
     <img alt="box ai scopes" />
   </Frame>

4. Submit your app for <Link href="/guides/authorization">authorization or enablement</Link>. If you want to enable Box AI API for an existing application, you must <Link href="/guides/authorization/platform-app-approval#re-authorization-on-changes">re-authorize</Link> it.

## Generate a developer token

You need a developer token
to authenticate your app when sending requests.

To generate a token:

1. Go to **Developer Console** > **My Platform Apps**.
2. Click the **Options menu** button (…) on the right.
3. Select **Generate Developer Token**. The token will be automatically generated and saved to clipboard.

<Frame>
  <img alt="generate token" />
</Frame>

You can also open your app, go to
**Configuration** > **Developer Token**
and generate the token.

<Note>
  A developer token is only valid for one hour.
</Note>

For additional details, see <Link href="/guides/authentication/tokens/developer-tokens">developer token</Link>.
After you generate the token, you can use it in cURL
or other clients, such as <Link href="/guides/tooling/postman">Postman</Link>, to make
calls.

[oauthscopes]: /guides/api-calls/permissions-and-errors/scopes#scopes-oauth-2-authorization

[form]: https://forms.gle/Nsh3TwM3W8qg4U35A

<RelatedLinks title="RELATED GUIDES" />


# Box AI
Source: https://developer.box.com/guides/box-ai/index

Ask questions, extract metadata, and summarize files stored in Box with the Box AI API. Covers request handling, input limits, and agent overrides.

Use the Box AI API to ask questions, extract metadata, and summarize files stored in Box. These guides cover how Box AI processes requests, what limits apply to each endpoint, and how to control model behavior with agent overrides.

For capabilities, quick starts, and reference links, see the [Box AI API](/ai/box-ai-api) page.

<SignupCTA>
  A free developer account gives you access to the Box AI API, Developer Console, and everything you need to start building.
</SignupCTA>

## How requests are processed

When you send a request to a Box AI endpoint, Box handles the model infrastructure for you. Your request flows through the following stages:

* **File retrieval**: Box reads the file content from the `items` array you provide. If you include the optional `content` parameter, that text is used as the primary input instead of the file's stored content. For `POST /ai/ask`, an `items` entry can also be a [Box Hub](/guides/hubs-api/index) (`"type": "hubs"`), in which case Box searches the hub's indexed content instead of a single file. See [Ask questions about a hub](/guides/box-ai/ai-tutorials/ask-questions#ask-questions-about-a-hub).
* **Representation generation**: For text-based files, Box converts the document into a text representation. For images, Box applies OCR automatically on supported endpoints.
* **Model routing**: Box routes the request to the default model for that endpoint and mode. You can override this with the `ai_agent` parameter.
* **Response generation**: The LLM processes your prompt against the file content and returns a result. Box handles token windowing for long documents (splitting content into chunks with embeddings for `long_text` configurations).

<Note>
  Box AI does not support multi-modal requests. If you send both images and text in the same request, only the text is processed.
</Note>

## Input limits

The limits below apply across Box AI endpoints. Exceeding these limits does not produce an error in most cases; Box truncates to the limit and processes what it can.

### Text and prompt limits

| Constraint | Limit |
| - | - |
| Prompt length | 10,000 characters |
| Single file text representation (`single_item_qa`) | 2 MB of text. Content beyond 2 MB is truncated. |
| Multiple files (`multiple_item_qa`) | Up to 25 files |
| Items array for `text_gen` | Exactly 1 file |
| Items array for `extract` and `extract_structured` | Exactly 1 file |

To process many documents, call extract once per file and run them in parallel. See <Link href="/guides/box-ai/ai-tutorials/extract-use-cases#run-extraction-across-thousands-of-documents">Run extraction across thousands of documents</Link>.

### Image limits

| Constraint | Limit |
| - | - |
| Resolution | 1024 x 1024 pixels |
| Maximum images or pages per request | 5. If more are provided, only the first 5 are processed. |

### OCR and file format support

OCR is **not** available on all endpoints.

| Endpoint | OCR | Supported file formats |
| - | - | - |
| `POST /ai/text_gen` | No | Text-based files |
| `POST /ai/extract` | No | Text-based files |
| `POST /ai/extract_structured` | Yes (automatic) | PDF, TIFF, PNG, JPEG |

### Language support

Box AI works in English, Japanese, French, Spanish, and many other languages. However, the underlying models are primarily trained on English, so prompts in other languages may return lower quality results.

The `extract_structured` endpoint has explicit multilingual support for:

* English, Japanese, Chinese, Korean
* Cyrillic-based languages (Russian, Ukrainian, Bulgarian, Serbian)

<Tip>
  Switch the language to Japanese to get better results for this language.
</Tip>

## The `ai_agent` override system

The following Box AI endpoints accept an optional `ai_agent` parameter that lets you override the default model configuration: `POST /ai/ask`, `POST /ai/text_gen`, `POST /ai/extract`, and `POST /ai/extract_structured`. This is how you control which LLM runs, how it behaves, and what instructions it receives.

### When to use overrides

* **Pinning a model version**: Box updates default models regularly. If your downstream process depends on consistent output, pin to a specific model to avoid unexpected changes.
* **Switching models**: Different models produce different results. You can switch to any model in the <Link href="/guides/box-ai/ai-models/index">supported models list</Link> to optimize for your use case.
* **Customizing prompts**: The `prompt_template` and `system_message` parameters let you steer the LLM's behavior without changing your application code.
* **Tuning creativity**: Adjust `temperature` and other `llm_endpoint_params` to control how deterministic or creative the output is.

### How it works

<Steps>
  <Step title="Get the default configuration">
    Call <Link href="/reference/get-ai-agent-default">`GET /2.0/ai_agent_default`</Link> with the `mode` you want (`ask`, `text_gen`, `extract`, or `extract_structured`) to retrieve the current defaults.
  </Step>

  <Step title="Modify the configuration">
    Change the fields you need: `model`, `prompt_template`, `system_message`, `llm_endpoint_params`, or `num_tokens_for_completion`. Leave other fields unchanged.
  </Step>

  <Step title="Pass it back in your request">
    Include the modified configuration as the `ai_agent` parameter in your `POST` request. Box uses your overrides for that request only.
  </Step>
</Steps>

### Configuration structure by endpoint

The `ai_agent` object structure varies by endpoint because each handles content differently:

| Endpoint | Agent type | Configuration keys |
| - | - | - |
| `POST /ai/ask` | `ai_agent_ask` | `basic_text`, `basic_text_multi`, `long_text`, `long_text_multi` |
| `POST /ai/text_gen` | `ai_agent_text_gen` | `basic_gen` |
| `POST /ai/extract` | `ai_agent_extract` | `basic_text`, `long_text` |
| `POST /ai/extract_structured` | `ai_agent_extract_structured` | `basic_text`, `long_text` |

The `ask` endpoint has four configuration keys because it handles both single-item and multi-item modes, and both short and long documents. When using `multiple_item_qa` mode, the `_multi` variants apply.

For `long_text` configurations, Box splits the content into chunks using an embeddings model. You can configure the embeddings model and chunking strategy as part of the override.

### LLM parameter differences by provider

The `llm_endpoint_params` options depend on the model provider:

| Provider | Param type | Key difference |
| - | - | - |
| <Link href="/reference/resources/ai-llm-endpoint-params-openai">OpenAI</Link> | `openai_params` | Use `temperature` **or** `top_p`, not both |
| <Link href="/reference/resources/ai-llm-endpoint-params-google">Google</Link> | `google_params` | `temperature` works with `top_p` and `top_k` together |
| <Link href="/reference/resources/ai-llm-endpoint-params-aws">AWS</Link> | `aws_params` | Same as Google: `temperature` works alongside `top_p` and `top_k` |

For detailed override examples, see the <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">AI model overrides</Link> guide and the <Link href="/guides/box-ai/ai-tutorials/default-agent-overrides">override tutorial</Link>.

### Model versioning

Box guarantees each AI agent configuration snapshot for at least 12 months, with a 6-month transition window when a new version is released. Default model changes are posted in the <Link href="/changelog">developer changelog</Link>. To avoid disruption, pin your agent configuration to a specific model version using overrides.

For full details, see <Link href="/guides/box-ai/ai-agents/ai-agent-versioning">AI agent configuration versioning</Link>.

## Box AI for UI Elements

The <Link href="/guides/embed/ui-elements/preview#box-ai-ui-element">Box AI for UI Elements</Link> integration embeds question-answering directly into Content Preview within your application. This lets end users interact with Box AI without leaving your UI.

## User Activity Reports

[User Activity Reports][uar] track Box AI interactions. Box admins can filter for the following action types:

| Action type | Description |
| - | - |
| **AI query** | The user queried Box AI and received a response |
| **Failed AI query** | The user queried Box AI but did not receive a response |

[uar]: https://support.box.com/hc/en-us/articles/4415012490387-User-Activity-Report

## Guides in this section

<CardGroup>
  <Card title="Tutorials" icon="graduation-cap" href={localizeLink("/guides/box-ai/ai-tutorials/index")}>
    Step-by-step guides for each endpoint: ask, text generation, extraction,
    and model overrides.
  </Card>

  <Card title="Model overrides" icon="sliders" href={localizeLink("/guides/box-ai/ai-agents/index")}>
    Override default models, prompts, and LLM parameters. Includes the
    default configuration reference and versioning policy.
  </Card>

  <Card title="Supported models" icon="microchip" href={localizeLink("/guides/box-ai/ai-models/index")}>
    Full list of core and customer-enabled models with capability tiers,
    compliance badges, and API names.
  </Card>

  <Card title="Quick starts" icon="rocket" href={localizeLink("/ai/box-ai-api#quick-starts")}>
    Get up and running in minutes with Python SDK walkthroughs for
    summarization and extraction.
  </Card>
</CardGroup>

## See Box AI in action

These end-to-end tutorials show how to combine Box AI with other platform capabilities to build production-ready automations.

<CardGroup>
  <Card title="Access-controlled knowledge base" icon="book" href={localizeLink("/guides/hubs-api/access-controlled-knowledge-base")}>
    Curate an enterprise repository into a Hub and ask questions with Box AI. Answers inherit Box permissions.
  </Card>

  <Card title="Invoice intake automation" icon="file-invoice" href={localizeLink("/tutorials/invoice-intake")}>
    Use Box AI Extract and metadata to automate accounts payable - extract vendors, totals, and dates from every invoice.
  </Card>

  <Card title="Sales RFP answer bank" icon="magnifying-glass" href={localizeLink("/tutorials/sales-rfp-answer-bank")}>
    Build an AI-powered knowledge base with Box Hubs and let sales reps query approved proposals in natural language.
  </Card>
</CardGroup>


# Extract structured data with Box AI in Python
Source: https://developer.box.com/guides/box-ai/quick-start/box-ai-extract

Learn how to use Box AI to automatically extract structured data from documents and store it as searchable metadata using the Box Python SDK.

<Link href="/ai">Box AI</Link> exposes intelligent extraction capabilities that enable developers to automatically extract structured
key-value pairs from documents through a single API call. This powerful feature transforms unstructured
document content into actionable metadata without manual data entry, streamlining document processing
workflows for invoices, forms, contracts, and other business documents.

This quick start demonstrates how to configure the Box Python SDK, create a metadata template,
and use Box AI to extract invoice data and store it as searchable metadata in Box.

<SignupCTA>
  A free developer account gives you access to the Box AI API. Try document summarization, question answering, and metadata extraction through the API.
</SignupCTA>

<Steps>
  <Step title="Create and configure a Box application">
    The first step for any Box integration is to create and configure a Box
    application.

    1. Go to <Link href="https://app.box.com/developers/console">Box Developer Console</Link>.
    2. For this quick start, create an App with the `Client Credentials Grant`
       application type.
    3. Once the app is created, enable the following scopes:
       * Read all files and folders stored in Box
       * Write all files and folders stored in Box
       * Manage AI

    For more information about creating a new Box application, see <Link href="/guides/getting-started/first-application#create-your-first-application">Create your first application</Link>.
  </Step>

  <Step title="Create a Box metadata template">
    <Tip>
      This step requires Admin access to your Box Enterprise. If you do not have access
      in your current environment, contact your Box administrator.
    </Tip>

    Box AI enables you to extract data from documents in several ways:

    | Type | Description | Use case |
    | - | - | - |
    | Freeform extraction | Accepts a string prompt. | Provide a natural language prompt. |
    | Structured extraction with template | Accepts a Box Metadata template key. | Define fields and data types once; simplifies pushing back to Box as metadata. |
    | Structured extraction with fields | Accepts a JSON array of fields. | Run one-off extractions without creating a template. |
    | Enhanced Extract Agent | Uses a specialized agent with a reasoning model. | Use for complex documents or nuanced extraction; works with structured templates or fields. |

    For this quick start, create a Box metadata template to define the fields you want
    to extract from your documents. See <Link href="https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates">Customizing Metadata Templates</Link>
    for a detailed walkthrough of the steps to create a Box metadata template in the Box Admin
    Console.

    1. Give your template a name, for example, `Box AI extract quick start`.

    2. Create the following fields:

       | Field name | Type | Description |
       | - | - | - |
       | Client Name | Text | The name of the client receiving the invoice |
       | Invoice Amount | Number | The total amount of the invoice after taxes and fees |
       | Products | Text | The names of the products delivered in the invoice, returned as a comma-delimited string |

       <Tip>
         The field description is used by Box AI to supplement the prompt to the LLM to ensure the
         right data is extracted.
       </Tip>

    3. Click **Save** to create your template. Make note of the template key to use
       in a later step.

    When you save the template, a list of templates appears. To find the template key,
    open the template you just created and inspect the URL. The last part of the path is
    your template key. For example, the URL might look like this:
    `https://app.box.com/master/metadata/templates/boxAiExtractquick start`.

    In this case, the template key is `boxAiExtractquick start`.
  </Step>

  <Step title="Upload a test file">
    After preparing the template, select a file to test. For this quick start, use this
    <Link href="/static/quickstarts/extract/files/demo-invoice-20tax-2.pdf">sample invoice document</Link>.

    1. Download the test document, and then drag and drop it into your Box account.
    2. Get the file ID by opening the file in Box and inspecting the URL.
       The last part of the path is your file ID. For example, the URL might look like this:
       `https://app.box.com/file/2064123286902`

       In this case, the file ID is `2064123286902`.
  </Step>

  <Step title="Configure the environment">
    Now set up your development environment to run the extraction. For this quick start, use Python and the
    Box Python SDK version 10. Make sure you have Python 3.11 or higher installed on your machine.

    1. Create a new directory for your project and navigate into it.
    2. Create a virtual environment:
       ```bash theme={null}
       python3 -m venv .venv
       source .venv/bin/activate
       ```
    3. Install the Box Python SDK:
       ```bash theme={null}
       pip install "boxsdk~=10"
       ```
    4. Install the `python-dotenv` package to load environment variables from the `.env` file:
       ```bash theme={null}
       pip install python-dotenv
       ```
    5. Create an `.env` file in the root of your project directory and add the following
       environment variables, replacing the placeholder values with your actual Box app credentials
       and the IDs from the previous steps:
       ```bash theme={null}
        BOX_DEVELOPER_TOKEN=your_box_developer_token

        BOX_METADATA_TEMPLATE_KEY=your_metadata_template_key
        BOX_FILE_ID=your_box_file_id
       ```

    To get your developer token, go to the Box Developer Console, open your app, and navigate to
    the **Configuration** tab.

    6. Click **Generate Developer Token** to create a new token.

    <Tip>
      For simplicity, this quick start uses a short-lived developer token. In production, you
      should authenticate using your app’s configured method (for example, Client Credentials Grant)
      instead of a developer token.
    </Tip>
  </Step>

  <Step title="Create the extract.py file">
    Your development environment is now ready to create the Python script to extract data from the document using Box AI.

    1. Create a new file named `extract.py` in the root of your project directory and add the following code:

       ```python theme={null}
       import os

       from dotenv import load_dotenv

       from box_sdk_gen import (
           AiItemBase,
           BoxClient,
           BoxDeveloperTokenAuth,
           CreateAiExtractStructuredMetadataTemplate,
           CreateAiExtractStructuredMetadataTemplateTypeField,
           CreateFileMetadataByIdScope
       )

       load_dotenv()

       developer_token = os.getenv("BOX_DEVELOPER_TOKEN")
       file_id = os.getenv("BOX_FILE_ID")
       template_key = os.getenv("BOX_METADATA_TEMPLATE_KEY")

       def get_box_client(token: str) -> BoxClient:
           
           if not developer_token:
               raise ValueError("BOX_DEVELOPER_TOKEN is not set in environment variables.")
           
           auth = BoxDeveloperTokenAuth(token=token)
           client = BoxClient(auth=auth)

           return client

       def main():
           client = get_box_client(token=developer_token)

           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")


       if __name__ == "__main__":
           main()
       ```

       This code loads the environment variables from the `.env` file, initializes the Box SDK client,
       and prints the current user's ID to validate that the client is working correctly.

    2. Run the script using the following command in your terminal:

       ```bash theme={null}
       python extract.py
       ```

       If the Box SDK client is set up correctly, the console displays your user ID. For example:

       ```bash theme={null}
       My user ID is 123456789
       ```
  </Step>

  <Step title="Extract data">
    With a working Box SDK client, you can add the code to extract data from the document using Box AI.

    1. Between the `get_box_client` function and the `main` function, add the following function:

       ```python theme={null}
       def extract_metadata(client: BoxClient, file_id: str, template_key: str) -> dict:
           metadata = client.ai.create_ai_extract_structured(
               [AiItemBase(id=file_id)],
               metadata_template=CreateAiExtractStructuredMetadataTemplate(
                   template_key=template_key,
                   type=CreateAiExtractStructuredMetadataTemplateTypeField.METADATA_TEMPLATE,
                   scope="enterprise",
               ),
           )
           
           return metadata.to_dict()['answer']
       ```

       This function uses the Box AI `create_ai_extract_structured` method to extract metadata from the specified file.
       Your BoxClient, the file ID, and the metadata template key created earlier are sent to the function, which
       returns the extracted metadata as a dictionary.

    2. Add the function call to extract the metadata in the `main` function. Ensure that the new `main` function contains the following logic:

       ```python theme={null}
       def main():
           client = get_box_client(token=developer_token)

           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")

           metadata = extract_metadata(client=client, file_id=file_id, template_key=template_key)

           print(f"Extracted Metadata: {metadata}")
       ```

       The SDK handles the API call to Box AI and returns the extracted metadata as an
       <Link href="/reference/resources/ai-extract-structured-response">`AiExtractStructuredResponse`</Link> object. In this quick start,
       the code converts this object to a dictionary and returns the `answer` field that contains the extracted
       key/value pairs.

    3. Print out the extracted metadata to the console to verify that the extraction was successful by running the following command in your terminal:

       ```bash theme={null}
       python extract.py
       ```

       If the extraction was successful, the console displays your user ID followed by the extracted metadata from the invoice document.

       ```bash theme={null}
       My user ID is 123456789

       Extracted Metadata: {'clientName': 'ACME Inc', 'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate, 
       Carbon Dioxide, Laser, Lens, Oleic Acid, Glycerine, Sodium Tallowate, Paint Base, Polypropylene, Rubber, 
       Additive, Pigment, Aluminum Silicate, Magnesium Silicate, Zinc Oxide, Distilled Solvent, Petroleum Distillate, 
       Sulfur Dioxide, Sodium Benzoate, Dust cap, Ferrite cap, Cone and coil assembly, Cleaner, Polypropylene pellets, 
       Polypropylene chips, Polypropylene blocks, Polypropylene slag, Parts Wash Solvent, Jar, 
       Plastic Bottle - 15.2 FL Oz (450 ml), Polymer'}
       ```
  </Step>

  <Step title="Add Box metadata to the file">
    Now that you have extracted metadata from the document, you can use these key/value pairs in your
    application: push to databases, integrate with CRMs, feed to agents for processing, or trigger automated workflows.

    This quick start demonstrates pushing the extracted data back to Box as file metadata. Box metadata management
    enables powerful filtering and search capabilities across your content. For example, you can query
    all invoices over \$500 from the last 30 days, create dashboards in Box Apps, or surface key document
    insights directly in the Box web application.

    1. Push the extracted metadata back to Box by adding the following function between the `extract_metadata` function
       and the `main` function:

       ```python theme={null}
       def push_metadata(client: BoxClient, file_id: str, metadata: dict, template_key: str) -> dict:
           attached_metadata = client.file_metadata.create_file_metadata_by_id(
               file_id,
               CreateFileMetadataByIdScope.ENTERPRISE,
               template_key,
               metadata,
           )
           return attached_metadata.to_dict()
       ```

       This function uses the `create_file_metadata_by_id` method to attach metadata to the specified file, processing
       the BoxClient, file ID, metadata dictionary, and template key. The API itself returns a
       <Link href="/reference/resources/metadata--full">`MetadataFull`</Link> object. The function converts this object to a
       dictionary and returns it.

    2. Add the function call to push the metadata in the `main` function. Ensure that the updated `main` function
       contains the following logic:

       ```python theme={null}
       def main():
           client = get_box_client(token=developer_token)

           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")

           metadata = extract_metadata(client=client, file_id=file_id, template_key=template_key)

           print(f"Extracted Metadata: {metadata}")

           attached_metadata = push_metadata(client=client, file_id=file_id, metadata=metadata, template_key=template_key)

           print(f"Attached Metadata: {attached_metadata}")
       ```

    3. Run the following command in your terminal:

       ```bash theme={null}
       python extract.py
       ```

       If the script is successful, the console displays your user ID, the extracted metadata, and the attached metadata response from Box. For example:

       ```bash theme={null}
       My user ID is 123456789

       Extracted Metadata: {'clientName': 'ACME Inc', 'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate,
       Carbon Dioxide, Laser, Lens, Oleic Acid, Glycerine, Sodium Tallowate, Paint Base, Polypropylene, Rubber,
       Additive, Pigment, Aluminum Silicate, Magnesium Silicate, Zinc Oxide, Distilled Solvent, Petroleum Distillate,
       Sulfur Dioxide, Sodium Benzoate, Dust cap, Ferrite cap, Cone and coil assembly, Cleaner, Polypropylene pellets,
       Polypropylene chips, Polypropylene blocks, Polypropylene slag, Parts Wash Solvent, Jar,
       Plastic Bottle - 15.2 FL Oz (450 ml), Polymer'}

       Attached Metadata: {'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate, Carbon Dioxide, Laser, Lens, 
       Oleic Acid, Glycerine, Sodium Tallowate, Paint Base, Polypropylene, Rubber, Additive, Pigment, Aluminum Silicate, 
       Magnesium Silicate, Zinc Oxide, Distilled Solvent, Petroleum Distillate, Sulfur Dioxide, Sodium Benzoate, Dust cap, 
       Ferrite cap, Cone and coil assembly, Cleaner, Polypropylene pellets, Polypropylene chips, Polypropylene blocks, 
       Polypropylene slag, Parts Wash Solvent, Jar, Plastic Bottle - 15.2 FL Oz (450 ml), Polymer', 
       'clientName': 'ACME Inc', '$parent': 'file_1956534287859', '$template': 'boxAiExtractquick start', 
       '$scope': 'enterprise_899905961', '$version': 0, '$canEdit': True, '$id': '4d4f0b55-d45a-4ba4-9ff6-1241182cb76a', 
       '$type': 'boxAiExtractquick start-c4024235-2384-49f4-9286-ada6d68fd6a9', '$typeVersion': 0, 'extra_data': 
       {'invoiceAmount': 1106.06, 'products': 'Polyol, Diisocyanate, Carbon Dioxide, Laser, Lens, Oleic Acid, Glycerine, 
       Sodium Tallowate, Paint Base, Polypropylene, Rubber, Additive, Pigment, Aluminum Silicate, Magnesium Silicate, 
       Zinc Oxide, Distilled Solvent, Petroleum Distillate, Sulfur Dioxide, Sodium Benzoate, Dust cap, Ferrite cap, 
       Cone and coil assembly, Cleaner, Polypropylene pellets, Polypropylene chips, Polypropylene blocks, Polypropylene slag, 
       Parts Wash Solvent, Jar, Plastic Bottle - 15.2 FL Oz (450 ml), Polymer', 'clientName': 'ACME Inc'}}
       ```
  </Step>
</Steps>

## Resources

* <Link href="https://github.com/box-community/box-quickstarts/tree/main/box-ai-extract-quickstart">Final code</Link>
* <Link href="/reference/post-ai-extract-structured">Extract Structured Metadata API Reference</Link>
* <Link href="/reference/post-files-id-metadata-id-id">Create metadata instance on file</Link>
* <Link href="https://github.com/box/box-python-sdk/tree/main">Box Python SDK</Link>


# Structured extraction with the Box AI Enhanced Extract Agent in Python
Source: https://developer.box.com/guides/box-ai/quick-start/box-ai-extract-enhanced

Learn how to use the Box AI Enhanced Extract Agent to automatically extract data from large, complex documents using the Box Python SDK.

<Link href="/ai">Box AI</Link> exposes intelligent extraction capabilities that enable developers to automatically extract
key-value pairs from documents through a single API call. The Enhanced Extract Agent uses advanced reasoning models
to transform complex unstructured document content into actionable metadata without manual data entry, streamlining
document processing workflows for invoices, forms, contracts, and other business documents.

This quick start demonstrates how to configure the Box Python SDK and use Box AI to extract data from a stock purchase
agreement stored in Box.

<SignupCTA>
  A free developer account gives you access to the Box AI API. Try document summarization, question answering, and metadata extraction through the API.
</SignupCTA>

<Steps>
  <Step title="Create and configure a Box application">
    The first step for any Box integration is to create and configure a Box
    application.

    1. Go to <Link href="https://app.box.com/developers/console">Box Developer Console</Link>.
    2. For this quick start, create an App with the `Client Credentials Grant`
       application type.
    3. Once the app is created, enable the following scopes:
       * Read all files and folders stored in Box
       * Write all files and folders stored in Box
       * Manage AI

    For more information about creating a new Box application, see <Link href="/guides/getting-started/first-application#create-your-first-application">Create your first application</Link>.
  </Step>

  <Step title="Upload a test file">
    After preparing the template, select a file to test. For this quick start, use this
    <Link href="/static/quickstarts/extract/files/enhanced-extract-file.pdf">sample stock purchase agreement</Link>.

    1. Download the test document, and then drag and drop it into your Box account.
    2. Get the file ID by opening the file in Box and inspecting the URL.
       The last part of the path is your file ID. For example, the URL might look like this:
       `https://app.box.com/file/2064123286902`

       In this case, the file ID is `2064123286902`.
  </Step>

  <Step title="Configure the environment">
    Now set up your development environment to run the extraction. For this quick start, use Python and the
    Box Python SDK version 10. Make sure you have Python 3.11 or higher installed on your machine.

    1. Create a new directory for your project and navigate into it.
    2. Create a virtual environment:
       ```bash theme={null}
       python3 -m venv .venv
       source .venv/bin/activate
       ```
    3. Install the Box Python SDK:
       ```bash theme={null}
       pip install "boxsdk~=10"
       ```
    4. Install the `python-dotenv` package to load environment variables from the `.env` file:
       ```bash theme={null}
       pip install python-dotenv
       ```
    5. Create an `.env` file in the root of your project directory and add the following
       environment variables, replacing the placeholder values with your actual Box app credentials
       and the IDs from the previous steps:
       ```bash theme={null}
        BOX_DEVELOPER_TOKEN=your_box_developer_token

        BOX_METADATA_TEMPLATE_KEY=your_metadata_template_key
        BOX_FILE_ID=your_box_file_id
       ```

    To get your developer token, go to the Box Developer Console, open your app, and navigate to
    the **Configuration** tab.

    6. Click **Generate Developer Token** to create a new token.

    <Tip>
      For simplicity, this quick start uses a short-lived developer token. In production, you
      should authenticate using your app’s configured method (for example, Client Credentials Grant)
      instead of a developer token.
    </Tip>
  </Step>

  <Step title="Create the enhanced-extract.py file">
    Your development environment is now ready to create the Python script to extract data from the document using Box AI.

    1. Create a new file named `enhanced-extract.py` in the root of your project directory and add the following code:

       ```python theme={null}
       import os

       from dotenv import load_dotenv

       from box_sdk_gen import (
           AiAgentReference,
           AiAgentReferenceTypeField,
           AiItemBase,
           BoxClient,
           BoxDeveloperTokenAuth,
           CreateAiExtractStructuredFields,
           CreateAiExtractStructuredFieldsOptionsField
       )

       load_dotenv()

       developer_token = os.getenv("BOX_DEVELOPER_TOKEN")
       file_id = os.getenv("BOX_FILE_ID")

       def get_box_client(token: str) -> BoxClient:
           
           if not developer_token:
               raise ValueError("BOX_DEVELOPER_TOKEN is not set in environment variables.")
           
           auth = BoxDeveloperTokenAuth(token=token)
           client = BoxClient(auth=auth)

           return client

       def main():
           client = get_box_client(token=developer_token)

           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")

       if __name__ == "__main__":
           main()
       ```

       This code loads the environment variables from the `.env` file, initializes the Box SDK client,
       and prints the current user's ID to validate that the client is working correctly.

    2. Run the script using the following command in your terminal:

       ```bash theme={null}
       python enhanced-extract.py
       ```

       If the Box SDK client is set up correctly, the console displays your user ID. For example:

       ```bash theme={null}
       My user ID is 123456789
       ```
  </Step>

  <Step title="Extract data">
    With a working Box SDK client, you can add the code to extract data from the document using Box AI.

    1. Between the `get_box_client` function and the `main` function, add the following function:

       ```python theme={null}
       def extract_metadata(client: BoxClient, file_id: str) -> dict:

           enhanced_extract_config = AiAgentReference(
               id="enhanced_extract_agent",
               type=AiAgentReferenceTypeField.AI_AGENT_ID
           )

           fields=[
               CreateAiExtractStructuredFields(
                   key="parties",
                   display_name="Parties",
                   description="The named parties involved",
                   prompt="A comma separated list of the named parties involved",
                   type="string",
               ),
               CreateAiExtractStructuredFields(
                   key="effectiveDate",
                   display_name="Effective date",
                   description="The effective date of the contract",
                   prompt="The effective date of the contract",
                   type="date",
               ),
               CreateAiExtractStructuredFields(
                   key="purchasePrice",
                   display_name="Purchase price",
                   description="The purchase price stated in the contract",
                   prompt="The purchase price stated in the contract",
                   type="float",
               ),
               CreateAiExtractStructuredFields(
                   key="summary",
                   display_name="Summary",
                   description="A summary of the contract in 50 words or less",
                   prompt="A summary of the contract in 50 words or less including key obligations",
                   type="string",
               ),
               CreateAiExtractStructuredFields(
                   key="recommendation",
                   display_name="Recommendation",
                   description="Should we make this purchase?",
                   prompt="Given the financial details, would you recommend proceeding with the purchase? Answer Yes or No.",
                   type="enum",
                   options=[
                       CreateAiExtractStructuredFieldsOptionsField(key="Yes"),
                       CreateAiExtractStructuredFieldsOptionsField(key="No"),
                   ],
               ),
           ]

           metadata = client.ai.create_ai_extract_structured(
               [ AiItemBase(id=file_id) ],
               fields=fields,
               ai_agent=enhanced_extract_config,
           )
           
           return metadata.to_dict()['answer']

       ```

       This function uses the Box AI `create_ai_extract_structured` method to extract metadata from the specified file.
       Your BoxClient and the file ID are sent to the function, which returns the extracted metadata as a dictionary.

       <Tip>
         The `fields` parameter defines the specific data points to extract from the document. You can also reference
         a metadata template key instead to extract fields defined in a Box metadata template.
       </Tip>

    2. Add the function call to extract the metadata in the `main` function. Ensure that the new `main` function contains the following logic:

       ```python theme={null}
       def main():
           client = get_box_client(token=developer_token)

           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")

           metadata = extract_metadata(client=client, file_id=file_id)

           print(f"\n\nExtracted Metadata: {metadata}")
       ```

       The SDK handles the API call to Box AI and returns the extracted metadata as an
       <Link href="/reference/resources/ai-extract-structured-response">`AiExtractStructuredResponse`</Link> object. In this quick start,
       the code converts this object to a dictionary and returns the `answer` field that contains the extracted
       key/value pairs.

    3. Print out the extracted metadata to the console to verify that the extraction was successful by running the following command in your terminal:

       ```bash theme={null}
       python enhanced-extract.py
       ```

       If the extraction was successful, the console displays your user ID followed by the extracted metadata from the stock purchase agreement.

       ```bash theme={null}
       My user ID is 123456789

       Extracted Metadata: {'parties': 'Argyle LLP, Suregood Family Trust', 'effectiveDate': '2023-03-31', 'purchasePrice': 231000000, 'summary': 'Argyle LLP agrees to purchase 51% of Erebor Life, Inc. from Suregood Family Trust for $231,000,000. The Seller must operate the business normally until closing, and the Buyer must pay the purchase price. The agreement is effective March 31, 2023.', 'recommendation': 'Yes'}
       ```
  </Step>
</Steps>

## Resources

* <Link href="https://github.com/box-community/box-quickstarts/tree/main/box-ai-enhanced-extract-quickstart">Final code</Link>
* <Link href="/reference/post-ai-extract-structured">Extract Structured Metadata API Reference</Link>
* <Link href="https://github.com/box/box-python-sdk/tree/main">Box Python SDK</Link>


# Natural language extraction with Box AI in Python
Source: https://developer.box.com/guides/box-ai/quick-start/box-ai-extract-freeform

Learn how to use Box AI to automatically extract data from documents with natural language prompts using the Box Python SDK.

<Link href="/ai">Box AI</Link> exposes intelligent extraction capabilities that enable developers to automatically extract
key-value pairs from documents through a single API call. This powerful feature transforms unstructured
document content into actionable metadata without manual data entry, streamlining document processing
workflows for invoices, forms, contracts, and other business documents.

This quick start demonstrates how to configure the Box Python SDK and use Box AI to extract data from a W-2 stored in Box.

<SignupCTA>
  A free developer account gives you access to the Box AI API. Try document summarization, question answering, and metadata extraction through the API.
</SignupCTA>

<Steps>
  <Step title="Create and configure a Box application">
    The first step for any Box integration is to create and configure a Box
    application.

    1. Go to <Link href="https://app.box.com/developers/console">Box Developer Console</Link>.
    2. For this quick start, create an App with the `Client Credentials Grant`
       application type.
    3. Once the app is created, enable the following scopes:
       * Read all files and folders stored in Box
       * Write all files and folders stored in Box
       * Manage AI

    For more information about creating a new Box application, see <Link href="/guides/getting-started/first-application#create-your-first-application">Create your first application</Link>.
  </Step>

  <Step title="Upload a test file">
    After preparing the template, select a file to test. For this quick start, use this
    <Link href="/static/quickstarts/extract/files/freeform-extract-file.pdf">sample W-2</Link>.

    1. Download the test document, and then drag and drop it into your Box account.
    2. Get the file ID by opening the file in Box and inspecting the URL.
       The last part of the path is your file ID. For example, the URL might look like this:
       `https://app.box.com/file/2064123286902`

       In this case, the file ID is `2064123286902`.
  </Step>

  <Step title="Configure the environment">
    Now set up your development environment to run the extraction. For this quick start, use Python and the
    Box Python SDK version 10. Make sure you have Python 3.11 or higher installed on your machine.

    1. Create a new directory for your project and navigate into it.
    2. Create a virtual environment:
       ```bash theme={null}
       python3 -m venv .venv
       source .venv/bin/activate
       ```
    3. Install the Box Python SDK:
       ```bash theme={null}
       pip install "boxsdk~=10"
       ```
    4. Install the `python-dotenv` package to load environment variables from the `.env` file:
       ```bash theme={null}
       pip install python-dotenv
       ```
    5. Create an `.env` file in the root of your project directory and add the following
       environment variables, replacing the placeholder values with your actual Box app credentials
       and the IDs from the previous steps:
       ```bash theme={null}
        BOX_DEVELOPER_TOKEN=your_box_developer_token

        BOX_METADATA_TEMPLATE_KEY=your_metadata_template_key
        BOX_FILE_ID=your_box_file_id
       ```

    To get your developer token, go to the Box Developer Console, open your app, and navigate to
    the **Configuration** tab.

    6. Click **Generate Developer Token** to create a new token.

    <Tip>
      For simplicity, this quick start uses a short-lived developer token. In production, you
      should authenticate using your app’s configured method (for example, Client Credentials Grant)
      instead of a developer token.
    </Tip>
  </Step>

  <Step title="Create the freeform-extract.py file">
    Your development environment is now ready to create the Python script to extract data from the document using Box AI.

    1. Create a new file named `freeform-extract.py` in the root of your project directory and add the following code:

       ```python theme={null}
       import os

       from dotenv import load_dotenv

       from box_sdk_gen import (
           AiItemBase,
           BoxClient,
           BoxDeveloperTokenAuth
       )

       # Set up environment variables
       load_dotenv()

       developer_token = os.getenv("BOX_DEVELOPER_TOKEN")
       file_id = os.getenv("BOX_FILE_ID")

       def get_box_client(token: str) -> BoxClient:
           
           if not developer_token:
               raise ValueError("BOX_DEVELOPER_TOKEN is not set in environment variables.")
           
           auth = BoxDeveloperTokenAuth(token=token)
           client = BoxClient(auth=auth)

           return client

       def main():
           client = get_box_client(token=developer_token)

           # Get the current user and print the ID to validate the client is working
           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")

       if __name__ == "__main__":
           main()
       ```

       This code loads the environment variables from the `.env` file, initializes the Box SDK client,
       and prints the current user's ID to validate that the client is working correctly.

    2. Run the script using the following command in your terminal:

       ```bash theme={null}
       python freeform-extract.py
       ```

       If the Box SDK client is set up correctly, the console displays your user ID. For example:

       ```bash theme={null}
       My user ID is 123456789
       ```
  </Step>

  <Step title="Extract data">
    With a working Box SDK client, you can add the code to extract data from the document using Box AI.

    1. Between the `get_box_client` function and the `main` function, add the following function:

       ```python theme={null}
       def extract_metadata(client: BoxClient, file_id: str) -> str:

           prompt = """
           firstName, lastName, wages, federalTaxWithheld, 
           socialSecurityWages, socialSecurityTaxWithheld, 
           medicareWagesAndTips, medicareTaxWithheld, 
           stateWages, stateTaxWithheld, 
           localWagesAndTips, localTaxWithheld
           """

           metadata = client.ai.create_ai_extract(
               prompt,
               [AiItemBase(id=file_id)]
           )
           
           return metadata.to_dict()['answer']
       ```

       This function uses the Box AI `create_ai_extract` method to extract metadata from the specified file.
       Your BoxClient and the file ID are sent to the function, which returns the extracted metadata as a dictionary.

    2. Add the function call to extract the metadata in the `main` function. Ensure that the new `main` function contains the following logic:

       ```python theme={null}
       def main():
           client = get_box_client(token=developer_token)

           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")

           metadata = extract_metadata(client=client, file_id=file_id)

           print(f"\n\nExtracted Metadata: {metadata}")
       ```

       The SDK handles the API call to Box AI and returns the extracted metadata as an
       <Link href="/reference/resources/ai-extract-response">`AiExtractResponse`</Link> object. In this quick start,
       the code converts this object to a dictionary and returns the `answer` field that contains the extracted
       key/value pairs.

    3. Print out the extracted metadata to the console to verify that the extraction was successful by running the following command in your terminal:

       ```bash theme={null}
       python freeform-extract.py
       ```

       If the extraction was successful, the console displays your user ID followed by the extracted metadata from the W-2.

       ```bash theme={null}
       My user ID is 123456789

       Extracted Metadata: {"firstName": "Wayne", "lastName": "Gatsby", "wages": "355000", "federalTaxWithheld": "125600", "socialSecurityWages": "355000", "socialSecurityTaxWithheld": "12300", "medicareWagesAndTips": "355000", "medicareTaxWithheld": "13200", "stateWages": "355,000", "stateTaxWithheld": "15000", "localWagesAndTips": "355000", "localTaxWithheld": "8000"}
       ```
  </Step>
</Steps>

## Resources

* <Link href="https://github.com/box-community/box-quickstarts/tree/main/box-ai-freeform-extract-quickstart">Final code</Link>
* <Link href="/reference/post-ai-extract">Extract Freeform Metadata API Reference</Link>
* <Link href="https://github.com/box/box-python-sdk/tree/main">Box Python SDK</Link>


# Summarize files with Box AI in Python
Source: https://developer.box.com/guides/box-ai/quick-start/box-ai-summarize

Learn how to use Box AI to automatically extract structured data from documents and store it as searchable metadata using the Box Python SDK.

<Link href="/ai">Box AI</Link> exposes AI capabilities that enable developers to interrogate documents through a single API call. This powerful feature transforms unstructured
document content into instant insights without the need to build and maintain complex Retrieval Augmented Generation (RAG) pipelines.

This quick start demonstrates how to configure the Box Python SDK and use Box AI to summarize files in Box.

<SignupCTA>
  A free developer account gives you access to the Box AI API. Try document summarization, question answering, and metadata extraction through the API.
</SignupCTA>

<Steps>
  <Step title="Create and configure a Box application">
    The first step for any Box integration is to create and configure a Box
    application.

    1. Go to <Link href="https://app.box.com/developers/console">Box Developer Console</Link>.
    2. For this quick start, create an App with the `Client Credentials Grant`
       application type.
    3. Once the app is created, enable the following scopes:
       * Read all files and folders stored in Box
       * Manage AI

    For more information about creating a new Box application, see <Link href="/guides/getting-started/first-application#create-your-first-application">Create your first application</Link>.
  </Step>

  <Step title="Upload a test file">
    To use Box AI to get insights from documents, you need a file in Box. For this quick start, use this document containing
    <Link href="/static/quickstarts/summarize/files/ai-summary-document.pdf">federal code</Link>.

    1. Download the test document, and then drag and drop it into your Box account.
    2. Get the file ID by opening the file in Box and inspecting the URL.
       The last part of the path is your file ID. For example, the URL might look like this:
       `https://app.box.com/file/2064123286902`

    In this case, the file ID is `2064123286902`.
  </Step>

  <Step title="Configure the environment">
    Now set up your development environment to run this quickstart. This tutorial uses Python and the
    latest Box Python SDK to run the code. Make sure you have Python 3.11 or higher installed on your machine.

    1. Create a new directory for your project and navigate into it.
    2. Create a virtual environment:
       ```bash theme={null}
       python3 -m venv .venv
       source .venv/bin/activate
       ```
    3. Install the Box Python SDK:
       ```bash theme={null}
       pip install "boxsdk~=10"
       ```
    4. Install the `python-dotenv` package to load environment variables from the `.env` file:
       ```bash theme={null}
       pip install python-dotenv
       ```
    5. Create an `.env` file in the root of your project directory and add the following
       environment variables, replacing the placeholder values with your actual Box app credentials
       and the IDs from the previous steps:
       ```bash theme={null}
        BOX_DEVELOPER_TOKEN=your_box_developer_token

        BOX_FILE_ID=your_box_file_id
       ```

    To get your developer token, go to the <Link href="https://app.box.com/developers/console">Box Developer Console</Link>,
    open your app, and navigate to the **Configuration** tab.

    6. Click **Generate Developer Token** to create a new token.

    <Tip>
      For simplicity, this quick start uses a short-lived developer token. In production, you
      should authenticate using your app’s configured method (for example, Client Credentials Grant)
      instead of a developer token.
    </Tip>
  </Step>

  <Step title="Create the summarize.py file">
    Your development environment is now ready to create the Python script to summarize the document using Box AI.

    1. Create a new file named `summarize.py` in the root of your project directory and add the following code:

       ```python theme={null}
       import os

       from dotenv import load_dotenv

       from box_sdk_gen import (
           AiItemAsk,
           AiItemAskTypeField,
           BoxClient,
           BoxDeveloperTokenAuth,
           CreateAiAskMode
       )

       load_dotenv()

       developer_token = os.getenv("BOX_DEVELOPER_TOKEN")
       file_id = os.getenv("BOX_FILE_ID")

       def get_box_client(token: str) -> BoxClient:
           
           if not developer_token:
               raise ValueError("BOX_DEVELOPER_TOKEN is not set in environment variables.")
           
           auth = BoxDeveloperTokenAuth(token=token)
           client = BoxClient(auth=auth)

           return client

       def main():
           client = get_box_client(token=developer_token)

           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")


       if __name__ == "__main__":
           main()
       ```

    This code loads the environment variables from the `.env` file, initializes the Box SDK client,
    and prints the current user's ID to validate that the client is working correctly.

    2. Run the script using the following command in your terminal:

       ```bash theme={null}
       python summarize.py
       ```

       If the Box SDK client is set up correctly, the console displays your user ID. For example:

       ```bash theme={null}
       My user ID is 123456789
       ```
  </Step>

  <Step title="Summarize the file">
    With a working Box SDK client, you can add the code to summarize the document using Box AI.

    1. Between the `get_box_client` function and the `main` function, add the following function:

       ```python theme={null}
       def summarize_file(client: BoxClient, file_id: str) -> str:
           prompt = """
           Summarize the content of the following file in a few sentences.
           """

           summary = client.ai.create_ai_ask(
               CreateAiAskMode.SINGLE_ITEM_QA,
               prompt,
               [
                   AiItemAsk(
                       id=file_id,
                       type=AiItemAskTypeField.FILE
                   )
               ]
           )
           
           return summary.to_dict()['answer']
       ```

       This function uses the Box AI `create_ai_ask` method to interrogate the specified file.
       Your BoxClient and file ID created earlier are sent to the function, which
       returns the summary of the file as a string.

    2. Add the function call to summarize the file in the `main` function. Ensure that the new `main` function contains the following logic:

       ```python theme={null}
       def main():
           client = get_box_client(token=developer_token)

           # Get the current user and print the ID to validate the client is working
           me = client.users.get_user_me()
           print(f"My user ID is {me.id}")

           summary = summarize_file(client=client, file_id=file_id)

           # Print the extracted metadata
           print(f"\n\nSummary: {summary}")
       ```

       The SDK handles the API call to Box AI and returns the summary as an
       <Link href="/reference/resources/ai-response--full">`AiResponseFull`</Link> object. In this quick start,
       the code converts this object to a dictionary and returns the `answer` field that contains the summary.

    3. Print out the summary to the console to verify that the operation was successful by running the following command in your terminal:

       ```bash theme={null}
       python summarize.py
       ```

       If the summarization was successful, the console displays your user ID followed by the summary from the test document.

       ```bash theme={null}
       My user ID is 123456789

       Summary: **Summary of 28 CFR § 2.20 (Paroling Policy Guidelines)**

       - The document sets forth the U.S. Parole Commission’s purpose and framework for national parole policy, emphasizing guidelines to promote consistent, equitable parole decisions while preserving individualized review.
       - It provides a matrix of customary total time-to-release ranges by offense severity categories (1–8) and offender parole prognosis (salient factor scores), noting guidelines apply to inmates with good institutional adjustment and are discretionary.
       - A comprehensive Offense Behavior Severity Index (Chapters 1–12) assigns categories to specific crimes (homicide, assault, theft, drugs, firearms, national defense, etc.) with detailed rules, exceptions, and examples for grading offenses (including monetary thresholds and drug-quantity bands).
       - Chapter Thirteen contains general notes, multiple-offense scoring guidance, definitions of key terms, and the Salient Factor Scoring Manual explaining how to compute parole prognosis points (prior convictions, commitments, age, recent commitment-free period, probation/parole status, and older-offender adjustment).
       - The document also references reparole guidelines and authority to revise guidelines; aggravated crimes and Category Eight cases receive special treatment.
       ```
  </Step>
</Steps>

## Resources

* <Link href="https://github.com/box-community/box-quickstarts/tree/main/box-ai-summarize-quickstart">Final code</Link>
* <Link href="/reference/post-ai-ask">Box AI Ask API Reference</Link>
* <Link href="https://github.com/box/box-python-sdk/tree/main">Box Python SDK</Link>


# Box MCP server
Source: https://developer.box.com/guides/box-mcp/index

Hosted Model Context Protocol (MCP) server at https://mcp.box.com that lets AI agents search and use Box files over OAuth.

The **Box MCP server** is a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server at `https://mcp.box.com`. It lets AI agents and apps search and use Box files over OAuth, without you handling raw file payloads in the client.

MCP is an open protocol that standardizes how applications provide context to LLMs. Agents call Box tools (search, Box AI, folders, and more) through this single endpoint.

<Frame>
  <img alt="MCP" />
</Frame>

## How it works at a glance

Follow this path when you are wiring or extending an integration:

1. **Box hosts MCP** at `https://mcp.box.com`. You connect your client or agent platform to this URL; you do not run Box’s MCP server yourself for the standard integration.
2. **An admin enables MCP** in the Box Admin Console and, for custom clients, creates **Integration Credentials** (OAuth client ID and client secret, redirect URI, and scopes such as **Content Actions**).
3. **Your application** passes the MCP endpoint, OAuth credentials, the MCP name `box-remote-mcp`, and an authorization token according to your platform’s MCP client requirements.

| If you want to… | Go to |
| - | - |
| Understand identity, scopes, and that MCP does not bypass Box permissions | [Permission-aware agent access](/guides/box-mcp/permission-aware-access) |
| Enable MCP in the Admin Console, configure OAuth, and connect your client | [Set up the MCP server](/guides/box-mcp/setup) |
| Look up tool names and what each tool does | [Available tools](/guides/box-mcp/tools) |

## Platform setup guides

Box MCP server supports an expanding range of AI platforms. Select a card below to view setup instructions for each one.

<Tip>
  Step-by-step setup for **end-user AI platforms** (for example ChatGPT, Claude, Copilot Studio, Figma, and others) lives in **Box product documentation** — see [Supported AI Platforms](https://docs.box.com/en/box-mcp/supported-ai-platforms) for the full partner list and platform guides.
</Tip>

<Columns>
  <Card title="Anthropic Messages API" icon="https://mintcdn.com/box/NmGN4B47Pa8A0w_J/static/guides-box-mcp/anthropic.svg?fit=max&auto=format&n=NmGN4B47Pa8A0w_J&q=85&s=f36ccc5d795d4efd47959d985c279d70" href={localizeLink("/guides/box-mcp/integrations/anthropic-messages-api")} />

  <Card title="Claude Code" icon="https://mintcdn.com/box/NmGN4B47Pa8A0w_J/static/guides-box-mcp/claude.svg?fit=max&auto=format&n=NmGN4B47Pa8A0w_J&q=85&s=fa5cecbfcbba321a853fd6677bd2c0a5" href={localizeLink("/guides/box-mcp/integrations/claude-code")} />

  <Card title="Codex" icon="https://mintcdn.com/box/mgZNgJiMvumWd7XU/static/guides-box-mcp/codex.svg?fit=max&auto=format&n=mgZNgJiMvumWd7XU&q=85&s=9e8c54fe247c199fbe197dc46fca6d62" href={localizeLink("/guides/box-mcp/integrations/codex")} />

  <Card title="Cursor" icon="https://mintcdn.com/box/NmGN4B47Pa8A0w_J/static/guides-box-mcp/cursor.svg?fit=max&auto=format&n=NmGN4B47Pa8A0w_J&q=85&s=5c167a019bf2ff32cc32223ff9da1a02" href={localizeLink("/guides/box-mcp/integrations/cursor")} />

  <Card title="GitHub Copilot" icon="https://mintcdn.com/box/NmGN4B47Pa8A0w_J/static/guides-box-mcp/github.svg?fit=max&auto=format&n=NmGN4B47Pa8A0w_J&q=85&s=1b24a24d063d4926cba62d91c35f47bc" href={localizeLink("/guides/box-mcp/integrations/github-copilot")} />

  <Card title="Groq Responses API" icon="https://mintcdn.com/box/NmGN4B47Pa8A0w_J/static/guides-box-mcp/groq.svg?fit=max&auto=format&n=NmGN4B47Pa8A0w_J&q=85&s=778280ac41cc66359ddf44f344dd1fa9" href={localizeLink("/guides/box-mcp/integrations/groq-responses-api")} />

  <Card title="LangSmith Agent Builder" icon="https://mintcdn.com/box/NmGN4B47Pa8A0w_J/static/guides-box-mcp/langsmith.svg?fit=max&auto=format&n=NmGN4B47Pa8A0w_J&q=85&s=6e7b1d25c75d7d504698141598849f56" href={localizeLink("/guides/box-mcp/integrations/langsmith-agent-builder")} />

  <Card title="Microsoft Foundry Tools" icon="https://mintcdn.com/box/NmGN4B47Pa8A0w_J/static/guides-box-mcp/microsoft.svg?fit=max&auto=format&n=NmGN4B47Pa8A0w_J&q=85&s=5894cfdffd33fd695bde11b6757bac72" href={localizeLink("/guides/box-mcp/integrations/microsoft-foundry-tools")} />

  <Card title="OpenAI AgentKit" icon="openai" href={localizeLink("/guides/box-mcp/integrations/openai-agentkit")} />
</Columns>

<Warning>
  The **self-hosted** Box MCP server (open-source community project) is **deprecated**. Do not start new work on it. Existing references and troubleshooting remain in [Self-hosted Box MCP server (legacy)](/guides/box-mcp/self-hosted) under **Appendix**.
</Warning>

Watch an interview with Box CTO, Ben Kus, and learn how MCP empowers AI agents to work dynamically across platforms, reducing the development effort.

<iframe title="MCP: The API standard that makes AI actionable for enterprises | Box AI Explainer Series EP4 with Ben Kus, Box CTO" />


# Anthropic's Messages API
Source: https://developer.box.com/guides/box-mcp/integrations/anthropic-messages-api



Connect the Box MCP server with [Anthropic's Messages API](https://docs.anthropic.com/en/api/messages). Clone [this sample chat bot project](https://github.com/box-community/mcp-client-remote-mcp-react) to get started quickly. It allows you to have a conversation with an Anthropic model, which has access to tools provided by the Box MCP server.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See [Set up the MCP server](/guides/box-mcp/setup).
* An Anthropic API key with access to the Messages API.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Clone the [sample chat bot project](https://github.com/box-community/mcp-client-remote-mcp-react).
2. Follow the project README to configure your Box OAuth credentials and Anthropic API key.
3. Start the application and authenticate with Box when prompted.

The sample project is a React-based chat bot that leverages Box MCP. It demonstrates how to pass the MCP endpoint and authorization token to Anthropic's Messages API:

```python theme={null}
response = await client.beta.messages.create(
    model="claude-3-opus-20240229",
    max_tokens=4096,
    messages=conversation_history,
    mcp_servers=[
        {
            "type": "url",
            "url": "https://mcp.box.com",
            "name": "box-remote-mcp",
            "authorization_token": BEARER_TOKEN,
        }
    ],
    betas=["mcp-client-2025-04-04"]
)
```

## Video walkthrough

Watch a video that features a demo project, a React-based chat bot that leverages Box MCP.

<iframe title="Unlock your enterprise data: Connect AI agents to Box with MCP" />


# Box MCP for Claude Code
Source: https://developer.box.com/guides/box-mcp/integrations/claude-code

Connect the Box MCP server to Claude Code so your coding agent can search and use Box content from the terminal.

Connect the Box MCP server with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) to give your AI coding agent direct access to Box content from the command line.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See [Set up the MCP server](/guides/box-mcp/setup).
* [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed (`npm install -g @anthropic-ai/claude-code`).

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **Claude** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Ensure Claude is enabled for your enterprise by setting the **Availability status** to **Available to all users**.

### Verify the connection

After adding the server, start Claude Code and run `/mcp` to confirm `box-remote-mcp` is listed and connected. You can then ask Claude Code to interact with your Box content using the [available tools](/guides/box-mcp/tools).

## Use the integration

<Badge>User</Badge>

1. In Claude Code run `/plugin`, search for Box, and install,
   OR
2. Run `claude mcp add box --transport http https://mcp.box.com` in Claude Code.

See Anthropic's docs for details: [Connect Claude Code to tools via MCP - Claude Code Docs](https://code.claude.com/docs/en/mcp).


# Codex
Source: https://developer.box.com/guides/box-mcp/integrations/codex



Connect the Box MCP server with [Codex](https://www.codex.com/) to give your AI coding agent direct access to Box content.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See [Set up the MCP server](/guides/box-mcp/setup).
* [Codex](https://www.codex.com/) installed.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **ChatGPT - MCP** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Ensure **ChatGPT - MCP** is enabled for your enterprise by setting the **Availability status** to **Available to all users**.

## Use the integration

<Badge>User</Badge>

In Codex app:

1. Open plugins.
2. Search for **Box**.
3. Add the integration to Codex.

## In CLI

<Badge>User</Badge>

1. Run `/plugins` in Codex.
2. Search for **Box** in the plugins marketplace and install it.


# Cursor
Source: https://developer.box.com/guides/box-mcp/integrations/cursor



Connect the Box MCP server with [Cursor](https://www.cursor.com/) to give your AI coding agent direct access to Box content.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See [Set up the MCP server](/guides/box-mcp/setup).
* [Cursor](https://www.cursor.com/) installed.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **Custom Box MCP Server** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Go to **Configuration** > **Add Integration Credentials** to generate new credentials.
4. In **Redirect URIs**, set the redirect URIs. See [here](https://cursor.com/docs/mcp#static-redirect-url) for Cursor's documentation on their redirect URIs.
5. Copy the **Client ID** and **Client Secret** for later use. These are required later for Cursor to authorize the connection.
6. Check the desired **Access scopes**:
   * **Scopes** define the maximum set of actions. Users can only access content they already have permission to view or edit in Box.
7. Click **Save**.

## Use the integration

<Badge>User</Badge>

1. Go to **Settings** > **Tools and MCPs** > **Add Custom MCP** (opens `mcp.json`).
2. Paste the configuration below, add your client ID and client secret, and save the file.

```json theme={null}
{
  "mcpServers": {
    "box": {
      "url": "https://mcp.box.com",
      "auth": {
        "CLIENT_ID": "your_client_id",
        "CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
```

3. Return to **Tools and MCPs** in Cursor settings and click connect to complete authorization.

Optionally, install the Box plugin for our skills.

1. Go to **Settings** > **Plugins** > **Browse Marketplace** and search for **Box**.
2. Click **Add to Cursor**.

See Cursor docs for more details: [Add Custom MCP - Cursor Docs](https://docs.cursor.com/mcp/add-custom-mcp).


# Box MCP for GitHub Copilot
Source: https://developer.box.com/guides/box-mcp/integrations/github-copilot

Connect the Box MCP server to GitHub Copilot in VS Code so Copilot can search and use files in Box.

Connect the Box MCP server to GitHub Copilot in VS Code: find it on the [GitHub MCP Registry](https://github.com/mcp), then complete setup with [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) using the flow below.

Copilot acts as the Box user who authorizes the connection. Scopes and Box file permissions still apply. See [permission-aware agent access](/guides/box-mcp/permission-aware-access).

## Prerequisites

* [VS Code](https://code.visualstudio.com/) with [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) installed.

## GitHub MCP Registry

The Box MCP server is listed on GitHub at the [Box MCP server overview page](https://github.com/mcp/box/mcp-server-box-remote). From there you can open the install flow for supported editors and tools (for example VS Code with Copilot) without hunting for the endpoint URL elsewhere.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **Custom Box MCP Server** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Go to **Configuration** > **Add Integration Credentials** to generate new credentials.
4. In **Redirect URIs**, change the Box redirect URIs to the Redirect URI provided by the external MCP Client.
5. Copy the **Client ID** and **Client Secret** for later use. These are required later for GitHub to authorize the connection.
6. Check the desired **Access scopes**:
   * **Scopes** define the maximum set of actions. Users can only access content they already have permission to view or edit in Box.
7. Click **Save**.

## Enable the integration in VS Code

<Badge>User</Badge>

1. Go to the [Box MCP server overview page](https://github.com/mcp/box/mcp-server-box-remote) on GitHub.
2. Click **Install MCP server**.
3. You will be redirected to the VS Code editor. Click **Install** and complete OAuth to grant access to Box.

You may need to manually enter your Client ID and Client Secret. When registering your OAuth application, make sure to include the following redirect URIs:

```sh theme={null}
http://127.0.0.1:33418
https://vscode.dev/redirect
```

## Video walkthrough

<iframe title="Build a working API demo-fast-by connecting GitHub Copilot to the Box MCP Server" />


# Groq Responses API
Source: https://developer.box.com/guides/box-mcp/integrations/groq-responses-api



Integrate the Box MCP server with Groq to enable high-speed AI inference with access to your Box content.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See [Set up the MCP server](/guides/box-mcp/setup).
* A Groq API account.

## Getting started

Follow the tutorial in the [Groq API Cookbook](https://github.com/groq/groq-api-cookbook/tree/main/tutorials/03-mcp/mcp-box) for step-by-step instructions on setting up and using Box MCP with Groq.


# LangSmith Agent Builder
Source: https://developer.box.com/guides/box-mcp/integrations/langsmith-agent-builder



Use the Box MCP server with [LangChain Agent Builder](https://docs.langchain.com/langsmith/agent-builder-remote-mcp-servers) to build reusable agents that securely connect to Box, analyze files with Box AI, extract structured data, and save artifacts back to Box.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See [Set up the MCP server](/guides/box-mcp/setup).
* A LangSmith account with access to Agent Builder.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **Custom Box MCP Server** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Go to **Configuration** > **Add Integration Credentials** to generate new credentials.
4. In **Redirect URIs**, change the Box redirect URIs to the Redirect URI provided by the external MCP Client.
5. Copy the **Client ID** and **Client Secret** for later use. These are required later for LangSmith to authorize the connection.
6. Check the desired **Access scopes**:
   * **Scopes** define the maximum set of actions. Users can only access content they already have permission to view or edit in Box.
7. Click **Save**.

## Configure Connection in LangSmith Agent Builder

<Badge>Admin</Badge>

Follow the instructions in the LangChain’s documentation: [Manage workspace administration](https://docs.langchain.com/langsmith/fleet/workspace-admin#workspace-secrets), [Remote MCP Servers](https://docs.langchain.com/langsmith/agent-builder-remote-mcp-servers).

## Video walkthrough

The video below shows how to use the Box MCP server with LangChain Agent Builder
to build a reusable intake review agent. The agent securely connects to Box, analyzes
files with Box AI, extracts structured data, and saves a review packet back to the source
folder. In this guide, you will:

* Connect LangChain Agent Builder to Box using MCP and OAuth
* Use a prebuilt agent template for intake review workflows
* Run the agent with a simple prompt
* Extract key fields, classify documents, and flag missing information
* Generate a durable review artifact saved back into Box

<iframe title="Build an intake review agent with LangChain Agent Builder + Box MCP" />


# Microsoft Foundry Tools
Source: https://developer.box.com/guides/box-mcp/integrations/microsoft-foundry-tools

Connect the Box MCP server to Microsoft Foundry Tools. The agent acts as the authorizing Box user. Scopes and Box file permissions still apply.

Connect the Box MCP server with Microsoft Foundry Tools so agents in Foundry can search and use Box files. This does **not** replace Box access control with Microsoft permissions. See <Link href="/guides/box-mcp/permission-aware-access">permission-aware agent access</Link>.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See <Link href="/guides/box-mcp/setup">Set up the MCP server</Link>.
* Microsoft Foundry Tools installed.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **Custom Box MCP Server** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Go to **Configuration** > **Add Integration Credentials** to generate new credentials.
4. In **Redirect URIs**, change the Box redirect URIs to the Redirect URI provided by the external MCP Client.
5. Copy the **Client ID** and **Client Secret** for later use. These are required later for Microsoft Foundry Tools to authorize the connection.
6. Check the desired **Access scopes**:
   * **Scopes** define the maximum set of actions. Users can only access content they already have permission to view or edit in Box.
7. Select **Save**.

## Add the remote Box MCP server

<Badge>User</Badge>

Box is available in the Microsoft Foundry Tools catalog. To add the remote Box MCP server, refer to the official Microsoft documentation:

* [Agent tools overview for Microsoft Foundry Agent Service - Microsoft Foundry](https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/tool-catalog).
* [Connect to MCP Server Endpoints for agents - Microsoft Foundry](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/tools/model-context-protocol?pivots=python#connect-to-mcp-server-endpoints-for-agents).


# OpenAI AgentKit
Source: https://developer.box.com/guides/box-mcp/integrations/openai-agentkit



Connect the Box MCP server with OpenAI AgentKit to enable your users to connect to Box
from OpenAI AgentKit.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **ChatGPT - MCP** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Ensure **ChatGPT - MCP** is enabled for your enterprise by setting the **Availability status** to **Available to all users**.

## Use the integration in agent builder

<Badge>User</Badge>

1. In each Agent that requires Box MCP, click the **+** button in the **Tools** section.
2. Select **MCP**.
3. Look for the **Box MCP**.
4. Enter your Box Access token and connect.


# Windows ODR (On Device Registry)
Source: https://developer.box.com/guides/box-mcp/integrations/windows-on-device-registry



Connect the Box MCP server with Windows ODR (On Device Registry) to enable your users to connect to Box from Windows ODR.

## Prerequisites

* A Box enterprise account with the MCP server enabled by an admin. See [Set up the MCP server](/guides/box-mcp/setup).
* Windows ODR installed.

## Enable Box integration in Box

<Badge>Admin</Badge>

1. Sign in to the [Box Admin Console](https://app.box.com/master).
2. Go to **Integrations** and find **Custom Box MCP Server** either by using the **MCP Category** filter, or by using the search bar at the top of the page.
3. Go to **Configuration** > **Add Integration Credentials** to generate new credentials.
4. In **Redirect URIs**, change the Box redirect URIs to the Redirect URI provided by the external MCP Client.
5. Copy the **Client ID** and **Client Secret** for later use. These are required later for Windows ODR to authorize the connection.
6. Check the desired **Access scopes**:
   * **Scopes** define the maximum set of actions. Users can only access content they already have permission to view or edit in Box.
7. Click **Save**.

## Windows ODR setup

<Badge>User</Badge>

To set up Windows ODR as an MCP host and connect the MCP servers,
refer to the detailed steps and guidance in the official Microsoft documentation: [Model Context Protocol (MCP) on Windows overview](https://learn.microsoft.com/en-us/windows/ai/mcp/overview).


# Give an AI agent secure, permission-aware access to enterprise documents
Source: https://developer.box.com/guides/box-mcp/permission-aware-access

Give an AI agent secure access to enterprise documents in Box. The Box MCP server and Box APIs act as the authenticated user or application. Scopes, collaborations, and waterfall permissions still apply.

Connect the agent as an authenticated Box identity.

Use the hosted <Link href="/guides/box-mcp">Box MCP server</Link> (`https://mcp.box.com`) when the agent supports MCP. Use the Box APIs, SDKs, or <Link href="/guides/cli">Box CLI</Link> when the agent runs code. Either way, the agent only sees files the authenticated user or application can already access.

Connecting any agent platform to Box does **not** bypass file permissions. Box checks collaborations, waterfall folder permissions, and application scopes on every request.

## How access works

Three layers apply on every request:

| Layer | What it controls |
| - | - |
| **Identity** | Who the agent is: an end user (OAuth) or a service account / CCG application. |
| **Scopes** | The maximum actions the integration can request. Scopes never grant access to files the identity cannot open. |
| **Content permissions** | Collaborations, waterfall folder permissions, shared links, Shield, and classification policies. |

The MCP server does not impersonate other users or search the enterprise unless the identity already can. See <Link href="/guides/getting-started/why-box#does-the-box-mcp-server-bypass-box-permissions">Does the Box MCP server bypass Box permissions?</Link>

## Choose an identity

<AccordionGroup>
  <Accordion title="End-user OAuth (default for MCP)">
    The agent acts as the Box user who signs in. Use this for assistants that work on that person's files: Copilot, Cursor, Claude, Foundry Tools, and similar clients.

    Enable MCP in the Admin Console, create integration credentials, and request only the scopes the agent needs. See <Link href="/guides/box-mcp/setup">Set up the MCP server</Link>.
  </Accordion>

  <Accordion title="Service account or CCG (automation)">
    Server-side jobs (extract on upload, publish to a hub, scheduled review) typically authenticate as a service account with <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>.

    Collaborate that service account onto specific folders. Do not use a service account as a hidden superuser for an interactive agent. Downscope tokens when you pass credentials to a browser or untrusted runtime. See <Link href="/guides/authentication/tokens/downscope">Downscope a token</Link>.
  </Accordion>
</AccordionGroup>

## Production versus local tests

Use a <Link href="https://account.box.com/signup/developer">free developer account</Link> and sample files while you learn the tools. The <Link href="/tutorials/connect-an-agent-to-box">Connect an AI agent to Box</Link> tutorial covers local setup and warns against pointing a coding agent at production content.

For production:

1. An admin enables MCP (or authorizes the Platform App) in the Admin Console.
2. Create dedicated integration credentials and request only the scopes you need.
3. Choose the Box user or service account deliberately. Collaborate it onto the folders the agent should access.
4. Test with that identity. If a file is missing from search or Ask, check collaborations first, not the model.

## Microsoft agent platforms

GitHub Copilot and Microsoft Foundry Tools connect to Box through MCP with the same permission model as any other client:

* The Box user who authorizes the connection is the identity.
* Admin-configured scopes cap what the client can request.
* SharePoint or Graph permissions do not replace Box permissions on Box files.

For setup steps, see <Link href="/guides/box-mcp/integrations/microsoft-foundry-tools">Microsoft Foundry Tools</Link> and <Link href="/guides/box-mcp/integrations/github-copilot">GitHub Copilot</Link>. For the tool list, see <Link href="/guides/box-mcp/tools">Available tools</Link>.

## Related patterns

* Query a curated knowledge base with hubs and Ask: <Link href="/guides/hubs-api/access-controlled-knowledge-base">Access-controlled AI knowledge base</Link>.
* Start with Box-managed retrieval before exporting to a vector index: <Link href="/ai/rag">Build RAG over enterprise documents stored in Box</Link>.

<RelatedLinks title="RELATED GUIDES" />


# Self-hosted Box MCP server (legacy)
Source: https://developer.box.com/guides/box-mcp/self-hosted/index

Deprecated open-source MCP server for local use. Prefer the remote Box MCP server for new integrations.

<Warning>
  **Deprecation:** The self-hosted Box MCP server is deprecated. For new integrations, use the [remote Box MCP server](/guides/box-mcp/setup) hosted at `https://mcp.box.com`. This page remains for existing deployments and reference only.
</Warning>

The [Self-hosted Box MCP server](https://github.com/box-community/mcp-server-box.git) is a Python project that integrates with the Box API to perform various operations such as file search, text extraction, AI-based querying, and data extraction. It leverages the Box Python Next Gen SDK library and provides a set of tools to interact with Box files and folders.

## Installation

### Prerequisites

* Python `3.13` or higher
* Platform app credentials (Client ID, Client Secret)

Follow the steps from this section to set up the self-hosted Box MCP server.

1. Clone the repository:

```sh theme={null}
git clone https://github.com/box-community/mcp-server-box.git
cd mcp-server-box
```

2. Install `uv` if it's not installed on your machine:

<CodeGroup>
  ```sh MacOS/Linux theme={null}
    curl -LsSf https://astral.sh/uv/install.sh | sh
  ```

  ```powershell Windows theme={null}
    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  ```
</CodeGroup>

Restart your terminal afterwards to ensure that the `uv` command gets picked up.

3. Create and set up our project:

<CodeGroup>
  ```sh MacOS/Linux theme={null}
    # Create virtual environment and activate it
    uv venv
    source .venv/bin/activate

    # Lock the dependencies
    uv lock
  ```

  ```sh Windows theme={null}
    # Create virtual environment and activate it
    uv venv
    .venv\Scripts\activate

    # Lock the dependencies
    uv lock
  ```
</CodeGroup>

4. Create a `.env` file in the root directory and fill your platform app credentials:

```.env theme={null}
BOX_CLIENT_ID=your_client_id
BOX_CLIENT_SECRET=your_client_secret
```

You can also watch a video tutorial and see example usage of Box MCP tools.

<iframe title="Box self-hosted MCP Server" />

## Running Box MCP server locally

To start the Box MCP server, run the following command:

```sh theme={null}
uv --directory /Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box run src/mcp_server_box.py
```

Update the path so it reflects your local setup.

### Use Cursor as the Box MCP client

Prerequisites:

* Download [Cursor desktop app](https://www.cursor.com/)

Follow these instructions to start using Box MCP Server with Cursor:

1. Open the Cursor app.
2. Click the cog icon to open settings.
3. Select `MCP` within the Cursor Settings tab.
4. Click the `Add new global MCP server` button. This opens the `mcp.json` file.
5. Update the values with your local setup and paste the following JSON:

```json theme={null}
{
  "mcpServers": {
    "box": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box",
        "run",
        "src/mcp_server_box.py"
      ]
    }
  }
}
```

6. Save and close the `mcp.json` file.
7. Restart Cursor if necessary.
8. Use the `box_authorize_app_tool` tool to start using Box MCP.

### Use Claude as the Box MCP client

Prerequisites:

* Download [Claude for Desktop](https://claude.ai/download) client
* Optionally, set up [`code`](https://code.visualstudio.com/docs/setup/mac#_configure-the-path-with-vs-code) command for VS Code

Follow these steps to set up Box MCP in Claude for Desktop:

1. Edit your `claude_desktop_config.json`.

You can run this command in your terminal:

```sh theme={null}
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

Alternatively, in the main Claude navigation choose `Settings`. Select the Developers tab and click `Edit Config`. This opens a folder window containing `claude_desktop_config.json`.

2. Add the configuration:

```json theme={null}
{
  "mcpServers": {
      "mcp-server-box": {
          "command": "uv",
          "args": [
              "--directory",
              "/Users/Users/USER_NAME/PATH_TO_PROJECT/mcp-server-box",
              "run",
              "src/mcp_server_box.py"
          ]
      }
  }
}
```

3. Restart Claude desktop app.
4. Authenticate the Box MCP server using `box_authorize_app_tool` tool.

## Available tools

### Authentication and Authorization

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`get_box_client`</td>
      <td>Helper function to get Box client from context</td>

      <td>
        * `ctx (Context)`: Request context.
      </td>

      <td>Box client instance</td>
    </tr>

    <tr>
      <td>`box_who_am_i`</td>
      <td>Get the current user's information</td>

      <td>
        * `ctx (Context)`: Request context.
      </td>

      <td>User information string</td>
    </tr>

    <tr>
      <td>`box_authorize_app_tool`</td>
      <td>Authorize the Box application</td>
      <td>None</td>
      <td>Authorization status message</td>
    </tr>
  </tbody>
</table>

### Search and Navigation

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_search_tool`</td>
      <td>Search for files in Box</td>

      <td>
        * `query (str)`: Search query.
        * `file_extensions (List[str], optional)`: Filter by extensions.
        * `where_to_look_for_query (List[str], optional)`: Locations to search.
        * `ancestor_folder_ids (List[str], optional)`: Folder IDs to limit the search.
      </td>

      <td>Newline-separated list of file names and IDs</td>
    </tr>

    <tr>
      <td><code>`box_search_folder_by_name`</code></td>
      <td>Locate a folder by name</td>
      <td>`folder_name (str)`: Name of the folder</td>
      <td>Folder ID and information</td>
    </tr>

    <tr>
      <td>`box_list_folder_content_by_folder_id`</td>
      <td>List folder contents</td>

      <td>
        <ul>
          <li>`folder_id (str)`: ID of the folder.</li>
          <li>`is_recursive (bool)`: Whether to list recursively.</li>
        </ul>
      </td>

      <td>Folder content in JSON format</td>
    </tr>
  </tbody>
</table>

### File Operations

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_read_tool`</td>
      <td>Read the text content of a Box file</td>

      <td>
        * `file_id (str)`: ID of the file to read.
      </td>

      <td>File content</td>
    </tr>

    <tr>
      <td>`box_upload_file_from_path_tool`</td>
      <td>Upload a file from local path</td>

      <td>
        * `file_path (str)`: Local file path.<br />
        * `folder_id (str, optional)`: Destination folder ID.<br />
        * `new_file_name (str, optional)`: New file name.
      </td>

      <td>File details or error message</td>
    </tr>

    <tr>
      <td>`box_upload_file_from_content_tool`</td>
      <td>Upload content as a file</td>

      <td>
        * `content (str|bytes)`: Content to upload.<br />
        * `file_name (str)`: File name.<br />
        * `folder_id (str, optional)`: Destination folder ID.<br />
        * `is_base64 (bool, optional)`: If content is base64 encoded.
      </td>

      <td>Upload success message</td>
    </tr>

    <tr>
      <td>`box_download_file_tool`</td>
      <td>Download a file from Box</td>

      <td>
        * `file_id (str)`: File ID.<br />
        * `save_file (bool, optional)`: Whether to save locally.<br />
        * `save_path (str, optional)`: Local save path.
      </td>

      <td>File content or save confirmation</td>
    </tr>

    <tr>
      <td>`get_file_content`</td>
      <td>Extract text content from a file</td>

      <td>
        * `file_id (str)`: File ID.<br />
      </td>

      <td>Text file content</td>
    </tr>
  </tbody>
</table>

### Folder Management

<table>
  <thead>
    <tr><th>Tool</th><th>Description</th><th>Parameters</th><th>Returns</th></tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_manage_folder_tool`</td>
      <td>Create, update, or delete folders</td>

      <td>
        * `action (str)`: `create`, `delete`, or `update`.
        * `folder_id (str, optional)`: Folder ID.
        * `name (str, optional)`: Folder name.
        * `parent_id (str, optional)`: Parent folder ID.
        * `description (str, optional)`: Folder description.
        * `recursive (bool, optional)`: For recursive delete.
      </td>

      <td>Status message with folder details</td>
    </tr>
  </tbody>
</table>

### Box AI

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_ask_ai_tool`</td>
      <td>Ask Box AI about a file</td>

      <td>
        * `file_id (str)`: File ID.<br />
        * `prompt (str)`: Question for the AI.
      </td>

      <td>AI response</td>
    </tr>

    <tr>
      <td>`box_ask_ai_tool_multi_file`</td>
      <td>Query Box AI using multiple files</td>

      <td>
        * `file_ids (List[str])`: List of file IDs.<br />
        * `prompt (str)`: Instruction for AI.
      </td>

      <td>AI-generated answer</td>
    </tr>

    <tr>
      <td>`box_hubs_ask_ai_tool`</td>
      <td>Ask Box AI about a hub</td>

      <td>
        * `hubs_id (str)`: ID of the hub.<br />
        * `prompt (str)`: Question for the AI.
      </td>

      <td>AI response</td>
    </tr>

    <tr>
      <td>`box_ai_extract_data`</td>
      <td>Extract data from a file using AI</td>

      <td>
        * `file_id (str)`: File ID.<br />
        * `fields (str)`: Fields to extract.
      </td>

      <td>Extracted data in JSON format</td>
    </tr>
  </tbody>
</table>

### Collaborations

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_collaboration_list_by_file_tool`</td>
      <td>List all collaborations on a specific file</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `file_id (str)`: ID of the Box file.
      </td>

      <td>List of collaborations in JSON format</td>
    </tr>

    <tr>
      <td>`box_collaboration_list_by_folder_tool`</td>
      <td>List all collaborations on a specific folder</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `folder_id (str)`: ID of the Box folder.
      </td>

      <td>List of collaborations in JSON format</td>
    </tr>

    <tr>
      <td>`box_collaboration_delete_tool`</td>
      <td>Delete a specific collaboration</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `collaboration_id (str)`: ID of the collaboration.
      </td>

      <td>Deletion confirmation</td>
    </tr>

    <tr>
      <td>`box_collaboration_file_group_by_group_id_tool`</td>
      <td>Add a group as a collaborator to a file</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `file_id (str)`: ID of the Box file.<br />
        * `group_id (str)`: ID of the group.<br />
        * `role (str, optional)`: Collaboration role (default: "editor").
      </td>

      <td>Created collaboration details</td>
    </tr>
  </tbody>
</table>

### Groups

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_groups_search_tool`</td>
      <td>Search for groups by name (partial match)</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `query (str)`: Search query.
      </td>

      <td>List of matching groups in JSON format</td>
    </tr>

    <tr>
      <td>`box_groups_list_members_tool`</td>
      <td>List all members of a specific group</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `group_id (str)`: ID of the group.
      </td>

      <td>List of group members in JSON format</td>
    </tr>

    <tr>
      <td>`box_groups_list_by_user_tool`</td>
      <td>List all groups that a specific user belongs to</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `user_id (str)`: ID of the user.
      </td>

      <td>List of groups in JSON format</td>
    </tr>
  </tbody>
</table>

### Users

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_users_list_tool`</td>
      <td>List all users in the Box account</td>

      <td>
        * `ctx (Context)`: Request context.
      </td>

      <td>List of users in JSON format</td>
    </tr>

    <tr>
      <td>`box_users_locate_by_name_tool`</td>
      <td>Locate a user by their name (exact match)</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `name (str)`: Name of the user.
      </td>

      <td>User details in JSON format</td>
    </tr>

    <tr>
      <td>`box_users_locate_by_email_tool`</td>
      <td>Locate a user by their email address (exact match)</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `email (str)`: Email address.
      </td>

      <td>User details in JSON format</td>
    </tr>

    <tr>
      <td>`box_users_search_by_name_or_email_tool`</td>
      <td>Search for users by name or email (partial match)</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `query (str)`: Search query.
      </td>

      <td>List of matching users in JSON format</td>
    </tr>
  </tbody>
</table>

### Box Shared Links

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_shared_link_file_get_tool`</td>
      <td>Get a shared link for a file</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `file_id (str)`: ID of the file.
      </td>

      <td>Shared link details in JSON format</td>
    </tr>

    <tr>
      <td>`box_shared_link_file_create_or_update_tool`</td>
      <td>Create or update a shared link for a file</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `file_id (str)`: ID of the file.<br />
        * `access (str, optional)`: Access level.<br />
        * `can_download (bool, optional)`: Can download.<br />
        * `can_preview (bool, optional)`: Can preview.<br />
        * `can_edit (bool, optional)`: Can edit.<br />
        * `password (str, optional)`: Password.<br />
        * `vanity_name (str, optional)`: Vanity name.<br />
        * `unshared_at (str, optional)`: Expiration date.
      </td>

      <td>Created/updated shared link details in JSON format</td>
    </tr>
  </tbody>
</table>

### Box Tools Web Link

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_web_link_create_tool`</td>
      <td>Create a Box web link</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `url (str)`: URL of the web link.<br />
        * `parent_folder_id (str)`: Parent folder ID.<br />
        * `name (str, optional)`: Name of the web link.<br />
        * `description (str, optional)`: Description.
      </td>

      <td>Created web link details in JSON format</td>
    </tr>

    <tr>
      <td>`box_web_link_get_by_id_tool`</td>
      <td>Get a Box web link by its ID</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `web_link_id (str)`: ID of the web link.
      </td>

      <td>Web link details in JSON format</td>
    </tr>

    <tr>
      <td>`box_web_link_update_by_id_tool`</td>
      <td>Update a Box web link by its ID</td>

      <td>
        * `ctx (Context)`: Request context.<br />
        * `web_link_id (str)`: ID of the web link.<br />
        * `url (str)`: New URL.
      </td>

      <td>Updated web link details in JSON format</td>
    </tr>
  </tbody>
</table>

### Box Doc Gen

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_docgen_create_batch_tool`</td>
      <td>Generate documents using a template</td>

      <td>
        * `file_id (str)`: Template file ID.
        * `destination_folder_id (str)`: Output folder ID.
        * `user_input_file_path (str)`: JSON input data path.
        * `output_type (str, optional)`: Output format.
      </td>

      <td>Batch generation result</td>
    </tr>

    <tr>
      <td>`box_docgen_get_job_tool`</td>
      <td>Fetch a Doc Gen job by ID</td>
      <td>`job_id (str)`: Job identifier</td>
      <td>Job details in JSON</td>
    </tr>

    <tr>
      <td>`box_docgen_list_jobs_tool`</td>
      <td>List all Doc Gen jobs</td>

      <td>
        * `marker (str, optional)`: Pagination marker.
        * `limit (int, optional)`: Max jobs to return.
      </td>

      <td>List of jobs in JSON</td>
    </tr>

    <tr>
      <td>`box_docgen_list_jobs_by_batch_tool`</td>
      <td>List jobs in a specific batch</td>

      <td>
        * `batch_id (str)`: Batch identifier.
        * `marker (str, optional)`: Pagination marker.
        * `limit (int, optional)`: Max jobs to return.
      </td>

      <td>Batch jobs details</td>
    </tr>

    <tr>
      <td>`box_docgen_template_create_tool`</td>
      <td>Mark a file as a template</td>
      <td>`file_id (str)`: File ID to mark</td>
      <td>Template details</td>
    </tr>

    <tr>
      <td>`box_docgen_template_list_tool`</td>
      <td>List all available templates</td>

      <td>
        * `marker (str, optional)`: Pagination marker.
        * `limit (int, optional)`: Max templates to list.
      </td>

      <td>List of templates</td>
    </tr>

    <tr>
      <td>`box_docgen_template_delete_tool`</td>
      <td>Remove template marking</td>
      <td>`template_id (str)`: Template identifier</td>
      <td>Deletion confirmation</td>
    </tr>

    <tr>
      <td>`box_docgen_template_get_by_id_tool`</td>
      <td>Get template details</td>
      <td>`template_id (str)`: Template identifier</td>
      <td>Template details</td>
    </tr>

    <tr>
      <td>`box_docgen_template_list_tags_tool`</td>
      <td>List template tags</td>

      <td>
        * `template_id (str)`: Template ID.
        * `template_version_id (str, optional)`: Version ID.
        * `marker (str, optional)`: Pagination marker.
        * `limit (int, optional)`: Max tags to return.
      </td>

      <td>List of tags</td>
    </tr>

    <tr>
      <td>`box_docgen_template_list_jobs_tool`</td>
      <td>List jobs using a template</td>

      <td>
        * `template_id (str)`: Template identifier.
        * `marker (str, optional)`: Pagination marker.
        * `limit (int, optional)`: Max jobs to list.
      </td>

      <td>Job details</td>
    </tr>
  </tbody>
</table>

### Box Metadata

<table>
  <thead>
    <tr>
      <th>Tool</th>
      <th>Description</th>
      <th>Parameters</th>
      <th>Returns</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`box_metadata_template_get_by_key_tool`</td>
      <td>Retrieves a metadata template by its key.</td>

      <td>
        `template_name (str)`: The key of the metadata template to retrieve.
      </td>

      <td>The metadata template associated with the provided key.</td>
    </tr>

    <tr>
      <td>`box_metadata_template_get_by_name_tool`</td>
      <td>Retrieve a metadata template by its name.</td>
      <td>`template_name (str)`: The name of the metadata template to retrieve.</td>
      <td>The metadata template associated with the provided name.</td>
    </tr>

    <tr>
      <td>`box_metadata_template_create_tool`</td>
      <td>Create a metadata template.</td>

      <td>
        * `ctx (Context)`: The context object
        * `display_name (str)`: The display name of the metadata template
        * `fields (List[Dict[str, Any]])`: A list of field definitions with type, key, displayName, description, hidden, and options (for enum/multiSelect)
        * `template_key (Optional[str])`: An optional key for the metadata template
      </td>

      <td>The created metadata template.</td>
    </tr>

    <tr>
      <td>`box_metadata_set_instance_on_file_tool`</td>
      <td>Set a metadata instance on a file.</td>

      <td>
        * `ctx (Context)`: The context object
        * `template_key (str)`: The key of the metadata template
        * `file_id (str)`: The ID of the file to set metadata on
        * `metadata (dict)`: The metadata values to set
      </td>

      <td>The metadata instance associated with the file.</td>
    </tr>

    <tr>
      <td>`box_metadata_update_instance_on_file_tool`</td>
      <td>Update a metadata instance on a file.</td>

      <td>
        * `ctx (Context)`: The context object
        * `file_id (str)`: The ID of the file to update metadata on
        * `template_key (str)`: The key of the metadata template
        * `metadata (dict)`: The metadata values to update
        * `remove_non_included_data (bool)`: If True, removes fields not included in metadata
      </td>

      <td>The response from the Box API after updating the metadata.</td>
    </tr>

    <tr>
      <td>`box_metadata_delete_instance_on_file_tool`</td>
      <td>Delete a metadata instance on a file.</td>

      <td>
        * `ctx (Context)`: The context object
        * `file_id (str)`: The ID of the file to delete metadata from
        * `template_key (str)`: The key of the metadata template
      </td>

      <td>The response from the Box API after deleting the metadata.</td>
    </tr>
  </tbody>
</table>

## Troubleshooting

In case of an `Error: spawn uv ENOENT` on MacOS when running the MCP server with Claude Desktop, you can:

* Remove `uv` and reinstall it with Homebrew: `brew install uv`.
* Provide the full path to the `uv` executable in your configuration:

```sh theme={null}
/Users/USER_NAME/.local/bin/uv --directory /Users/USER_NAME/local/mcp-server-box run src/mcp_server_box.py
```

In case of additional issues related to setup, post your question on our [Developer Community forum](https://community.box.com/ai-developers-23).


# Set up the MCP server
Source: https://developer.box.com/guides/box-mcp/setup



Use these steps to enable Box’s hosted MCP endpoint (`https://mcp.box.com`) and connect your client or agent platform.

## Access and manage predefined Box MCP servers

1. Click **Integrations** in the sidebar of Box Admin Console.
2. Use *Categories* filter and choose MCP or search for a predefined Box MCP server in the search field at the top of the window.
3. Beside the selected MCP server, click the state, then select the state you want to enable.

<Frame>
  <img alt="MCP" />
</Frame>

## Create an unlisted Box MCP server

1. Click **Integrations** in the sidebar of Box Admin Console.
2. Search for **Box MCP server** in the search field at the top of the window.
3. Hover on the **Box MCP server** application, then click **Configure**.
4. In the **Additional Configuration** section, click on **+ Add Integration Credentials**.
5. Enter integration name and click **Save**.
6. Expand details of the newly created entry.
7. Copy the generated **Client ID** and **Client Secret**.
8. Enter the **Redirect URI** provided by the external MCP client.
9. Select desired **Access Scopes**.
   * **Scopes** define the maximum set of actions. Users can only access content they already have permission to view or edit in Box.

## Add Box MCP server on the client side

Exact steps for adding Box MCP server may vary depending on the AI platform. Refer to your platform’s documentation for client-side setup instructions. Check this sample code for reference:

To connect to Box from the AI Agent platform, you need to:

* Add endpoint URL: `https://mcp.box.com`
* Pass client ID and client secret. Box generates these in the Integration Credentials section of your Admin Console when configuring the Box MCP server, above.
* Pass an MCP name: `box-remote-mcp`
* Provide an `authorization_token`

Sometimes, the client may request the authorization URL, token exchange URL, and scopes. For the Box MCP server, use the following values:

* Authorization URL: `https://account.box.com/api/oauth2/authorize`
* Token Exchange URL: `https://api.box.com/oauth2/token`
* Scopes: `root_readwrite`, `ai.readwrite`, and `docgen.readwrite`. The `docgen.readwrite` scope requires an Enterprise Advanced license.

```python theme={null}
  response = await client.beta.messages.create(
      model="claude-3-opus-20240229",  # Or your preferred model
      max_tokens=4096,
      messages=conversation_history,
      mcp_servers=[
          {
              "type": "url",
              "url": "https://mcp.box.com",
              "name": "box-remote-mcp",
              "authorization_token": BEARER_TOKEN,
          }
      ],
      betas=["mcp-client-2025-04-04"]
  )
```

## Using Box AI features with the MCP server

When you use Box AI in third-party applications, you can achieve the best experience and highest quality results by accessing the applications through the Box MCP server. This ensures full functionality, improved performance, and a seamless user experience.

For the tools agents can call after setup, see [Available tools](/guides/box-mcp/tools).


# Available tools
Source: https://developer.box.com/guides/box-mcp/tools

Reference list of Box MCP server tools by category, including which tools an admin must turn on before agents can use them.

The Box MCP server provides tools that let AI agents interact with Box content and features. Tools are organized by category so you can quickly find the right capabilities for your scenario.

Tools marked **Off** in the **Default** column need an admin to turn them on. See [Manage tool access](https://docs.box.com/en/box-mcp/admin-controls) in Box product documentation for instructions.

## User and authentication

Manage user authentication and retrieve information about the authenticated user.

| Tool | Description | Default |
| - | - | - |
| `who_am_i` | Returns detailed information about the currently authenticated Box user. | On |

## Files and folders

Access, manage, and modify Box file and folder resources. These tools give you control over content, metadata, and versioning.

### Read-only

| Tool | Description | Default |
| - | - | - |
| `get_download_url` | Issues a temporary, single-use URL for downloading binary files from Box. See [Upload and download URL tools](#upload-and-download-url-tools) for additional configuration details. | Off |
| `get_file_content` | Returns the content of a file stored in Box. | On |
| `get_file_details` | Returns detailed file information from Box, including metadata, permissions, and version details. | On |
| `get_file_preview` | Returns the preview widget for a file stored in Box. | On |
| `get_folder_details` | Retrieves detailed folder information, including metadata, permissions, and collaboration settings. | On |
| `list_folder_content_by_folder_id` | Lists files, folders, and web links in a folder (paginated). <br /> Use `folder_id` "0" for the root folder. `id`, `type`, `name`, and `etag` are always returned. Optional field: `limit`. | On |

### Write

| Tool | Description | Default |
| - | - | - |
| `copy_file` | Copies an existing file to a destination folder in Box. | On |
| `copy_folder` | Copies an existing folder to a destination parent folder in Box. | On |
| `create_folder` | Creates a folder in Box. | On |
| `create_metadata_template` | Creates an enterprise metadata template. Requires the `enterprise` scope, `display_name`, and an optional `fields` array. | On |
| `get_upload_url` | Issues a temporary, single-use URL for uploading binary files to Box. See [Upload and download URL tools](#upload-and-download-url-tools) for additional configuration details. | Off |
| `move_file` | Moves an existing file to a destination folder in Box. The file ID stays the same and `parent_folder_id` is required. | Off |
| `move_folder` | Moves a folder to a new parent in Box. The folder ID stays the same and `parent_folder_id` is required. | Off |
| `set_file_metadata` | Creates or updates (upserts) custom metadata on a file for a template. Use `list_metadata_templates` and `get_metadata_template_schema` to find the `scope`, `template_key`, and `fields`. | Off |
| `set_folder_metadata` | Creates or updates (upserts) custom metadata on a folder for a template. Use `list_metadata_templates` and `get_metadata_template_schema` to find the `scope`, `template_key`, and `fields`. | Off |
| `update_file_properties` | Updates file properties, including name, description, tags, and collections. The name can have up to 255 characters, and the file extension is preserved unless you specify otherwise. The description can have up to 256 characters. You can add or update up to 100 tags. | Off |
| `update_folder_properties` | Updates folder properties, including name, description, tags, and collections. The name can have up to 255 characters and must not include `/`, `\`, `.`, `..`, or leading or trailing spaces. The description can have up to 256 characters. You can update up to 100 tags. | Off |
| `update_metadata_template` | Updates a metadata template by scope and `template_key` using atomic schema operations (for example, `addField`, `editField`, and `removeField`). | Off |
| `upload_file` | Uploads a new file to Box. | On |
| `upload_file_version` | Uploads a new file version by providing the entire file contents to update an existing file in Box. | Off |

## Search

Locate content and containers using keywords, names, or structured metadata queries with optional filters and scopes.

| Tool | Description | Default |
| - | - | - |
| `get_metadata_template_schema` | Returns the schema and field keys for a metadata template. | On |
| `list_metadata_templates` | Lists available Box metadata templates (enterprise or global). | On |
| `search_files_keyword` | Searches for files using keywords. Supports metadata filters, file-extension filtering, and field selection. | On |
| `search_files_metadata` | Searches for files using SQL-like metadata queries. Supports complex filtering with parameters, field selection, and folder scoping. | On |
| `search_folders_by_name` | Searches for folders in Box by name using keyword matching. | On |

## Collaboration

Enable team collaboration through comments, shared links, and collaboration management tools.

### Read-only

| Tool | Description | Default |
| - | - | - |
| `list_file_comments` | Lists all comments on a file. | On |
| `list_item_collaborations` | Lists all existing collaborations on an item. | On |
| `list_tasks` | Lists all tasks for a file, including status, message, and due dates. | On |

### Write

| Tool | Description | Default |
| - | - | - |
| `add_file_shared_link` | Creates or updates a shared link for a Box file. Can create open shared links or add collaborators from outside your organization. | Off |
| `add_folder_shared_link` | Creates or updates a shared link for a Box folder. Can create open shared links or add collaborators from outside your organization. | Off |
| `create_collaboration` | Invites a user or group to a file, folder, or hub. Can create open shared links or add collaborators from outside your organization. | Off |
| `create_file_comment` | Creates a comment on a file. | On |
| `update_collaboration` | Updates a file, folder, or hub collaboration. Can create open shared links or add collaborators from outside your organization. | Off |

## Box AI

Use AI-powered tools to ask questions, extract insights, and analyze content across files and hubs.

| Tool | Description | Default |
| - | - | - |
| `ai_extract_freeform` | Extracts metadata from files using Box AI with natural-language prompts (no fixed template). <br /> Text representation up to 1 MB. Supports documents, PDFs, presentations, and text. Works with one or more `file_ids`. | On |
| `ai_extract_structured` | Extracts structured key-value metadata from files using the Box AI Enhanced Extract Agent and custom field definitions. | On |
| `ai_extract_structured_from_fields` | Extracts structured metadata from files using Box AI and custom field definitions. <br /> Works with one or more files. Field types include `string`, `date`, `float`, `enum`, and `multiSelect`. | On |
| `ai_extract_structured_from_fields_enhanced` | Extracts structured metadata from files using the Box AI Enhanced Extract Agent and custom field definitions. <br /> Use only when the user asks for the Enhanced Extract Agent. This tool costs more than the standard Box AI Extract tools. Field types include `string`, `date`, `float`, `enum`, and `multiSelect`. | On |
| `ai_extract_structured_from_metadata_template` | Extracts structured metadata from files using an existing Box metadata template. <br /> Requires `template_key` and `scope` (for example, `enterprise` or `global`). <br /> Processes the text representation of file content. | On |
| `ai_extract_structured_from_metadata_template_enhanced` | Extracts structured metadata from files using an existing Box metadata template and the Enhanced Extract Agent. <br /> Use only when the user asks for the Enhanced Extract Agent. This tool costs more than the standard Box AI Extract tools. | On |
| `ai_qa_hub` | Asks a question about a Box hub and returns an answer based on the hub's content, with citations when available. | On |
| `ai_qa_multi_file` | Asks a question about multiple files using Box AI, with citations when available. | On |
| `ai_qa_single_file` | Asks a question about a single file using Box AI, with citations when available. <br /> Text representation up to 1 MB. If the file is larger, only the first 1 MB is processed. | On |

## Hubs

Create and manage Box Hubs for organizing collaborative content and resources around specific topics or projects.

### Read-only

| Tool | Description | Default |
| - | - | - |
| `get_hub_details` | Retrieves detailed information about a specific hub. | On |
| `get_hub_items` | Gets items (files and folders) associated with a specific hub. | On |
| `list_hubs` | Lists all hubs that the authenticated user can access. | On |

### Write

| Tool | Description | Default |
| - | - | - |
| `add_items_to_hub` | Adds files, folders, or web links to a hub. | On |
| `copy_hub` | Creates a copy of an existing hub, including its structure and settings. The original hub is not modified. The new title can have up to 50 characters; if you do not provide one, a default title is used. | On |
| `create_hub` | Creates a hub. | On |
| `update_hub` | Updates the title and description of a hub. | Off |

## Doc Gen

Automate document generation by using templates with placeholder tags to create custom documents at scale.

### Read-only

| Tool | Description | Default |
| - | - | - |
| `get_docgen_template_by_id` | Retrieves details about a Doc Gen template. | On |
| `list_docgen_templates` | Lists all Box Doc Gen templates that the authenticated user can access. | On |

### Write

| Tool | Description | Default |
| - | - | - |
| `create_docgen_batch` | Generates documents from a Doc Gen template by filling placeholder tags with provided data. | Off |
| `create_docgen_template` | Marks a Box file (`.docx` or `.pptx`) as a Doc Gen template for automated document generation. | On |

## Upload and download URL tools

The upload and download URL tools require the AI agent to make a direct network request to transfer the file. Declarative agents can't make these requests, so these tools work only in agentic (code-executing) environments.

Some clients require you to allowlist specific domains before upload and download URLs work.

If you're not a Box Zones customer, add the following domains to your allowlist:

```
upload.box.com
upload.app.box.com
upload.ent.box.com
dl.boxcloud.com
public.boxcloud.com
```

The domains you need vary depending on your Box Zone. For the full list, see [Configuring A Firewall For Box Applications and Services](https://docs.box.com/en/box-admin-tools/box-security/configuring-a-firewall-for-box-applications-and-services).

You can also use wildcard domains to allow all subdomains:

```
upload.*.box.com
*.boxcloud.com
*.box.com
```

## Feedback

To share feedback or ask questions about the Box MCP server, visit the [Box AI API thread](https://community.box.com/box-ai-api-8) in the Box Developer Community forum.


# Box Mount
Source: https://developer.box.com/guides/box-mount

Mount a Box folder into an agent runtime as a POSIX filesystem, kept in two-way sync, with Box permissions and governance applied to every operation.

Box Mount brings Box content into any agent runtime as a standard POSIX filesystem. Agents read, write, and edit files using familiar file operations, with Box security, governance, and access controls applied to every operation. Continuous two-way sync keeps agent and Box content aligned, so people and agents collaborate in the same folders with built-in conflict protection.

<Note>
  Box Mount is in private preview. It is not publicly available, it is not covered by a production SLA, and features can change before general availability. Box provides the binary and setup guidance to preview participants. To request access, complete the [Box Mount private preview form](https://bit.ly/box-mount-preview).
</Note>

## How Box Mount works

Box Mount runs a background sync process, the daemon, that maps a Box folder to a local directory inside the sandbox your product provisions. It works with any supported Linux sandbox, including Daytona, Docker, E2B, and Vercel Sandbox, and is not tied to one vendor.

* **Content stays in Box.** Your agent works against a local path, and every operation flows through the Box API.
* **Governance follows the content.** Every operation runs as the identity Box Mount authenticates with, so that identity's permissions, retention, legal hold, ethical walls, and audit trail apply to the agent, along with any Box Shield security policies driven by classification. In OAuth mode the identity is the user who authorized the app, so the agent can never reach content that the user cannot. In JWT mode the identity is the service account, so scope that account to the content the agent needs.
* **Sync runs both ways.** Changes an agent makes in the mount upload to Box, and updates from people or other agents are reflected back in the mount.
* **Conflicts are preserved, not overwritten.** When two writers change the same file at the same time, Box Mount detects the conflict at upload and keeps both results, either as a new Box version or as a separate conflict copy, so a reviewer can merge the work or roll back using Box version history.

Because the agent works with plain files, most tools work against Box content without knowing it is Box. Read [Known limitations](#known-limitations) first, because applications that save a file by replacing it rather than editing it in place behave differently.

## See Box Mount in action

This demo builds a contract review agent that mounts a Box folder into an E2B sandbox, runs the agent against that workspace, and syncs the finished review back to Box for a person to review.

<iframe title="Build a Contract Review Agent with Box Mount and E2B" />

For the architecture behind the demo and more workflow patterns, read [Meet Box Mount: A Box workspace for sandboxed AI agents](https://blog.box.com/meet-box-mount-box-workspace-sandboxed-ai-agents) on the Box blog.

## Before you begin

You need:

* Access to the Box Mount private preview, including the Box Mount binary. To request access, complete the [Box Mount private preview form](https://bit.ly/box-mount-preview).
* A Box app in the [Developer Console](https://app.box.com/developers/console), configured for either [OAuth 2.0](/guides/authentication/oauth2/oauth2-setup) or [JWT](/guides/authentication/jwt/jwt-setup) authentication.
* The ID of the Box folder you want to mount. This is the number at the end of the folder URL on Box.

### Supported platforms

Box Mount supports Linux runtimes on the x86\_64 and ARM64 architectures. macOS is not supported.

## Commands

| Command | What it does |
| - | - |
| `box-mount config` | Configures credentials and sync settings interactively |
| `box-mount mount "<local-dir>" "<box-id>"` | Mounts a Box folder to `<local-dir>`, an absolute local path. `<box-id>` is the Box folder ID |
| `box-mount status` | Reports the state of the current mount |
| `box-mount unmount "<local-dir>"` | Unmounts the local directory, using its absolute path |
| `box-mount unmount --reset-force "<local-dir>"` | Unmounts and force-deletes all local mount contents |

A first session looks like this:

```bash theme={null}
box-mount config
mkdir -p /mnt/box
box-mount mount "/mnt/box" "123456789"
box-mount status
```

Your agent now works against `/mnt/box`.

## Configure credentials

Box Mount reads Box credentials from a `box-config.json` file in `~/.box-mount/`, or in the path you pass to `--data-path`.

The `config` command handles configuration interactively in one step and writes `~/.box-mount/box-config.json`:

```bash theme={null}
box-mount config
```

Box Mount supports two authentication modes, OAuth and JWT. OAuth is the default. Enter `oauth` or `jwt` when prompted. Restrict the config file, and any JWT private key JSON it points at, as described in [Secure your credentials](#secure-your-credentials).

### Configure OAuth manually

Create `~/.box-mount/box-config.json` and fill in your Box app credentials:

```json theme={null}
{
  "client_id":     "YOUR_BOX_CLIENT_ID",
  "client_secret": "YOUR_BOX_CLIENT_SECRET",
  "access_token":  "",
  "refresh_token": "",
  "redirect_uri":  "http://localhost:3000/callback"
}
```

| Field | Required | Notes |
| - | - | - |
| `client_id` | Yes | From the Developer Console |
| `client_secret` | Yes | From the Developer Console |
| `access_token` | Yes | Run `box-mount config` to obtain one through OAuth |
| `refresh_token` | OAuth only | Run `box-mount config` to obtain one through OAuth. Rotated on every refresh |
| `redirect_uri` | No | Must match the Box app setting exactly. Used when configuring OAuth |

The OAuth config has no `auth_type` field because OAuth is the default mode. Set `auth_type` only to switch to JWT.

### Configure JWT manually

For a JWT service account, the config needs only two fields:

```json theme={null}
{
  "auth_type": "jwt",
  "jwt_config_path": "/path/to/box-jwt-config.json"
}
```

| Field | Required | Notes |
| - | - | - |
| `auth_type` | Yes | Must be `jwt` |
| `jwt_config_path` | Yes | Absolute path to the Developer Console JWT JSON |

`jwt_config_path` must point to the JSON file generated by the Developer Console. To create it, open your app's **Configuration** tab and, in **App Settings**, select **Generate a Public/Private Keypair**. JWT authentication does not need an `access_token` or a `refresh_token`, because the SDK obtains short-lived access tokens automatically.

### Use environment variables

You can supply credential fields through environment variables instead of the JSON file. Environment variables take precedence over file values, and the JSON file is optional when you provide every required field this way.

| Variable | Config key | Notes |
| - | - | - |
| `BOX_CLIENT_ID` | `client_id` | OAuth app client ID |
| `BOX_CLIENT_SECRET` | `client_secret` | OAuth app client secret |
| `BOX_ACCESS_TOKEN` | `access_token` | Current access token. Updated in-process and written back to the config file on refresh |
| `BOX_REFRESH_TOKEN` | `refresh_token` | Current refresh token. Same write-back behavior as the access token |
| `BOX_AUTH_TYPE` | `auth_type` | Set to `jwt` to enable JWT mode |
| `BOX_JWT_CONFIG_PATH` | `jwt_config_path` | Path to the Developer Console JWT JSON. JWT mode only |

<Warning>
  Do not persist `BOX_ACCESS_TOKEN` or `BOX_REFRESH_TOKEN` in shell startup files such as `.zprofile` or `.bashrc`. When Box Mount refreshes tokens it writes the new values to `~/.box-mount/box-config.json`, which leaves any copies baked into the environment stale, and stale tokens cause authentication failures on the next run. Export these variables only for the duration of a session.

  Do not put `BOX_*` credentials in the environment of an LLM agent or any other untrusted process. See [Secure your credentials](#secure-your-credentials).
</Warning>

### Use a developer token

[Developer tokens](/guides/authentication/tokens/developer-tokens) are short-lived tokens you generate in the Developer Console. They are valid for 60 minutes, cannot be refreshed, and are useful for quick testing without the full OAuth flow.

Set `access_token` in `~/.box-mount/box-config.json` and leave `refresh_token` empty:

```json theme={null}
{
  "client_id":     "YOUR_BOX_CLIENT_ID",
  "client_secret": "YOUR_BOX_CLIENT_SECRET",
  "access_token":  "PASTE_DEVELOPER_TOKEN_HERE",
  "refresh_token": ""
}
```

You can also pass the token through the environment and skip the config file:

```bash theme={null}
export BOX_ACCESS_TOKEN="PASTE_DEVELOPER_TOKEN_HERE"
box-mount mount "/local/path" "123456789"
```

Because developer tokens cannot be refreshed, Box Mount stops syncing when the token expires. Generate a new token in the Developer Console and update `access_token`, or re-export the environment variable, to resume.

## Token lifecycle

In OAuth mode:

* Access tokens expire after about 60 minutes, and the SDK refreshes them automatically.
* Each refresh rotates the refresh token, and the old one is invalidated immediately.
* Rotated tokens are written back to `~/.box-mount/box-config.json`.
* Refresh tokens expire after 60 days without use. Run `box-mount config` again to repeat the OAuth flow.

In JWT mode:

* The SDK signs a JWT assertion, exchanges it for a short-lived access token, and refreshes that token automatically. Tokens are held in memory only, so nothing is written to `box-config.json`.
* Authentication needs no user interaction as long as the JWT config JSON and private key are valid.

## Secure your credentials

Box credentials are a Box API identity, and that identity is usually broader than the folder you mount. This applies to the OAuth client secret and tokens in `box-config.json`, the `BOX_*` environment variables, and the JWT private key JSON on disk. Anyone who reads them can call the Box API as that app or user, not only read the files in the mount.

The daemon that `box-mount mount` starts needs those credentials, and the mount directory is the only surface other processes should share. Keep `~/.box-mount/`, which holds the config, database, process ID, and logs, private to the account that runs Box Mount.

### Recommended setup on an agent sandbox

When an LLM agent runs on the same machine as Box Mount, do not run the agent as the same Unix user as the daemon. Use two users:

| Role | Unix user | What it can access |
| - | - | - |
| Box Mount daemon | User A | `~/.box-mount/`, the JWT JSON, and the mount directory |
| LLM agent | User B | The mount directory only |

1. Create the two users. Run `box-mount config` as user A so that `~/.box-mount/` lives in the home directory of user A. Do not mount yet, because bootstrap fills the tree and the share permissions must be set on an empty mount directory first.

2. Restrict the credentials so that only user A can read them, then confirm ownership with `ls -l`. Mode `644`, which is world-readable, is not appropriate for these files.

   ```bash theme={null}
   chmod 700 ~/.box-mount
   chmod 600 ~/.box-mount/box-config.json
   chmod 600 /path/to/box-jwt-config.json   # JWT mode only
   ```

3. Share only the mount directory with user B, using a shared group, setgid, and a default POSIX ACL. Setgid copies group ownership onto new inodes, and the default ACL inherits group write access. Apply this to an empty directory, then mount. The `setfacl` command ships in the `acl` package.

   ```bash theme={null}
   sudo mkdir -p /path/to/mount
   sudo groupadd boxmount
   sudo usermod -aG boxmount userA
   sudo usermod -aG boxmount userB
   sudo chown userA:boxmount /path/to/mount
   sudo chmod 2770 /path/to/mount
   sudo setfacl -m g:boxmount:rwx -m d:g:boxmount:rwx /path/to/mount
   box-mount mount "/path/to/mount" "<box-id>"   # as user A
   ```

   User B must not have read access to the home directory of user A, to `--data-path`, or to the JWT file. User B must also be able to traverse every directory above the mount, which is why the example puts the mount outside any home directory. If you place the mount inside the home directory of user A instead, a home directory set to `750` blocks user B even when the mount directory itself is `2770`.

4. Start the agent as user B. Do not export `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET`, `BOX_ACCESS_TOKEN`, `BOX_REFRESH_TOKEN`, or `BOX_JWT_CONFIG_PATH` in the shell, systemd unit, or container spec of the agent. Those values are visible in the process environment and belong only to the daemon process of user A.

5. In JWT mode, use a service account scoped to the content the agent needs, rather than an enterprise admin keypair.

On a personal machine, where you are the only process using the mount, running Box Mount as your own user is expected, and follows the same model as SSH keys in `$HOME`. That layout is not appropriate when the other process is an untrusted agent.

<Warning>
  This isolation does not protect against root on the machine, kernel exploits, or running the agent as user A. It also does not reduce what the agent can do inside the mount, because user B has normal filesystem access to that tree.
</Warning>

## Data and log locations

By default, `--data-path` points to `~/.box-mount/`, and Box Mount derives all other paths from it:

| Path | Contents |
| - | - |
| `~/.box-mount/mount.json` | Mount record |
| `~/.box-mount/box-config.json` | Box credentials |
| `~/.box-mount/local-config.json` | Local sync settings |
| `~/.box-mount/data/` | `sync.sqlite3`, `bdlc.pid`, and `teardown.json`, which is present only during an incomplete reset or unmount |
| `~/.box-mount/logs/` | `box-mount-sync.stdout.log` and `box-mount-sync.stderr.log` for daemon output, plus a `box-mount-sync-YYYYMMDD-HHMMSS-ffffff.log` file for each run |

Treat this tree as private to the daemon. See [Secure your credentials](#secure-your-credentials).

## Known limitations

### No support for atomic save

Box Mount does not support atomic save, also called safe write, where an application saves a file by writing a temporary file and renaming it over the original instead of editing in place. Files saved this way lose their Box version history, because Box Mount syncs the replacement as a new file rather than as a new version of the existing file.

### Workload limits

For the preview, use non-production workloads of up to 5 GB of content and 10,000 files per mount.

## Related tools

Box Mount complements the other ways agents reach Box content. Use Box Mount when an agent needs to do file work in place, and use the following tools for API-level and command-line access:

| Tool | Use it for |
| - | - |
| [Box MCP server](/guides/box-mcp) | Giving agents tool-based access to Box search, Box AI, and file operations |
| [Box CLI](/guides/cli) | Running routine or bulk Box actions from the command line |
| [Box SDKs](/guides/tooling/sdks) | Building applications directly against the Box API |


# AI resources
Source: https://developer.box.com/reference/ai-resources



A set of endpoints used to interact with supported LLMs.

## AI agent for extract requests

The AI agent to be used for extraction.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent to be used for extraction. Available options: `ai_agent_extract`. |
  | `long_text` | `AI agent long text tool` | No | |
  | `basic_text` | `AI agent basic text tool` | No | |
  | `basic_image` | `AI agent basic text tool` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_extract",
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      }
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    }
  }
  ```
</Accordion>

## AI agent for question requests

The AI agent used to handle queries.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent used to handle queries. Available options: `ai_agent_ask`. |
  | `long_text` | `AI agent long text tool` | No | |
  | `basic_text` | `AI agent basic text tool` | No | |
  | `spreadsheet` | `AI agent spreadsheet tool` | No | |
  | `long_text_multi` | `AI agent long text tool` | No | |
  | `basic_text_multi` | `AI agent basic text tool` | No | |
  | `basic_image` | `AI agent basic text tool` | No | |
  | `basic_image_multi` | `AI agent basic text tool` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_ask",
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      }
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    },
    "spreadsheet": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      }
    },
    "long_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      }
    },
    "basic_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    },
    "basic_image_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    }
  }
  ```
</Accordion>

## AI agent for structured extract request

The AI agent to be used for structured extraction.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent to be used for extraction. Available options: `ai_agent_extract_structured`. |
  | `long_text` | `AI agent long text tool` | No | |
  | `basic_text` | `AI agent basic text tool` | No | |
  | `basic_image` | `AI agent basic text tool` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_extract_structured",
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      }
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`."
    }
  }
  ```
</Accordion>

## AI agent for text generation requests

The AI agent used for generating text.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent used for generating text. Available options: `ai_agent_text_gen`. |
  | `basic_gen` | `AI agent basic text generation tool` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_text_gen",
    "basic_gen": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "content_template": "---{content}---"
    }
  }
  ```
</Accordion>

## AI agent reference

The AI agent used to handle queries.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent used to handle queries. Available options: `ai_agent_id`. |
  | `id` | `string` | Yes | The ID of an Agent. This can be a numeric ID for custom agents (for example, `14031`) or a unique identifier for pre-built agents (for example, `enhanced_extract_agent` for the [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent)). |

  ```json Example theme={null}
  {
    "type": "ai_agent_id",
    "id": "14031"
  }
  ```
</Accordion>

## AI extract response

AI extract response. The content of this response may vary depending on the requested configuration.

<Accordion title="Attributes and example">
  ```json Example theme={null}
  {}
  ```
</Accordion>

## AI extract structured response

AI extract structured response.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `answer` | [AI extract response](#ai-extract-response) | Yes | |
  | `created_at` | `string` | Yes | The ISO date formatted timestamp of when the answer to the prompt was created. |
  | `completion_reason` | `string` | No | The reason the response finishes. |
  | `confidence_score` | `object` | No | The confidence score levels and numeric values for each extracted field as a JSON dictionary. This can be empty if no field could be extracted. |
  | `reference` | `object` | No | The reference for each extracted field as a JSON dictionary. This can be empty if no field could be extracted. |
  | `ai_agent_info` | `The information on the models and processors used in the request.` | No | |

  ```json Example theme={null}
  {
    "answer": {},
    "created_at": "2012-12-12T10:53:43-08:00",
    "completion_reason": "done",
    "confidence_score": {},
    "reference": {},
    "ai_agent_info": {
      "models": [
        {
          "name": "azure__openai__text_embedding_ada_002",
          "provider": "azure",
          "supported_purpose": "embedding"
        }
      ],
      "processor": "basic_text"
    }
  }
  ```
</Accordion>

## AI response

AI response.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `answer` | `string` | Yes | The answer provided by the LLM. |
  | `created_at` | `string` | Yes | The ISO date formatted timestamp of when the answer to the prompt was created. |
  | `completion_reason` | `string` | No | The reason the response finishes. |
  | `ai_agent_info` | `The information on the models and processors used in the request.` | No | |

  ```json Example theme={null}
  {
    "answer": "Public APIs are important because of key and important reasons.",
    "created_at": "2012-12-12T10:53:43-08:00",
    "completion_reason": "done",
    "ai_agent_info": {
      "models": [
        {
          "name": "azure__openai__text_embedding_ada_002",
          "provider": "azure",
          "supported_purpose": "embedding"
        }
      ],
      "processor": "basic_text"
    }
  }
  ```
</Accordion>

## AI response (Full)

AI ask response.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `answer` | `string` | Yes | The answer provided by the LLM. |
  | `created_at` | `string` | Yes | The ISO date formatted timestamp of when the answer to the prompt was created. |
  | `completion_reason` | `string` | No | The reason the response finishes. |
  | `ai_agent_info` | `The information on the models and processors used in the request.` | No | |
  | `citations` | array of `The citation of the LLM's answer reference` | No | The citations of the LLM's answer reference. |

  ```json Example theme={null}
  {
    "answer": "Public APIs are important because of key and important reasons.",
    "created_at": "2012-12-12T10:53:43-08:00",
    "completion_reason": "done",
    "ai_agent_info": {
      "models": [
        {
          "name": "azure__openai__text_embedding_ada_002",
          "provider": "azure",
          "supported_purpose": "embedding"
        }
      ],
      "processor": "basic_text"
    },
    "citations": [
      {
        "content": "Public APIs are key drivers of innovation and growth.",
        "id": "123",
        "type": "file",
        "name": "The importance of public APIs.pdf"
      }
    ]
  }
  ```
</Accordion>


# AI Studio resources
Source: https://developer.box.com/reference/ai-studio-resources



A set of endpoints used to interact with AI Studio.

## AI agent

Standard representation of an AI Agent instance.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier of the AI Agent. |
  | `type` | `enum<string>` | No | The type of agent used to handle queries. Available options: `ai_agent`. |
  | `origin` | `string` | Yes | The provider of the AI Agent. |
  | `name` | `string` | Yes | The name of the AI Agent. |
  | `access_state` | `string` | Yes | The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who created this agent. |
  | `created_at` | `string` | No | The ISO date-time formatted timestamp of when this AI agent was created. |
  | `modified_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who most recently modified this agent. |
  | `modified_at` | `string` | No | The ISO date-time formatted timestamp of when this AI agent was recently modified. |
  | `icon_reference` | `string` | No | The icon reference of the AI Agent. |
  | `allowed_entities` | array of `The entity with type and ID` | No | List of allowed users or groups. |

  ```json Example theme={null}
  {
    "id": "1234567890",
    "type": "ai_agent",
    "origin": "CUSTOM",
    "name": "This is my Agent",
    "access_state": "enabled",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "created_at": "2022-01-01T00:00:00Z",
    "modified_by": {
      "id": "11446498",
      "type": "user"
    },
    "modified_at": "2022-01-01T00:00:00Z",
    "icon_reference": "https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg",
    "allowed_entities": [
      {
        "id": "11446498",
        "type": "user"
      }
    ]
  }
  ```
</Accordion>

## AI agent (Full)

Full representation of an AI Agent instance.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier of the AI Agent. |
  | `type` | `enum<string>` | No | The type of agent used to handle queries. Available options: `ai_agent`. |
  | `origin` | `string` | Yes | The provider of the AI Agent. |
  | `name` | `string` | Yes | The name of the AI Agent. |
  | `access_state` | `string` | Yes | The state of the AI Agent. Possible values are: `enabled`, `disabled`, and `enabled_for_selected_users`. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who created this agent. |
  | `created_at` | `string` | No | The ISO date-time formatted timestamp of when this AI agent was created. |
  | `modified_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who most recently modified this agent. |
  | `modified_at` | `string` | No | The ISO date-time formatted timestamp of when this AI agent was recently modified. |
  | `icon_reference` | `string` | No | The icon reference of the AI Agent. |
  | `allowed_entities` | array of `The entity with type and ID` | No | List of allowed users or groups. |
  | `ask` | [AI agent capability ask](#ai-agent-capability-ask) | No | |
  | `text_gen` | [AI agent capability text generation](#ai-agent-capability-text-generation) | No | |
  | `extract` | [AI agent capability extract](#ai-agent-capability-extract) | No | |

  ```json Example theme={null}
  {
    "id": "1234567890",
    "type": "ai_agent",
    "origin": "CUSTOM",
    "name": "This is my Agent",
    "access_state": "enabled",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "created_at": "2022-01-01T00:00:00Z",
    "modified_by": {
      "id": "11446498",
      "type": "user"
    },
    "modified_at": "2022-01-01T00:00:00Z",
    "icon_reference": "https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg",
    "allowed_entities": [
      {
        "id": "11446498",
        "type": "user"
      }
    ],
    "ask": {
      "type": "ai_agent_ask",
      "access_state": "enabled",
      "description": "This is ASK Agent",
      "custom_instructions": "This is a custom instruction",
      "suggested_questions": [
        "What is in this file?",
        "What are the main highlights of this document?"
      ],
      "long_text": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "embeddings": {
          "model": "azure__openai__text_embedding_ada_002",
          "strategy": {
            "id": "basic",
            "num_tokens_per_chunk": 64
          }
        },
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "basic_text": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "basic_image": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "spreadsheet": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "long_text_multi": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "embeddings": {
          "model": "azure__openai__text_embedding_ada_002",
          "strategy": {
            "id": "basic",
            "num_tokens_per_chunk": 64
          }
        },
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "basic_text_multi": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "basic_image_multi": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      }
    },
    "text_gen": {
      "type": "ai_agent_text_gen",
      "access_state": "enabled",
      "description": "This is ASK Agent",
      "custom_instructions": "This is a custom instruction",
      "suggested_questions": [
        "What is in this file?",
        "What are the main highlights of this document?"
      ],
      "basic_gen": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`",
        "embeddings": {
          "model": "azure__openai__text_embedding_ada_002",
          "strategy": {
            "id": "basic",
            "num_tokens_per_chunk": 64
          }
        },
        "content_template": "---{content}---",
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      }
    },
    "extract": {
      "type": "ai_agent_extract",
      "access_state": "enabled",
      "description": "This is ASK Agent",
      "custom_instructions": "This is a custom instruction",
      "long_text": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "embeddings": {
          "model": "azure__openai__text_embedding_ada_002",
          "strategy": {
            "id": "basic",
            "num_tokens_per_chunk": 64
          }
        },
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "basic_text": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      },
      "basic_image": {
        "model": "azure__openai__gpt_4o_mini",
        "num_tokens_for_completion": 8400,
        "llm_endpoint_params": {
          "type": "openai_params",
          "temperature": 0,
          "top_p": 1,
          "frequency_penalty": 1.5,
          "presence_penalty": 1.5,
          "stop": "<|im_end|>"
        },
        "system_message": "You are a helpful travel assistant specialized in budget travel",
        "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
        "is_custom_instructions_included": false,
        "warnings": [
          "MODEL_INACTIVE"
        ]
      }
    }
  }
  ```
</Accordion>

## AI agent capability ask

The AI agent to be used to ask questions.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent used to ask questions. Available options: `ai_agent_ask`. |
  | `access_state` | `string` | Yes | The state of the AI Agent capability. Possible values are: `enabled` and `disabled`. |
  | `description` | `string` | Yes | The description of the AI agent. |
  | `custom_instructions` | `string` | No | Custom instructions for the AI agent. Can be `null`. |
  | `suggested_questions` | array of `string` | No | Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed. |
  | `long_text` | `AI agent long text tool` | No | |
  | `basic_text` | `AI agent basic text tool` | No | |
  | `basic_image` | `AI agent basic text tool` | No | |
  | `spreadsheet` | `AI agent spreadsheet tool` | No | |
  | `long_text_multi` | `AI agent long text tool` | No | |
  | `basic_text_multi` | `AI agent basic text tool` | No | |
  | `basic_image_multi` | `AI agent basic text tool` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_ask",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "spreadsheet": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "long_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_image_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    }
  }
  ```
</Accordion>

## AI agent capability ask request

The AI agent to be used to handle queries.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent used to handle queries. Available options: `ai_agent_ask`. |
  | `access_state` | `string` | Yes | The state of the AI Agent capability. Possible values are: `enabled` and `disabled`. |
  | `description` | `string` | Yes | The description of the AI agent. |
  | `custom_instructions` | `string` | No | Custom instructions for the AI agent. Can be `null`. |
  | `suggested_questions` | array of `string` | No | Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed. |
  | `long_text` | `AI agent long text tool request` | No | |
  | `basic_text` | `AI agent basic text tool request` | No | |
  | `basic_image` | `AI agent basic text tool request` | No | |
  | `spreadsheet` | `AI agent spreadsheet tool` | No | |
  | `long_text_multi` | `AI agent long text tool request` | No | |
  | `basic_text_multi` | `AI agent basic text tool request` | No | |
  | `basic_image_multi` | `AI agent basic text tool request` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_ask",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "spreadsheet": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      }
    },
    "long_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false
    },
    "basic_text_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "basic_image_multi": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    }
  }
  ```
</Accordion>

## AI agent capability extract

The AI agent to be used for metadata extraction.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent to be used for metadata extraction. Available options: `ai_agent_extract`. |
  | `access_state` | `string` | Yes | The state of the AI Agent capability. Possible values are: `enabled` and `disabled`. |
  | `description` | `string` | Yes | The description of the AI agent. |
  | `custom_instructions` | `string` | No | Custom instructions for the AI agent. Can be `null`. |
  | `long_text` | `AI agent long text tool` | No | |
  | `basic_text` | `AI agent basic text tool` | No | |
  | `basic_image` | `AI agent basic text tool` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_extract",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    }
  }
  ```
</Accordion>

## AI agent capability extract request

The AI agent to be used for metadata extraction.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent to be used for metadata extraction. Available options: `ai_agent_extract`. |
  | `access_state` | `string` | Yes | The state of the AI Agent capability. Possible values are: `enabled` and `disabled`. |
  | `description` | `string` | Yes | The description of the AI agent. |
  | `custom_instructions` | `string` | No | Custom instructions for the AI agent. Can be `null`. |
  | `long_text` | `AI agent long text tool request` | No | |
  | `basic_text` | `AI agent basic text tool request` | No | |
  | `basic_image` | `AI agent basic text tool request` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_extract",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "long_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "is_custom_instructions_included": false
    },
    "basic_text": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    },
    "basic_image": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
      "is_custom_instructions_included": false
    }
  }
  ```
</Accordion>

## AI agent capability text generation

The AI agent to be used to generate text.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent used for generating text. Available options: `ai_agent_text_gen`. |
  | `access_state` | `string` | Yes | The state of the AI Agent capability. Possible values are: `enabled` and `disabled`. |
  | `description` | `string` | Yes | The description of the AI agent. |
  | `custom_instructions` | `string` | No | Custom instructions for the AI agent. Can be `null`. |
  | `suggested_questions` | array of `string` | No | Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed. |
  | `basic_gen` | `AI agent basic text generation tool` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_text_gen",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "basic_gen": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "content_template": "---{content}---",
      "is_custom_instructions_included": false,
      "warnings": [
        "MODEL_INACTIVE"
      ]
    }
  }
  ```
</Accordion>

## AI agent capability text generation request

The AI agent to be used to generate text.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of AI agent used for generating text. Available options: `ai_agent_text_gen`. |
  | `access_state` | `string` | Yes | The state of the AI Agent capability. Possible values are: `enabled` and `disabled`. |
  | `description` | `string` | Yes | The description of the AI agent. |
  | `custom_instructions` | `string` | No | Custom instructions for the AI agent. Can be `null`. |
  | `suggested_questions` | array of `string` | No | Suggested questions for the AI agent. If null, suggested question will be generated. If empty, no suggested questions will be displayed. |
  | `basic_gen` | `AI agent basic text generation tool request` | No | |

  ```json Example theme={null}
  {
    "type": "ai_agent_text_gen",
    "access_state": "enabled",
    "description": "This is ASK Agent",
    "custom_instructions": "This is a custom instruction",
    "suggested_questions": [
      "What is in this file?",
      "What are the main highlights of this document?"
    ],
    "basic_gen": {
      "model": "azure__openai__gpt_4o_mini",
      "num_tokens_for_completion": 8400,
      "llm_endpoint_params": {
        "type": "openai_params",
        "temperature": 0,
        "top_p": 1,
        "frequency_penalty": 1.5,
        "presence_penalty": 1.5,
        "stop": "<|im_end|>"
      },
      "system_message": "You are a helpful travel assistant specialized in budget travel",
      "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`",
      "embeddings": {
        "model": "azure__openai__text_embedding_ada_002",
        "strategy": {
          "id": "basic",
          "num_tokens_per_chunk": 64
        }
      },
      "content_template": "---{content}---",
      "is_custom_instructions_included": false
    }
  }
  ```
</Accordion>

## AI agents list

List of AI Agents with pagination.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [AI agent (Full)](#ai-agent-full) | Yes | The list of AI Agents. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "1234567890",
        "type": "ai_agent",
        "origin": "CUSTOM",
        "name": "This is my Agent",
        "access_state": "enabled",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "created_at": "2022-01-01T00:00:00Z",
        "modified_by": {
          "id": "11446498",
          "type": "user"
        },
        "modified_at": "2022-01-01T00:00:00Z",
        "icon_reference": "https://cdn01.boxcdn.net/app-assets/aistudio/avatars/logo_analytics.svg",
        "allowed_entities": [
          {
            "id": "11446498",
            "type": "user"
          }
        ],
        "ask": {
          "type": "ai_agent_ask",
          "access_state": "enabled",
          "description": "This is ASK Agent",
          "custom_instructions": "This is a custom instruction",
          "suggested_questions": [
            "What is in this file?",
            "What are the main highlights of this document?"
          ],
          "long_text": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "embeddings": {
              "model": "azure__openai__text_embedding_ada_002",
              "strategy": {
                "id": "basic",
                "num_tokens_per_chunk": 64
              }
            },
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "basic_text": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "basic_image": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "spreadsheet": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "long_text_multi": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "embeddings": {
              "model": "azure__openai__text_embedding_ada_002",
              "strategy": {
                "id": "basic",
                "num_tokens_per_chunk": 64
              }
            },
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "basic_text_multi": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "basic_image_multi": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          }
        },
        "text_gen": {
          "type": "ai_agent_text_gen",
          "access_state": "enabled",
          "description": "This is ASK Agent",
          "custom_instructions": "This is a custom instruction",
          "suggested_questions": [
            "What is in this file?",
            "What are the main highlights of this document?"
          ],
          "basic_gen": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, and I have $8000 and want to spend a week in the Azores. `{user_question}`",
            "embeddings": {
              "model": "azure__openai__text_embedding_ada_002",
              "strategy": {
                "id": "basic",
                "num_tokens_per_chunk": 64
              }
            },
            "content_template": "---{content}---",
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          }
        },
        "extract": {
          "type": "ai_agent_extract",
          "access_state": "enabled",
          "description": "This is ASK Agent",
          "custom_instructions": "This is a custom instruction",
          "long_text": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "embeddings": {
              "model": "azure__openai__text_embedding_ada_002",
              "strategy": {
                "id": "basic",
                "num_tokens_per_chunk": 64
              }
            },
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "basic_text": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          },
          "basic_image": {
            "model": "azure__openai__gpt_4o_mini",
            "num_tokens_for_completion": 8400,
            "llm_endpoint_params": {
              "type": "openai_params",
              "temperature": 0,
              "top_p": 1,
              "frequency_penalty": 1.5,
              "presence_penalty": 1.5,
              "stop": "<|im_end|>"
            },
            "system_message": "You are a helpful travel assistant specialized in budget travel",
            "prompt_template": "It is `{current_date}`, consider these travel options `{content}` and answer the `{user_question}`.",
            "is_custom_instructions_included": false,
            "warnings": [
              "MODEL_INACTIVE"
            ]
          }
        }
      }
    ]
  }
  ```
</Accordion>


# App item associations resources
Source: https://developer.box.com/reference/app-item-associations-resources



## App item

An app item represents an content object owned by an application. It can group files and folders together from different paths. That set can be shared via a collaboration.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this app item. |
  | `type` | `enum<string>` | Yes | The value will always be `app_item`. Available options: `app_item`. |
  | `application_type` | `string` | Yes | The type of the app that owns this app item. |

  ```json Example theme={null}
  {
    "id": "12345678",
    "type": "app_item",
    "application_type": "hubs"
  }
  ```
</Accordion>

## App item association

An app item association represents an association between a file or folder and an app item. Associations between a folder and an app item cascade down to all descendants of the folder.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this app item association. |
  | `type` | `enum<string>` | Yes | The value will always be `app_item_association`. Available options: `app_item_association`. |
  | `app_item` | [App item](#app-item) | Yes | The app item which is associated with the file or folder. |
  | `item` | `App item associated item` | Yes | |

  ```json Example theme={null}
  {
    "id": "12345678",
    "type": "app_item_association",
    "app_item": {
      "id": "12345678",
      "type": "app_item",
      "application_type": "hubs"
    },
    "item": {
      "id": "12345",
      "etag": "1",
      "type": "file"
    }
  }
  ```
</Accordion>

## App item associations

A list of app item associations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [App item association](#app-item-association) | No | |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345678",
        "type": "app_item_association",
        "app_item": {
          "id": "12345678",
          "type": "app_item",
          "application_type": "hubs"
        },
        "item": {
          "id": "12345",
          "etag": "1",
          "type": "file"
        }
      }
    ]
  }
  ```
</Accordion>


# Authorization resources
Source: https://developer.box.com/reference/authorization-resources



A set of endpoints used to manage user authorization process.

## Access token

A token that can be used to make authenticated API calls.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `access_token` | `string` | No | The requested access token. |
  | `expires_in` | `integer` | No | The time in seconds by which this token will expire. |
  | `token_type` | `enum<string>` | No | The type of access token returned. Available options: `bearer`. |
  | `restricted_to` | array of `Resource scope` | No | The permissions that this access token permits, providing a list of resources (files, folders, etc) and the scopes permitted for each of those resources. |
  | `refresh_token` | `string` | No | The refresh token for this access token, which can be used to request a new access token when the current one expires. |
  | `issued_token_type` | `enum<string>` | No | The type of downscoped access token returned. This is only returned if an access token has been downscoped. Available options: `urn:ietf:params:oauth:token-type:access_token`. |

  ```json Example theme={null}
  {
    "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
    "expires_in": 3600,
    "token_type": "bearer",
    "restricted_to": [
      {
        "scope": "item_download",
        "object": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      }
    ],
    "refresh_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
    "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
  }
  ```
</Accordion>

## OAuth 2.0 error

An OAuth 2.0 error.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `error` | `string` | No | The type of the error returned. |
  | `error_description` | `string` | No | The type of the error returned. |

  ```json Example theme={null}
  {
    "error": "invalid_client",
    "error_description": "The client credentials are not valid"
  }
  ```
</Accordion>


# Classifications resources
Source: https://developer.box.com/reference/classifications-resources



Classification labels are used for content that is sensitive or under security restrictions.

## Classification

An instance of the classification metadata template, containing the classification applied to the file or folder. To get more details about the classification applied to an item, request the classification metadata template.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `Box__Security__Classification__Key` | `string` | No | The name of the classification applied to the item. |
  | `$parent` | `string` | No | The identifier of the item that this metadata instance has been attached to. This combines the `type` and the `id` of the parent in the form `{type}_{id}`. |
  | `$template` | `enum<string>` | No | The value will always be `securityClassification-6VMVochwUWo`. Available options: `securityClassification-6VMVochwUWo`. |
  | `$scope` | `string` | No | The scope of the enterprise that this classification has been applied for. This will be in the format `enterprise_{enterprise_id}`. |
  | `$version` | `integer` | No | The version of the metadata instance. This version starts at 0 and increases every time a classification is updated. |
  | `$type` | `string` | No | The unique ID of this classification instance. This will be include the name of the classification template and a unique ID. |
  | `$typeVersion` | `number` | No | The version of the metadata template. This version starts at 0 and increases every time the template is updated. This is mostly for internal use. |
  | `$canEdit` | `boolean` | No | Whether an end user can change the classification. |

  ```json Example theme={null}
  {
    "Box__Security__Classification__Key": "Sensitive",
    "$parent": "folder_59449484661,",
    "$template": "securityClassification-6VMVochwUWo",
    "$scope": "enterprise_27335",
    "$version": 1,
    "$type": "securityClassification-6VMVochwUWo-fd31537a-0f95-4d86-9f2b-5974a29978f8",
    "$typeVersion": 5,
    "$canEdit": true
  }
  ```
</Accordion>

## Classification Template

A metadata template that holds the security classifications defined by an enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The ID of the classification template. |
  | `type` | `enum<string>` | Yes | The value will always be `metadata_template`. Available options: `metadata_template`. |
  | `scope` | `string` | Yes | The scope of the classification template. This is in the format `enterprise_{id}` where the `id` is the enterprise ID. |
  | `templateKey` | `enum<string>` | Yes | The value will always be `securityClassification-6VMVochwUWo`. Available options: `securityClassification-6VMVochwUWo`. |
  | `displayName` | `enum<string>` | Yes | The name of this template as shown in web and mobile interfaces. Available options: `Classification`. |
  | `hidden` | `boolean` | No | Determines if the template is always available in web and mobile interfaces. |
  | `copyInstanceOnItemCopy` | `boolean` | No | Determines if classifications are copied along when the file or folder is copied. |
  | `fields` | array of `object` | Yes | A list of fields for this classification template. This includes only one field, the `Box__Security__Classification__Key`, which defines the different classifications available in this enterprise. |

  ```json Example theme={null}
  {
    "id": "58063d82-4128-7b43-bba9-92f706befcdf",
    "type": "metadata_template",
    "scope": "enterprise_123456",
    "templateKey": "securityClassification-6VMVochwUWo",
    "displayName": "Classification",
    "hidden": false,
    "copyInstanceOnItemCopy": true,
    "fields": [
      {
        "id": "822227e0-47a5-921b-88a8-494760b2e6d2",
        "type": "enum",
        "key": "Box__Security__Classification__Key",
        "displayName": "Classification",
        "hidden": false,
        "options": [
          {
            "id": "46aea176-3483-4431-856c-6b5b13d1cc50",
            "key": "Sensitive",
            "staticConfig": {
              "classification": {
                "classificationDefinition": "Sensitive information",
                "colorID": 4
              }
            }
          }
        ]
      }
    ]
  }
  ```
</Accordion>


# Delete AI agent
Source: https://developer.box.com/reference/delete-ai-agents-id

box-openapi.json DELETE /ai_agents/{agent_id}
Deletes an AI agent using the provided parameters.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove classification from file
Source: https://developer.box.com/reference/delete-files-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json DELETE /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Removes any classifications from a file.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get AI agent default configuration
Source: https://developer.box.com/reference/get-ai-agent-default

box-openapi.json GET /ai_agent_default
Get the AI agent default config.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List AI agents
Source: https://developer.box.com/reference/get-ai-agents

box-openapi.json GET /ai_agents
Lists AI agents based on the provided parameters.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get AI agent by agent ID
Source: https://developer.box.com/reference/get-ai-agents-id

box-openapi.json GET /ai_agents/{agent_id}
Gets an AI Agent using the `agent_id` parameter.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Authorize user
Source: https://developer.box.com/reference/get-authorize

box-openapi.json GET /authorize
Authorize a user by sending them through the [Box](https://box.com) website and request their permission to act on their behalf.

This is the first step when authenticating a user using OAuth 2.0. To request a user's authorization to use the Box APIs on their behalf you will need to send a user to the URL with this format.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List file app item associations
Source: https://developer.box.com/reference/get-files-id-app-item-associations

box-openapi.json GET /files/{file_id}/app_item_associations
**This is a beta feature, which means that its availability might be limited.** Returns all app items the file is associated with. This includes app items associated with ancestors of the file. Assuming the context user has access to the file, the type/ids are revealed even if the context user does not have **View** permission on the app item.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get classification on file
Source: https://developer.box.com/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json GET /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Retrieves the classification metadata instance that has been applied to a file.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List folder app item associations
Source: https://developer.box.com/reference/get-folders-id-app-item-associations

box-openapi.json GET /folders/{folder_id}/app_item_associations
**This is a beta feature, which means that its availability might be limited.** Returns all app items the folder is associated with. This includes app items associated with ancestors of the folder. Assuming the context user has access to the folder, the type/ids are revealed even if the context user does not have **View** permission on the app item.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get classification on folder
Source: https://developer.box.com/reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json GET /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Retrieves the classification metadata instance that has been applied to a folder.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all classifications
Source: https://developer.box.com/reference/get-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema

box-openapi.json GET /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema
Retrieves the classification metadata template and lists all the classifications available to this enterprise.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List Box Sign requests
Source: https://developer.box.com/reference/get-sign-requests

box-openapi.json GET /sign_requests
Gets signature requests created by a user. If the `sign_files` and/or `parent_folder` are deleted, the signature request will not return in the list.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Sign request by ID
Source: https://developer.box.com/reference/get-sign-requests-id

box-openapi.json GET /sign_requests/{sign_request_id}
Gets a sign request by ID.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List Box Sign templates
Source: https://developer.box.com/reference/get-sign-templates

box-openapi.json GET /sign_templates
Gets Box Sign templates created by a user.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Sign template by ID
Source: https://developer.box.com/reference/get-sign-templates-id

box-openapi.json GET /sign_templates/{template_id}
Fetches details of a specific Box Sign template.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# API Reference
Source: https://developer.box.com/reference/index



<Note>
  **Versioning.** This reference covers every Box API resource. Resources and
  endpoints added in a recent release are marked <Badge>New</Badge>.
  When an endpoint has multiple versions, the latest is the recommended default.
  Request an earlier one with the `box-version` header. See the
  [API versioning strategy](/guides/api-calls/api-versioning-strategy) for details.
</Note>

## Get started

In the vast majority of cases, API requests use the base URL `https://api.box.com/2.0` and require an OAuth 2.0 access token.

New to the platform? [Create a free developer account](https://account.box.com/signup/n/developer), then [generate a developer token](/guides/authentication/tokens/developer-tokens) to start making calls in minutes.

### Try your first request

Replace `<ACCESS_TOKEN>` with a [developer token](/guides/authentication/tokens/developer-tokens) and run:

```bash theme={null}
curl https://api.box.com/2.0/users/me \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

A successful response returns the user profile or app service account who the token belongs to. This confirms your credentials and connection are working.

### Common tasks

<CardGroup>
  <Card title="Authenticate" href="/guides/authentication" icon="key">
    Choose an auth method and obtain access tokens
  </Card>

  <Card title="Upload a file" href="/guides/uploads" icon="cloud-arrow-up">
    Send content to Box with direct or chunked uploads
  </Card>

  <Card title="Download a file" href="/guides/downloads" icon="download">
    Retrieve file content and representations
  </Card>

  <Card title="Create a shared link" href="/guides/shared-links" icon="share-nodes">
    Share files and folders with a URL
  </Card>

  <Card title="Search content" href="/guides/search" icon="magnifying-glass">
    Find files and folders across an account
  </Card>

  <Card title="Invite a collaborator" href="/guides/collaborations" icon="handshake">
    Grant users and groups access to content
  </Card>
</CardGroup>

## Browse by category

<AccordionGroup>
  <Accordion title="Content management" icon="folder-open">
    Core file and folder operations, uploads, downloads, and trash.

    <CardGroup>
      <Card title="Files" href="/reference/files-resources#file" icon="file">
        Core file operations and management
      </Card>

      <Card title="Folders" href="/reference/folders-resources#folder" icon="folder">
        Core folder operations and management
      </Card>

      <Card title="File versions" href="/reference/files-resources#file-versions" icon="file">
        Access and manage file version history
      </Card>

      <Card title="File requests" href="/reference/files-resources#file-request" icon="file">
        Create and manage file upload requests
      </Card>

      <Card title="Uploads" href="/reference/uploads-resources#upload-url" icon="cloud-arrow-up">
        Upload files to Box
      </Card>

      <Card title="Uploads (Chunked)" href="/reference/chunked-uploads-resources#upload-session" icon="cloud-arrow-up">
        Upload large files in chunks
      </Card>

      <Card title="Downloads" href="/reference/get-files-id-content" icon="download">
        Download file content
      </Card>

      <Card title="Zip Downloads" href="/reference/zip-downloads-resources#zip-download" icon="download">
        Download multiple items as zip archives
      </Card>

      <Card title="Folder Locks" href="/reference/folders-resources#folder-lock" icon="folder">
        Lock folders to prevent modifications
      </Card>

      <Card title="Collections" href="/reference/collections-resources#collection" icon="folder-open">
        Organize content into collections
      </Card>

      <Card title="Recent items" href="/reference/recent-items-resources#recent-item" icon="book">
        Access recently accessed items
      </Card>

      <Card title="Transfer folders" href="/reference/put-users-id-folders-0" icon="folder">
        Transfer folder ownership between users
      </Card>

      <Card title="Web links" href="/reference/web-links-resources#web-link" icon="globe">
        Create and manage bookmarks
      </Card>

      <Card title="App item associations" href="/reference/app-item-associations-resources#app-item-association" icon="book">
        Associate app items with files and folders
      </Card>

      <Card title="Trashed files" href="/reference/trashed-files-resources#trashed-file" icon="file">
        Manage files in trash
      </Card>

      <Card title="Trashed folders" href="/reference/trashed-folders-resources#trashed-folder" icon="folder">
        Manage folders in trash
      </Card>

      <Card title="Trashed items" href="/reference/get-folders-trash-items" icon="trash">
        List all items in trash
      </Card>

      <Card title="Trashed web links" href="/reference/trashed-web-links-resources#trashed-web-link" icon="trash">
        Manage web links in trash
      </Card>
    </CardGroup>

    <CardGroup>
      <Card title="Archives" href="/reference/v2025.0/archives-resources#archive" icon="box-archive">
        Create and manage Box Archive resources
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Authentication & users" icon="key">
    Authorization, user accounts, groups, and session management.

    <CardGroup>
      <Card title="Authorization" href="/reference/authorization-resources#access-token" icon="fingerprint">
        OAuth 2.0 authorization and token management
      </Card>

      <Card title="Users" href="/reference/users-resources#user" icon="person">
        Create and manage users
      </Card>

      <Card title="User avatars" href="/reference/users-resources#user-avatar" icon="person">
        Manage user profile images
      </Card>

      <Card title="Groups" href="/reference/groups-resources#group" icon="users">
        Create and manage user groups
      </Card>

      <Card title="Group memberships" href="/reference/groups-resources#group-membership" icon="users">
        Manage user membership in groups
      </Card>

      <Card title="Invites" href="/reference/invites-resources#invite" icon="user-plus">
        Invite users to join Box
      </Card>

      <Card title="Email aliases" href="/reference/email-aliases-resources#email-alias" icon="at">
        Manage user email aliases
      </Card>

      <Card title="Session termination" href="/reference/session-termination-resources#session-termination-message" icon="clock">
        Terminate user or group sessions
      </Card>

      <Card title="Device pinners" href="/reference/device-pinners-resources#device-pinner" icon="mobile">
        Manage device pinning for offline access
      </Card>
    </CardGroup>

    <CardGroup>
      <Card title="External Users" href="/reference/v2025.0/external-users-resources#external-users-submit-delete-job-response" icon="person">
        Manage external user access
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Sharing & collaboration" icon="handshake">
    Collaborations, shared links, comments, and tasks.

    <CardGroup>
      <Card title="Collaborations" href="/reference/user-collaborations-resources#collaboration" icon="handshake">
        Create and manage file/folder collaborations
      </Card>

      <Card title="Collaborations (List)" href="/reference/get-files-id-collaborations" icon="handshake">
        List collaborations for users, files, folders, and groups
      </Card>

      <Card title="Shared links (Files)" href="/reference/put-files-id--add-shared-link" icon="file">
        Create and manage shared links for files
      </Card>

      <Card title="Shared links (Folders)" href="/reference/put-folders-id--add-shared-link" icon="folder">
        Create and manage shared links for folders
      </Card>

      <Card title="Shared links (Web Links)" href="/reference/put-web-links-id--add-shared-link" icon="share-nodes">
        Access web links via shared links
      </Card>

      <Card title="Shared links (App Items)" href="/reference/get-shared-items--app-items" icon="share-nodes">
        Access app items via shared links
      </Card>

      <Card title="Comments" href="/reference/comments-resources#comment" icon="message">
        Add and manage comments on files
      </Card>

      <Card title="Tasks" href="/reference/tasks-resources#task" icon="list-check">
        Create and manage file-based tasks
      </Card>

      <Card title="Task assignments" href="/reference/tasks-resources#task-assignment" icon="list-check">
        Assign tasks to users
      </Card>

      <Card title="Domain restrictions for collaborations" href="/reference/user-collaborations-resources#collaboration-allowlist-entry" icon="globe">
        Restrict collaborations to specific domains
      </Card>

      <Card title="Domain restrictions (User exemptions)" href="/reference/user-collaborations-resources#collaboration-allowlist-exempt-target" icon="user-check">
        Exempt users from domain restrictions
      </Card>

      <Card title="Box Hubs" href="/reference/v2025.0/hubs-resources#box-hub" icon="share-nodes">
        Create and manage Box Hubs
      </Card>

      <Card title="Box Hub Items" href="/reference/v2025.0/hubs-resources#box-hub-item" icon="share-nodes">
        Manage items within Box Hubs
      </Card>

      <Card title="Box Hub Collaborations" href="/reference/v2025.0/hubs-resources#box-hub-collaboration" icon="share-nodes">
        Manage collaborations for Box Hubs
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Search & metadata" icon="magnifying-glass">
    <CardGroup>
      <Card title="Box query insights" href="/reference/v2026.0/query-resources#query-insights" icon="chart-line">
        Create insights for Box items
      </Card>

      <Card title="Box query resources" href="/reference/v2026.0/query-resources#query-results" icon="file-lines">
        Query for Box items
      </Card>
    </CardGroup>

    Search across content and manage metadata templates, instances, taxonomies, and classifications.

    <CardGroup>
      <Card title="Search" href="/reference/search-resources#search-results" icon="magnifying-glass">
        Search for files and folders
      </Card>

      <Card title="Metadata instances (Files)" href="/reference/file-metadata-resources#metadata-instance" icon="file">
        Manage metadata on files
      </Card>

      <Card title="Metadata instances (Folders)" href="/reference/get-folders-id-metadata-id-id" icon="folder">
        Manage metadata on folders
      </Card>

      <Card title="Metadata templates" href="/reference/file-metadata-resources#metadata-instance-template" icon="tag">
        Define custom metadata schemas
      </Card>

      <Card title="Metadata cascade policies" href="/reference/file-metadata-resources#metadata-instance-cascade-policy" icon="tag">
        Auto-apply metadata to folder contents
      </Card>

      <Card title="Metadata taxonomies" href="/reference/file-metadata-resources#metadata-instance-taxonomy" icon="sitemap">
        Organize metadata into hierarchical taxonomies
      </Card>

      <Card title="Classifications" href="/reference/classifications-resources#classification" icon="tag">
        Define and manage security classifications
      </Card>

      <Card title="Classifications on files" href="/reference/get-files-id-metadata-enterprise-securityClassification-6VMVochwUWo" icon="tag">
        Apply classifications to files
      </Card>

      <Card title="Classifications on folders" href="/reference/get-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo" icon="tag">
        Apply classifications to folders
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Events & webhooks" icon="bell">
    Monitor activity and receive real-time notifications.

    <CardGroup>
      <Card title="Events" href="/reference/events-resources#event" icon="bell">
        Monitor Box events and activity
      </Card>

      <Card title="Webhooks" href="/reference/webhooks-resources#webhook" icon="webhook">
        Configure real-time event notifications
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="AI & intelligence" icon="robot">
    Box AI, custom AI agents, and metadata skills.

    <CardGroup>
      <Card title="Box AI" href="/reference/ai-resources#ai-response" icon="sparkles">
        AI-powered features for asking questions and extracting data
      </Card>

      <Card title="Box AI Studio" href="/reference/ai-studio-resources#ai-agent-capability-ask-request" icon="sparkles">
        Build and manage custom AI agents
      </Card>

      <Card title="Box Skills" href="/reference/skills-resources#skills-metadata-instance" icon="brain">
        Apply AI-powered skills to files
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Automation & document workflows" icon="gears">
    Workflows and e-signatures.

    <CardGroup>
      <Card title="Workflows" href="/reference/workflows-resources#workflow" icon="zap">
        Trigger and manage Box Relay workflows
      </Card>

      <Card title="Box Sign requests" href="/reference/sign-requests-resources#box-sign-request" icon="pen-fancy">
        Create and manage e-signature requests
      </Card>

      <Card title="Box Sign templates" href="/reference/sign-templates-resources#box-sign-template" icon="pen-fancy">
        Manage reusable e-signature templates
      </Card>
    </CardGroup>

    <CardGroup>
      <Card title="Automate Workflows" href="/reference/v2026.0/resources/automate-workflows" icon="zap">
        <Badge>New</Badge> <Badge>Beta</Badge> List and manually start Automate workflow actions
      </Card>

      <Card title="Convert to Box note" href="/reference/v2026.0/notes-resources#notes-convert-response" icon="cloud">
        <Badge>New</Badge> Convert content to a Box Note
      </Card>

      <Card title="Box Doc Gen" href="/reference/v2025.0/docgen-resources" icon="file-lines">
        Generate documents programmatically from templates
      </Card>

      <Card title="Box Doc Gen templates" href="/reference/v2025.0/docgen-template-resources#box-doc-gen-template-tag" icon="file-lines">
        Manage document generation templates
      </Card>
    </CardGroup>
  </Accordion>

  <Accordion title="Administration & compliance" icon="shield">
    Enterprise integrations, governance, retention, and Box Shield.

    <CardGroup>
      <Card title="Integration mappings" href="/reference/integration-mappings-resources#integration-mapping-slack" icon="link">
        Map Box users to external integrations
      </Card>

      <Card title="Legal hold policies" href="/reference/legal-hold-policies-resources#legal-hold-policy" icon="scale-balanced">
        Define and manage legal hold policies
      </Card>

      <Card title="Legal hold policy assignments" href="/reference/legal-hold-policies-resources#legal-hold-policy-assignment" icon="scale-balanced">
        Apply legal hold policies to content
      </Card>

      <Card title="File version legal holds" href="/reference/file-version-legal-holds-resources#file-version-legal-hold" icon="file">
        Apply legal holds to specific file versions
      </Card>

      <Card title="Retention policies" href="/reference/retention-policies-resources#retention-policy" icon="hourglass-end">
        Define content retention policies
      </Card>

      <Card title="Retention policy assignments" href="/reference/retention-policies-resources#retention-policy-assignment" icon="hourglass-end">
        Apply retention policies to content
      </Card>

      <Card title="File version retentions" href="/reference/file-version-retentions-resources#file-version-retention" icon="file">
        Manage retention policies for file versions
      </Card>

      <Card title="Terms of service" href="/reference/terms-of-services-resources#terms-of-service" icon="file-contract">
        Define enterprise terms of service
      </Card>

      <Card title="Terms of service user statuses" href="/reference/terms-of-services-resources#terms-of-service-user-status" icon="file-contract">
        Track user acceptance of terms
      </Card>

      <Card title="Watermarks (Files)" href="/reference/file-watermarks-resources#watermark" icon="file">
        Apply watermarks to files
      </Card>

      <Card title="Watermarks (Folders)" href="/reference/put-folders-id-watermark" icon="folder">
        Apply watermarks to folders
      </Card>

      <Card title="Standard and Zones Storage Policies" href="/reference/storage-policies-resources#storage-policy" icon="hard-drive">
        Manage storage location policies
      </Card>

      <Card title="Standard and Zones Storage Policy Assignments" href="/reference/storage-policies-resources#storage-policy-assignment" icon="hard-drive">
        Assign storage policies to users
      </Card>

      <Card title="Shield information barriers" href="/reference/shield-information-barriers-resources#shield-information-barrier" icon="shield">
        Implement information barriers for compliance
      </Card>

      <Card title="Shield information barrier segments" href="/reference/shield-information-barriers-resources#shield-information-barrier-segment" icon="shield">
        Create and manage barrier segments
      </Card>

      <Card title="Shield information barrier segment members" href="/reference/shield-information-barriers-resources#shield-information-barrier-segment-member" icon="shield">
        Manage users in barrier segments
      </Card>

      <Card title="Shield information barrier segment restrictions" href="/reference/shield-information-barriers-resources#shield-information-barrier-segment-restriction" icon="shield">
        Define restrictions between segments
      </Card>

      <Card title="Shield information barrier reports" href="/reference/shield-information-barriers-resources#shield-information-barrier-report" icon="shield">
        Generate reports on information barriers
      </Card>
    </CardGroup>

    <CardGroup>
      <Card title="Enterprise Configurations" href="/reference/v2025.0/enterprise-configurations-resources#enterprise-configuration-content-and-sharing" icon="building">
        Configure enterprise-wide settings
      </Card>

      <Card title="Shield lists" href="/reference/v2025.0/shield-lists-resources#shield-list-content-country" icon="shield">
        Manage access control lists
      </Card>
    </CardGroup>
  </Accordion>
</AccordionGroup>


# Create AI agent
Source: https://developer.box.com/reference/post-ai-agents

box-openapi.json POST /ai_agents
Creates an AI agent. At least one of the following capabilities must be provided: `ask`, `text_gen`, `extract`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Ask question
Source: https://developer.box.com/reference/post-ai-ask

box-openapi.json POST /ai/ask
Sends an AI request to supported LLMs and returns an answer specifically focused on the user's question given the provided context.

You can ask a question about a single file, several files, or the entire contents of a Box Hub. To search across and ask questions about everything in a Box Hub, send a single item with `type` set to `hubs` and the Hub's ID as the `id`. Box AI answers the question using the indexed content of all files in that Hub.

Asking questions about a Box Hub requires Box AI for Hubs to be enabled in the Admin Console before the Hub is created, so that its content is indexed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Extract metadata (freeform)
Source: https://developer.box.com/reference/post-ai-extract

box-openapi.json POST /ai/extract
Sends an AI request to supported Large Language Models (LLMs) and extracts metadata in form of key-value pairs. In this request, both the prompt and the output can be freeform. Metadata template setup before sending the request is not required.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Extract metadata (structured)
Source: https://developer.box.com/reference/post-ai-extract-structured

box-openapi.json POST /ai/extract_structured
Sends an AI request to supported Large Language Models (LLMs) and returns extracted metadata as a set of key-value pairs.

To define the extraction structure, provide either a metadata template or a list of fields. To learn more about creating templates, see [Creating metadata templates in the Admin Console](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or use the [metadata template API](/guides/metadata/templates/create).

This endpoint also supports [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent).

For information about supported file formats and languages, see the [Extract metadata from file (structured)](/guides/box-ai/ai-tutorials/extract-metadata-structured) API guide.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Generate text
Source: https://developer.box.com/reference/post-ai-text-gen

box-openapi.json POST /ai/text_gen
Sends an AI request to supported Large Language Models (LLMs) and returns generated text based on the provided prompt.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add classification to file
Source: https://developer.box.com/reference/post-files-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json POST /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Adds a classification to a file by specifying the label of the classification to add.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/files/:id//enterprise_12345/securityClassification-6VMVochwUWo`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add initial classifications
Source: https://developer.box.com/reference/post-metadata-templates-schema--classifications

box-openapi.json POST /metadata_templates/schema#classifications
When an enterprise does not yet have any classifications, this API call initializes the classification template with an initial set of classifications.

If an enterprise already has a classification, the template will already exist and instead an API call should be made to add additional classifications.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Revoke access token
Source: https://developer.box.com/reference/post-oauth2-revoke

box-openapi.json POST /oauth2/revoke
Revoke an active Access Token, effectively logging a user out that has been previously authenticated.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Request access token
Source: https://developer.box.com/reference/post-oauth2-token

box-openapi.json POST /oauth2/token
Request an Access Token using either a client-side obtained OAuth 2.0 authorization code or a server-side JWT assertion.

An Access Token is a string that enables Box to verify that a request belongs to an authorized session. In the normal order of operations you will begin by requesting authentication from the [authorize](/reference/get-authorize) endpoint and Box will send you an authorization code.

You will then send this code to this endpoint to exchange it for an Access Token. The returned Access Token can then be used to to make Box API calls.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Refresh access token
Source: https://developer.box.com/reference/post-oauth2-token--refresh

box-openapi.json POST /oauth2/token#refresh
Refresh an Access Token using its client ID, secret, and refresh token.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create Box Sign request
Source: https://developer.box.com/reference/post-sign-requests

box-openapi.json POST /sign_requests
Creates a signature request. This involves preparing a document for signing and sending the signature request to signers.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Cancel Box Sign request
Source: https://developer.box.com/reference/post-sign-requests-id-cancel

box-openapi.json POST /sign_requests/{sign_request_id}/cancel
Cancels a sign request.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Resend Box Sign request
Source: https://developer.box.com/reference/post-sign-requests-id-resend

box-openapi.json POST /sign_requests/{sign_request_id}/resend
Resends a signature request email to all outstanding signers.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update AI agent
Source: https://developer.box.com/reference/put-ai-agents-id

box-openapi.json PUT /ai_agents/{agent_id}
Updates an AI agent.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update classification on file
Source: https://developer.box.com/reference/put-files-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json PUT /files/{file_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Updates a classification on a file.

The classification can only be updated if a classification has already been applied to the file before. When editing classifications, only values are defined for the enterprise will be accepted.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add classification
Source: https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--add

box-openapi.json PUT /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#add
Adds one or more new classifications to the list of classifications available to the enterprise.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update classification
Source: https://developer.box.com/reference/put-metadata-templates-enterprise-securityClassification-6VMVochwUWo-schema--update

box-openapi.json PUT /metadata_templates/enterprise/securityClassification-6VMVochwUWo/schema#update
Updates the labels and descriptions of one or more classifications available to the enterprise.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/metadata_templates/enterprise_12345/securityClassification-6VMVochwUWo/schema`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Box Sign requests resources
Source: https://developer.box.com/reference/sign-requests-resources



Box Sign requests are used to submit a file for signature.

## Box Sign request

A Box Sign request object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `is_document_preparation_needed` | `boolean` | No | Indicates if the sender should receive a `prepare_url` in the response to complete document preparation using the UI. |
  | `redirect_url` | `string` | No | When specified, the signature request will be redirected to this url when a document is signed. Can be `null`. |
  | `declined_redirect_url` | `string` | No | The uri that a signer will be redirected to after declining to sign a document. Can be `null`. |
  | `are_text_signatures_enabled` | `boolean` | No | Disables the usage of signatures generated by typing (text). |
  | `email_subject` | `string` | No | Subject of sign request email. This is cleaned by sign request. If this field is not passed, a default subject will be used. Can be `null`. |
  | `email_message` | `string` | No | Message to include in sign request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used. Can be `null`. |
  | `are_reminders_enabled` | `boolean` | No | Reminds signers to sign a document on day 3, 8, 13 and 18. Reminders are only sent to outstanding signers. |
  | `name` | `string` | No | Name of the signature request. |
  | `prefill_tags` | array of `Sign request prefill tag` | No | When a document contains sign-related tags in the content, you can prefill them using this `prefill_tags` by referencing the 'id' of the tag as the `external_id` field of the prefill tag. |
  | `days_valid` | `integer` | No | Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire. Can be `null`. |
  | `external_id` | `string` | No | This can be used to reference an ID in an external system that the sign request is related to. Can be `null`. |
  | `template_id` | `string` | No | When a signature request is created from a template this field will indicate the id of that template. Can be `null`. |
  | `external_system_name` | `string` | No | Used as an optional system name to appear in the signature log next to the signers who have been assigned the `embed_url_external_id`. Can be `null`. |
  | `request_flow` | `string` | No | The flow type of the sign request. Values can include `standard` or `cfr11`. When not specified during creation, a default is chosen based on admin settings. Can be `null`. |
  | `type` | `enum<string>` | No | The value will always be `sign-request`. Available options: `sign-request`. |
  | `source_files` | array of [File (Base)](/reference/files-resources#file-base) | No | List of files to create a signing document from. This is currently limited to ten files. Only the ID and type fields are required for each file. |
  | `signers` | array of `Signer fields for Box Sign request response` | No | Array of signers for the signature request. |
  | `signature_color` | `string` | No | Force a specific color for the signature (blue, black, or red). Can be `null`. |
  | `id` | `string` | No | Box Sign request ID. |
  | `prepare_url` | `string` | No | This URL is returned if `is_document_preparation_needed` is set to `true` in the request. The parameter is used to prepare the signature request using the UI. The signature request is not sent until the preparation phase is complete. Can be `null`. |
  | `signing_log` | [File (Mini)](/reference/files-resources#file-mini) | No | Reference to a file that holds a log of all signer activity for the request. |
  | `status` | `enum<string>` | No | Describes the status of the signature request. Available options: `converting`, `created`, `sent`, `viewed`, `signed`, `cancelled`, `declined`, `error`, `error_converting`, `error_sending`, `expired`, `finalizing`, `error_finalizing`. |
  | `sign_files` | `object` | No | List of files that will be signed, which are copies of the original source files. A new version of these files are created as signers sign and can be downloaded at any point in the signing process. |
  | `auto_expire_at` | `string` | No | Uses `days_valid` to calculate the date and time, in GMT, the sign request will expire if unsigned. Can be `null`. |
  | `parent_folder` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The destination folder to place final, signed document and signing log. When this value was not passed in when the signature request was created, then we will use a default folder which is either the parent folder of the first source file in the payload if we have the permission to upload to that folder or a folder called "My Sign Requests". |
  | `collaborator_level` | `string` | No | The collaborator level of the user to the sign request. Values can include "owner", "editor", and "viewer". Can be `null`. |
  | `short_id` | `string` | No | Short identifier for the sign request. |
  | `created_at` | `string` | No | Timestamp marking when the sign request was created. |
  | `finished_at` | `string` | No | Timestamp indicating when all signing actions completed. Can be `null`. |
  | `error_code` | `string` | No | When the sign request is in an error state, identifies the specific reason. Null when no error code applies. Read-only. Can be `null`. |
  | `sender_email` | `string` | No | The email address of the sender of the sign request. Can be `null`. |
  | `sender_id` | `integer` | No | The user ID of the sender of the sign request. Can be `null`. |

  ```json Example theme={null}
  {
    "is_document_preparation_needed": true,
    "redirect_url": "https://www.example.com",
    "declined_redirect_url": "https://declined-redirect.com",
    "are_text_signatures_enabled": true,
    "email_subject": "Sign Request from Acme",
    "email_message": "Hello! Please sign the document below",
    "are_reminders_enabled": true,
    "name": "name",
    "prefill_tags": [
      {
        "document_tag_id": "1234",
        "text_value": "text",
        "checkbox_value": true,
        "date_value": "2021-04-26"
      }
    ],
    "days_valid": 2,
    "external_id": "123",
    "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb",
    "external_system_name": "Box",
    "request_flow": "standard",
    "type": "sign-request",
    "source_files": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file"
      }
    ],
    "signers": [
      {
        "email": "example@gmail.com",
        "role": "signer",
        "is_in_person": true,
        "order": 2,
        "embed_url_external_user_id": "1234",
        "redirect_url": "https://example.com",
        "declined_redirect_url": "https://declined-example.com",
        "login_required": true,
        "verification_phone_number": "6314578901",
        "password": "SecretPassword123",
        "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
        "suppress_notifications": false,
        "language": "en",
        "has_viewed_document": true,
        "signer_decision": {
          "type": "signed",
          "finalized_at": "2021-04-26T08:12:13.982Z",
          "additional_info": "Requesting changes before signing."
        },
        "inputs": [
          {
            "document_tag_id": "1234",
            "text_value": "text",
            "checkbox_value": true,
            "date_value": "2021-04-26",
            "type": "text",
            "content_type": "signature",
            "page_index": 4,
            "read_only": true,
            "validation": {
              "validation_type": "email"
            },
            "reason": "I read and approve this document",
            "is_validated": true
          }
        ],
        "embed_url": "https://example.com",
        "iframeable_embed_url": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4",
        "attachments": [
          {
            "id": "12345",
            "name": "proof_of_identity.pdf"
          }
        ]
      }
    ],
    "signature_color": "blue",
    "id": "12345",
    "prepare_url": "https://prepareurl.com",
    "signing_log": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    },
    "status": "converting",
    "sign_files": {
      "files": [
        {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        }
      ],
      "is_ready_for_download": true
    },
    "auto_expire_at": "2021-04-26T08:12:13.982Z",
    "parent_folder": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "collaborator_level": "owner",
    "short_id": "SR-12345",
    "created_at": "2025-02-01T12:00:00Z",
    "finished_at": "2025-02-02T12:00:00Z",
    "error_code": "cfr11_validation_failed",
    "sender_email": "sender@box.com",
    "sender_id": 12345
  }
  ```
</Accordion>

## Box Sign requests

A standard representation of a signature request, as returned from any Box Sign API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `entries` | array of [Box Sign request](#box-sign-request) | No | A list of Box Sign requests. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "entries": [
      {
        "is_document_preparation_needed": true,
        "redirect_url": "https://www.example.com",
        "declined_redirect_url": "https://declined-redirect.com",
        "are_text_signatures_enabled": true,
        "email_subject": "Sign Request from Acme",
        "email_message": "Hello! Please sign the document below",
        "are_reminders_enabled": true,
        "name": "name",
        "prefill_tags": [
          {
            "document_tag_id": "1234",
            "text_value": "text",
            "checkbox_value": true,
            "date_value": "2021-04-26"
          }
        ],
        "days_valid": 2,
        "external_id": "123",
        "template_id": "123075213-af2c8822-3ef2-4952-8557-52d69c2fe9cb",
        "external_system_name": "Box",
        "request_flow": "standard",
        "type": "sign-request",
        "source_files": [
          {
            "id": "12345",
            "etag": "1",
            "type": "file"
          }
        ],
        "signers": [
          {
            "email": "example@gmail.com",
            "role": "signer",
            "is_in_person": true,
            "order": 2,
            "embed_url_external_user_id": "1234",
            "redirect_url": "https://example.com",
            "declined_redirect_url": "https://declined-example.com",
            "login_required": true,
            "verification_phone_number": "6314578901",
            "password": "SecretPassword123",
            "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
            "suppress_notifications": false,
            "language": "en",
            "has_viewed_document": true,
            "signer_decision": {
              "type": "signed",
              "finalized_at": "2021-04-26T08:12:13.982Z",
              "additional_info": "Requesting changes before signing."
            },
            "inputs": [
              {
                "document_tag_id": "1234",
                "text_value": "text",
                "checkbox_value": true,
                "date_value": "2021-04-26",
                "type": "text",
                "content_type": "signature",
                "page_index": 4,
                "read_only": true,
                "validation": {
                  "validation_type": "email"
                },
                "reason": "I read and approve this document",
                "is_validated": true
              }
            ],
            "embed_url": "https://example.com",
            "iframeable_embed_url": "https://app.box.com/embed/sign/document/gfhr4222-a331-494b-808b-79bc7f3992a3/f14d7098-a331-494b-808b-79bc7f3992a4",
            "attachments": [
              {
                "id": "12345",
                "name": "proof_of_identity.pdf"
              }
            ]
          }
        ],
        "signature_color": "blue",
        "id": "12345",
        "prepare_url": "https://prepareurl.com",
        "signing_log": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "status": "converting",
        "sign_files": {
          "files": [
            {
              "id": "12345",
              "etag": "1",
              "type": "file",
              "sequence_id": "3",
              "name": "Contract.pdf",
              "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
              "file_version": {
                "id": "12345",
                "type": "file_version",
                "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
              }
            }
          ],
          "is_ready_for_download": true
        },
        "auto_expire_at": "2021-04-26T08:12:13.982Z",
        "parent_folder": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "collaborator_level": "owner",
        "short_id": "SR-12345",
        "created_at": "2025-02-01T12:00:00Z",
        "finished_at": "2025-02-02T12:00:00Z",
        "error_code": "cfr11_validation_failed",
        "sender_email": "sender@box.com",
        "sender_id": 12345
      }
    ]
  }
  ```
</Accordion>


# Box Sign templates resources
Source: https://developer.box.com/reference/sign-templates-resources



Sign templates allow you to use a predefined Box Sign template when creating a signature request. The template includes placeholders that are automatically populated with data when creating the request.

## Box Sign template

A Box Sign template object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | No | The value will always be `sign-template`. Available options: `sign-template`. |
  | `id` | `string` | No | Template identifier. |
  | `name` | `string` | No | The name of the template. Can be `null`. |
  | `email_subject` | `string` | No | Subject of signature request email. This is cleaned by sign request. If this field is not passed, a default subject will be used. Can be `null`. |
  | `email_message` | `string` | No | Message to include in signature request email. The field is cleaned through sanitization of specific characters. However, some html tags are allowed. Links included in the message are also converted to hyperlinks in the email. The message may contain the following html tags including `a`, `abbr`, `acronym`, `b`, `blockquote`, `code`, `em`, `i`, `ul`, `li`, `ol`, and `strong`. Be aware that when the text to html ratio is too high, the email may end up in spam filters. Custom styles on these tags are not allowed. If this field is not passed, a default message will be used. Can be `null`. |
  | `days_valid` | `integer` | No | Set the number of days after which the created signature request will automatically expire if not completed. By default, we do not apply any expiration date on signature requests, and the signature request does not expire. Can be `null`. |
  | `parent_folder` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The destination folder to place final, signed document and signing log. Only `ID` and `type` fields are required. The root folder, folder ID `0`, cannot be used. |
  | `source_files` | array of [File (Mini)](/reference/files-resources#file-mini) | No | List of files to create a signing document from. Only the ID and type fields are required for each file. |
  | `are_fields_locked` | `boolean` | No | Indicates if the template input fields are editable or not. |
  | `are_options_locked` | `boolean` | No | Indicates if the template document options are editable or not, for example renaming the document. |
  | `are_recipients_locked` | `boolean` | No | Indicates if the template signers are editable or not. |
  | `are_email_settings_locked` | `boolean` | No | Indicates if the template email settings are editable or not. |
  | `are_files_locked` | `boolean` | No | Indicates if the template files are editable or not. This includes deleting or renaming template files. |
  | `signers` | array of `Signer fields for Templates` | No | Array of signers for the template. **Note**: It may happen that some signers specified in the template belong to conflicting [segments](/reference/shield-information-barrier-segment-members-resources#shield-information-barrier-segment-member) (user groups). This means that due to the security policies, users are assigned to segments to prevent exchanges or communication that could lead to ethical conflicts. In such a case, an attempt to send a sign request based on a template that lists signers in conflicting segments will result in an error. Read more about [segments and ethical walls](https://support.box.com/hc/en-us/articles/9920431507603-Understanding-Information-Barriers#h_01GFVJEHQA06N7XEZ4GCZ9GFAQ). |
  | `additional_info` | `object` | No | Additional information on which fields are required and which fields are not editable. |
  | `ready_sign_link` | `object` | No | Box's ready-sign link feature enables you to create a link to a signature request that you've created from a template. Use this link when you want to post a signature request on a public form — such as an email, social media post, or web page — without knowing who the signers will be. Note: The ready-sign link feature is limited to Enterprise Plus customers and not available to Box Verified Enterprises. Can be `null`. |
  | `custom_branding` | `object` | No | Custom branding applied to notifications and signature requests. Can be `null`. |
  | `request_flow` | `string` | No | The sign flow of sign requests created from the template. Values can include `standard` or `cfr11`. Can be `null`. |

  ```json Example theme={null}
  {
    "type": "sign-template",
    "id": "4206996024-14944f75-c34b-478a-95a1-264b1ff80d35",
    "name": "Official contract",
    "email_subject": "Sign Request from Acme",
    "email_message": "Hello! Please sign the document below",
    "days_valid": 2,
    "parent_folder": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "source_files": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      }
    ],
    "are_fields_locked": false,
    "are_options_locked": true,
    "are_recipients_locked": false,
    "are_email_settings_locked": true,
    "are_files_locked": true,
    "signers": [
      {
        "inputs": [
          {
            "document_tag_id": "1234",
            "text_value": "text",
            "checkbox_value": true,
            "date_value": "2021-04-26",
            "type": "text",
            "content_type": "text",
            "is_required": true,
            "page_index": 4,
            "document_id": "123075213-eb54b537-8b25-445e-87c1-5a1c67d8cbd7",
            "dropdown_choices": [
              "Yes",
              "No",
              "Maybe"
            ],
            "group_id": "da317330-225a-4c72-89ad-0d6dcaaf4df6",
            "coordinates": {
              "x": 0.672258592471358,
              "y": 0.18654283173599448
            },
            "dimensions": {
              "width": 0.2618657937806874,
              "height": 0.05311728090109673
            },
            "label": "Legal name",
            "read_only": true,
            "validation": {
              "validation_type": "email"
            }
          }
        ],
        "email": "example@mail.com",
        "role": "signer",
        "is_in_person": true,
        "order": 2,
        "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
        "label": "Jane Doe",
        "public_id": "RJZYYVPR",
        "is_password_required": true,
        "is_phone_number_required": true,
        "login_required": true
      }
    ],
    "additional_info": {
      "non_editable": [
        "email_subject",
        "name"
      ],
      "required": {
        "signers": [
          [
            "email"
          ],
          [
            "email"
          ]
        ]
      }
    },
    "ready_sign_link": {
      "url": "\"https://app.box.com/sign/\nready-sign-link/a1cdf2c7-fa81-4a67-8163-1e5f4dbe5178\"",
      "name": "Official contract",
      "instructions": "Hello! Please sign the document below",
      "folder_id": "12345",
      "is_notification_disabled": true,
      "is_active": false
    },
    "custom_branding": {
      "company_name": "Corporation inc.",
      "logo_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA\nAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A\n8AAQUBAScY42YAAAAASUVORK5CYII=",
      "branding_color": "9E5E6F",
      "email_footer_text": "Contact email email@mail.com"
    },
    "request_flow": "standard"
  }
  ```
</Accordion>

## Box Sign templates

A list of templates, as returned from any Box Sign API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Sign template](#box-sign-template) | No | A list of templates. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "type": "sign-template",
        "id": "4206996024-14944f75-c34b-478a-95a1-264b1ff80d35",
        "name": "Official contract",
        "email_subject": "Sign Request from Acme",
        "email_message": "Hello! Please sign the document below",
        "days_valid": 2,
        "parent_folder": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "source_files": [
          {
            "id": "12345",
            "etag": "1",
            "type": "file",
            "sequence_id": "3",
            "name": "Contract.pdf",
            "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
            "file_version": {
              "id": "12345",
              "type": "file_version",
              "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
            }
          }
        ],
        "are_fields_locked": false,
        "are_options_locked": true,
        "are_recipients_locked": false,
        "are_email_settings_locked": true,
        "are_files_locked": true,
        "signers": [
          {
            "inputs": [
              {
                "document_tag_id": "1234",
                "text_value": "text",
                "checkbox_value": true,
                "date_value": "2021-04-26",
                "type": "text",
                "content_type": "text",
                "is_required": true,
                "page_index": 4,
                "document_id": "123075213-eb54b537-8b25-445e-87c1-5a1c67d8cbd7",
                "dropdown_choices": [
                  "Yes",
                  "No",
                  "Maybe"
                ],
                "group_id": "da317330-225a-4c72-89ad-0d6dcaaf4df6",
                "coordinates": {
                  "x": 0.672258592471358,
                  "y": 0.18654283173599448
                },
                "dimensions": {
                  "width": 0.2618657937806874,
                  "height": 0.05311728090109673
                },
                "label": "Legal name",
                "read_only": true,
                "validation": {
                  "validation_type": "email"
                }
              }
            ],
            "email": "example@mail.com",
            "role": "signer",
            "is_in_person": true,
            "order": 2,
            "signer_group_id": "cd4ff89-8fc1-42cf-8b29-1890dedd26d7",
            "label": "Jane Doe",
            "public_id": "RJZYYVPR",
            "is_password_required": true,
            "is_phone_number_required": true,
            "login_required": true
          }
        ],
        "additional_info": {
          "non_editable": [
            "email_subject",
            "name"
          ],
          "required": {
            "signers": [
              [
                "email"
              ],
              [
                "email"
              ]
            ]
          }
        },
        "ready_sign_link": {
          "url": "\"https://app.box.com/sign/\nready-sign-link/a1cdf2c7-fa81-4a67-8163-1e5f4dbe5178\"",
          "name": "Official contract",
          "instructions": "Hello! Please sign the document below",
          "folder_id": "12345",
          "is_notification_disabled": true,
          "is_active": false
        },
        "custom_branding": {
          "company_name": "Corporation inc.",
          "logo_uri": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA\nAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A\n8AAQUBAScY42YAAAAASUVORK5CYII=",
          "branding_color": "9E5E6F",
          "email_footer_text": "Contact email email@mail.com"
        },
        "request_flow": "standard"
      }
    ]
  }
  ```
</Accordion>


# Domain restrictions for collaborations resources
Source: https://developer.box.com/reference/collaboration-allowlist-entries-resources



A set of endpoints that manage domains for which users can collaborate with files and folders in an enterprise.

## Allowed collaboration domain

An entry that describes an approved domain for which users can collaborate with files and folders in your enterprise or vice versa.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this entry. |
  | `type` | `enum<string>` | No | The value will always be `collaboration_whitelist_entry`. Available options: `collaboration_whitelist_entry`. |
  | `domain` | `string` | No | The whitelisted domain. |
  | `direction` | `enum<string>` | No | The direction of the collaborations to allow. Available options: `inbound`, `outbound`, `both`. |
  | `enterprise` | `object` | No | A representation of a Box enterprise. |
  | `created_at` | `string` | No | The time the entry was created at. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "collaboration_whitelist_entry",
    "domain": "example.com",
    "direction": "both",
    "enterprise": {
      "id": "11446498",
      "type": "enterprise",
      "name": "Acme Inc."
    },
    "created_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Allowed collaboration domains

A list of allowed domains for collaboration.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Allowed collaboration domain](#allowed-collaboration-domain) | No | A list of allowed collaboration domains. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "collaboration_whitelist_entry",
        "domain": "example.com",
        "direction": "both",
        "enterprise": {
          "id": "11446498",
          "type": "enterprise",
          "name": "Acme Inc."
        },
        "created_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# Domain restrictions (User exemptions) resources
Source: https://developer.box.com/reference/collaboration-allowlist-exempt-targets-resources



A set of endpoints that allow exempting users from restrictions imposed by the list of allowed collaboration domains for a specific enterprise.

## Allowed collaboration domains user exemption

The user that is exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this exemption. |
  | `type` | `enum<string>` | No | The value will always be `collaboration_whitelist_exempt_target`. Available options: `collaboration_whitelist_exempt_target`. |
  | `enterprise` | `object` | No | A representation of a Box enterprise. |
  | `user` | [User (Mini)](/reference/users-resources#user-mini) | No | The user that has been exempt. |
  | `created_at` | `string` | No | The time the entry was created. |
  | `modified_at` | `string` | No | The time the entry was modified. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "collaboration_whitelist_exempt_target",
    "enterprise": {
      "id": "11446498",
      "type": "enterprise",
      "name": "Acme Inc."
    },
    "user": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Allowed collaboration domains user exemptions

A list of users exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Allowed collaboration domains user exemption](#allowed-collaboration-domains-user-exemption) | No | A list of users exempt from any of the restrictions imposed by the list of allowed collaboration domains for this enterprise. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "collaboration_whitelist_exempt_target",
        "enterprise": {
          "id": "11446498",
          "type": "enterprise",
          "name": "Acme Inc."
        },
        "user": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# Collections resources
Source: https://developer.box.com/reference/collections-resources



Collections are a way to group files, folders, and web links without putting them all into a folder.

## Collection

A collection of items, including files and folders. Currently, the only collection available is the `favorites` collection. The contents of a collection can be explored in a similar way to which the contents of a folder is explored.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this collection. |
  | `type` | `enum<string>` | No | The value will always be `collection`. Available options: `collection`. |
  | `name` | `enum<string>` | No | The name of the collection. Available options: `Favorites`. |
  | `collection_type` | `enum<string>` | No | The type of the collection. This is used to determine the proper visual treatment for collections. Available options: `favorites`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "collection",
    "name": "Favorites",
    "collection_type": "favorites"
  }
  ```
</Accordion>

## Collections

A list of collections.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of [Collection](#collection) | No | A list of collections. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "11446498",
        "type": "collection",
        "name": "Favorites",
        "collection_type": "favorites"
      }
    ]
  }
  ```
</Accordion>


# Comments resources
Source: https://developer.box.com/reference/comments-resources



Comments are messages generated users on files, allowing users to collaborate on a file, discussing any feedback they might have on the content.

## Comment

Standard representation of a comment.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this comment. |
  | `type` | `enum<string>` | No | The value will always be `comment`. Available options: `comment`. |
  | `is_reply_comment` | `boolean` | No | Whether or not this comment is a reply to another comment. |
  | `message` | `string` | No | The text of the comment, as provided by the user. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | A mini user object representing the author of the comment. |
  | `created_at` | `string` | No | The time this comment was created. |
  | `modified_at` | `string` | No | The time this comment was last modified. |
  | `item` | `object` | No | The bare basic reference for an object. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "comment",
    "is_reply_comment": true,
    "message": "@Aaron Levie these tigers are cool!",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "item": {
      "id": "11446498",
      "type": "file"
    }
  }
  ```
</Accordion>

## Comment (Base)

Base representation of a comment.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this comment. |
  | `type` | `enum<string>` | No | The value will always be `comment`. Available options: `comment`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "comment"
  }
  ```
</Accordion>

## Comment (Full)

Comments are messages created on files. Comments can be made independently or created as responses to other comments.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this comment. |
  | `type` | `enum<string>` | No | The value will always be `comment`. Available options: `comment`. |
  | `is_reply_comment` | `boolean` | No | Whether or not this comment is a reply to another comment. |
  | `message` | `string` | No | The text of the comment, as provided by the user. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | A mini user object representing the author of the comment. |
  | `created_at` | `string` | No | The time this comment was created. |
  | `modified_at` | `string` | No | The time this comment was last modified. |
  | `item` | `object` | No | The bare basic reference for an object. |
  | `tagged_message` | `string` | No | The string representing the comment text with @mentions included. @mention format is @\[id:username] where `id` is user's Box ID and `username` is their display name. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "comment",
    "is_reply_comment": true,
    "message": "@Aaron Levie these tigers are cool!",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "item": {
      "id": "11446498",
      "type": "file"
    },
    "tagged_message": "@[1234567:Aaron Levie] these tigers are cool!"
  }
  ```
</Accordion>

## Comments

A list of comments.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of [Comment (Full)](#comment-full) | No | A list of comments. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "11446498",
        "type": "comment",
        "is_reply_comment": true,
        "message": "@Aaron Levie these tigers are cool!",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "item": {
          "id": "11446498",
          "type": "file"
        },
        "tagged_message": "@[1234567:Aaron Levie] these tigers are cool!"
      }
    ]
  }
  ```
</Accordion>


# Remove domain from list of allowed collaboration domains
Source: https://developer.box.com/reference/delete-collaboration-whitelist-entries-id

box-openapi.json DELETE /collaboration_whitelist_entries/{collaboration_whitelist_entry_id}
Removes a domain from the list of domains that have been deemed safe to create collaborations for within the current enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove user from list of users exempt from domain restrictions
Source: https://developer.box.com/reference/delete-collaboration-whitelist-exempt-targets-id

box-openapi.json DELETE /collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}
Removes a user's exemption from the restrictions set out by the allowed list of domains for collaborations.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove collaboration
Source: https://developer.box.com/reference/delete-collaborations-id

box-openapi.json DELETE /collaborations/{collaboration_id}
Deletes a single collaboration.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove comment
Source: https://developer.box.com/reference/delete-comments-id

box-openapi.json DELETE /comments/{comment_id}
Permanently deletes a comment.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove device pin
Source: https://developer.box.com/reference/delete-device-pinners-id

box-openapi.json DELETE /device_pinners/{device_pinner_id}
Deletes an individual device pin.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete file request
Source: https://developer.box.com/reference/delete-file-requests-id

box-openapi.json DELETE /file_requests/{file_request_id}
Deletes a file request permanently.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete file
Source: https://developer.box.com/reference/delete-files-id

box-openapi.json DELETE /files/{file_id}
Deletes a file, either permanently or by moving it to the trash.

The enterprise settings determine whether the item will be permanently deleted from Box or moved to the trash.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove file version
Source: https://developer.box.com/reference/delete-files-id-versions-id

box-openapi.json DELETE /files/{file_id}/versions/{file_version_id}
Move a file version to the trash.

Versions are only tracked for Box users with premium accounts.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete folder lock
Source: https://developer.box.com/reference/delete-folder-locks-id

box-openapi.json DELETE /folder_locks/{folder_lock_id}
Deletes a folder lock on a given folder.

You must be authenticated as the owner or co-owner of the folder to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete folder
Source: https://developer.box.com/reference/delete-folders-id

box-openapi.json DELETE /folders/{folder_id}
Deletes a folder, either permanently or by moving it to the trash.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove classification from folder
Source: https://developer.box.com/reference/delete-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json DELETE /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Removes any classifications from a folder.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove user from group
Source: https://developer.box.com/reference/delete-group-memberships-id

box-openapi.json DELETE /group_memberships/{group_membership_id}
Deletes a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove group
Source: https://developer.box.com/reference/delete-groups-id

box-openapi.json DELETE /groups/{group_id}
Permanently deletes a group. Only users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete Slack integration mapping
Source: https://developer.box.com/reference/delete-integration-mappings-slack-id

box-openapi.json DELETE /integration_mappings/slack/{integration_mapping_id}
Deletes a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).

You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete Teams integration mapping
Source: https://developer.box.com/reference/delete-integration-mappings-teams-id

box-openapi.json DELETE /integration_mappings/teams/{integration_mapping_id}
Deletes a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove email alias
Source: https://developer.box.com/reference/delete-users-id-email-aliases-id

box-openapi.json DELETE /users/{user_id}/email_aliases/{email_alias_id}
Removes an email alias from a user.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Device pinners resources
Source: https://developer.box.com/reference/device-pinners-resources



Device pinners allow enterprises to control what devices can use native Box applications.

## Device pinner

Device pins allow enterprises to control what devices can use native Box applications.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this device pin. |
  | `type` | `enum<string>` | No | The value will always be `device_pinner`. Available options: `device_pinner`. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user that the device pin belongs to. |
  | `product_name` | `string` | No | The type of device being pinned. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "device_pinner",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "product_name": "iPad"
  }
  ```
</Accordion>

## Device pinners

A list of device pins.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Device pinner](#device-pinner) | No | A list of device pins. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. |
  | `next_marker` | `integer` | No | The marker for the start of the next page of results. |
  | `order` | array of `object` | No | The order by which items are returned. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "11446498",
        "type": "device_pinner",
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "product_name": "iPad"
      }
    ],
    "limit": 200,
    "next_marker": 3000,
    "order": [
      {
        "by": "id",
        "direction": "asc"
      }
    ]
  }
  ```
</Accordion>


# Email aliases resources
Source: https://developer.box.com/reference/email-aliases-resources



Email aliases provide a list of emails additional to the user's primary login email.

## Email alias

An email alias for a user.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this object. |
  | `type` | `enum<string>` | No | The value will always be `email_alias`. Available options: `email_alias`. |
  | `email` | `string` | No | The email address. |
  | `is_confirmed` | `boolean` | No | Whether the email address has been confirmed. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "email_alias",
    "email": "alias@example.com",
    "is_confirmed": true
  }
  ```
</Accordion>

## Email aliases

A list of email aliases.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | The number of email aliases. |
  | `entries` | array of [Email alias](#email-alias) | No | A list of email aliases. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "entries": [
      {
        "id": "11446498",
        "type": "email_alias",
        "email": "alias@example.com",
        "is_confirmed": true
      }
    ]
  }
  ```
</Accordion>


# Events resources
Source: https://developer.box.com/reference/events-resources



Events provide a way for an application to subscribe to any actions performed by any user, users, or service in an enterprise.

## Event

The description of an event that happened within Box.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `string` | No | The value will always be `event`. |
  | `created_at` | `string` | No | When the event object was created. |
  | `recorded_at` | `string` | No | When the event object was recorded in database. |
  | `event_id` | `string` | No | The ID of the event object. You can use this to detect duplicate events. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user that performed the action represented by the event. Some events may be performed by users not logged into Box. In that case, not all attributes of the object are populated and the event is attributed to a unknown user (`user_id = 2`). |
  | `event_type` | `enum<string>` | No | An event type that can trigger an event. Available options: `ACCESS_GRANTED`, `ACCESS_REVOKED`, `ADD_DEVICE_ASSOCIATION`, `ADD_LOGIN_ACTIVITY_DEVICE`, `ADMIN_LOGIN`, `ADVANCED_FOLDER_SETTINGS_UPDATE`, `AI_SECURITY_DETECTION`, `ANNOTATIONV2_CREATE`, `ANNOTATIONV2_DELETE`, `ANNOTATIONV2_EDIT`, `APPLICATION_CREATED`, `APPLICATION_PUBLIC_KEY_ADDED`, `APPLICATION_PUBLIC_KEY_DELETED`, `BOX_AI_USER_FAILED_REQUEST`, `BOX_AI_USER_REQUEST`, `CHANGE_ADMIN_ROLE`, `CHANGE_FOLDER_PERMISSION`, `COLLABORATION_ACCEPT`, `COLLABORATION_EXPIRATION`, `COLLABORATION_INVITE`, `COLLABORATION_REMOVE`, `COLLABORATION_ROLE_CHANGE`, `COLLAB_ADD_COLLABORATOR`, `COLLAB_INVITE_COLLABORATOR`, `COLLAB_REMOVE_COLLABORATOR`, `COLLAB_ROLE_CHANGE`, `COLLECTION_CREATE`, `COLLECTION_DELETE`, `COLLECTION_ITEM_CREATE`, `COLLECTION_ITEM_DELETE`, `COLLECTION_ITEM_UPDATE`, `COLLECTION_UPDATE`, `COMMENT_CREATE`, `COMMENT_DELETE`, `COMMENT_EDIT`, `CONTENT_ACCESS`, `CONTENT_RECOVERY_REPORT_CREATE`, `CONTENT_RECOVERY_REPORT_DELETE`, `CONTENT_RECOVERY_REPORT_INITIATE`, `CONTENT_WORKFLOW_ABNORMAL_DOWNLOAD_ACTIVITY`, `CONTENT_WORKFLOW_AUTOMATION_ADD`, `CONTENT_WORKFLOW_AUTOMATION_DELETE`, `CONTENT_WORKFLOW_POLICY_ADD`, `CONTENT_WORKFLOW_SHARING_POLICY_VIOLATION`, `CONTENT_WORKFLOW_UPLOAD_POLICY_VIOLATION`, `COPY`, `DATA_RETENTION_CREATE_RETENTION`, `DATA_RETENTION_REMOVE_RETENTION`, `DELETE`, `DELETE_USER`, `DEVICE_TRUST_CHECK_FAILED`, `DISABLE_MULTI_FACTOR_AUTH`, `DOWNLOAD`, `EDIT`, `EDIT_USER`, `EDR_CROWDSTRIKE_ACCESS_ALLOWED_NO_CROWDSTRIKE_DEVICE`, `EDR_CROWDSTRIKE_ACCESS_REVOKED`, `EDR_CROWDSTRIKE_BOX_TOOLS_OUTDATED`, `EDR_CROWDSTRIKE_DEVICE_DETECTED`, `EDR_CROWDSTRIKE_DRIVE_OUTDATED`, `EDR_CROWDSTRIKE_NO_BOX_TOOLS`, `EMAIL_ALIAS_CONFIRM`, `EMAIL_ALIAS_PRIMARY`, `EMAIL_ALIAS_REMOVE`, `EMAIL_UPLOAD_DISABLED`, `EMAIL_UPLOAD_ENABLED`, `ENABLE_MULTI_FACTOR_AUTH`, `ENABLE_TWO_FACTOR_AUTH`, `ENTERPRISE_APP_AUTHORIZATION_UPDATE`, `EXTERNAL_COLLAB_SECURITY_SETTINGS`, `FAILED_LOGIN`, `FAVORITE`, `FILE_MARKED_MALICIOUS`, `FILE_REQUEST_CREATE`, `FILE_REQUEST_DELETE`, `FILE_REQUEST_UPDATE`, `FILE_VERSION_RESTORE`, `FILE_WATERMARKED_DOWNLOAD`, `GROUP_ADD_ITEM`, `GROUP_ADD_USER`, `GROUP_ADMIN_CREATED`, `GROUP_ADMIN_DELETED`, `GROUP_ADMIN_PERMISSIONS_UPDATED`, `GROUP_CREATION`, `GROUP_DELETION`, `GROUP_EDITED`, `GROUP_REMOVE_ITEM`, `GROUP_REMOVE_USER`, `ILLEGAL_ITEM_OWNERSHIP_TRANSFER_BY_USER`, `ITEM_ASSOCIATION_CREATED`, `ITEM_ASSOCIATION_DELETED`, `ITEM_ASSOCIATION_UPDATED`, `ITEM_COPY`, `ITEM_CREATE`, `ITEM_DOWNLOAD`, `ITEM_EMAIL_SEND`, `ITEM_MAKE_CURRENT_VERSION`, `ITEM_MODIFY`, `ITEM_MOVE`, `ITEM_OPEN`, `ITEM_PREVIEW`, `ITEM_RENAME`, `ITEM_SHARED`, `ITEM_SHARED_CREATE`, `ITEM_SHARED_UNSHARE`, `ITEM_SHARED_UPDATE`, `ITEM_SYNC`, `ITEM_TRASH`, `ITEM_UNDELETE_VIA_TRASH`, `ITEM_UNSYNC`, `ITEM_UPLOAD`, `LEGAL_HOLD_ASSIGNMENT_CREATE`, `LEGAL_HOLD_ASSIGNMENT_DELETE`, `LEGAL_HOLD_POLICY_CREATE`, `LEGAL_HOLD_POLICY_DELETE`, `LEGAL_HOLD_POLICY_UPDATE`, `LOCK`, `LOCK_CREATE`, `LOCK_DESTROY`, `LOGIN`, `MASTER_INVITE_ACCEPT`, `MASTER_INVITE_REJECT`, `METADATA_CASCADE_POLICY_APPLY`, `METADATA_CASCADE_POLICY_CREATE`, `METADATA_INSTANCE_COPY`, `METADATA_INSTANCE_CREATE`, `METADATA_INSTANCE_DELETE`, `METADATA_INSTANCE_UPDATE`, `METADATA_TEMPLATE_CREATE`, `METADATA_TEMPLATE_DELETE`, `METADATA_TEMPLATE_UPDATE`, `MOVE`, `NEW_USER`, `OAUTH2_ACCESS_TOKEN_REVOKE`, `OAUTH2_REFRESH_TOKEN_REVOKE`, `PREVIEW`, `REMOVE_DEVICE_ASSOCIATION`, `REMOVE_LOGIN_ACTIVITY_DEVICE`, `RENAME`, `RETENTION_POLICY_ASSIGNMENT_ADD`, `SHARE`, `SHARED_LINK_REDIRECT_OUT_OF_SHARED_CONTEXT`, `SHARED_LINK_SEND`, `SHARE_EXPIRATION`, `SHIELD_ACCESS_POLICY_CREATED`, `SHIELD_ACCESS_POLICY_DELETED`, `SHIELD_ACCESS_POLICY_UPDATED`, `SHIELD_ALERT`, `SHIELD_DOWNLOAD_BLOCKED`, `SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED`, `SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION`, `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED`, `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION`, `SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED`, `SHIELD_INFORMATION_BARRIER_COLLAB_BLOCKED`, `SHIELD_INFORMATION_BARRIER_DISABLED`, `SHIELD_INFORMATION_BARRIER_ENABLED`, `SHIELD_INFORMATION_BARRIER_GROUP_ADD_USER_BLOCKED`, `SHIELD_INFORMATION_BARRIER_ITEM_COPY_BLOCKED`, `SHIELD_INFORMATION_BARRIER_ITEM_MOVE_BLOCKED`, `SHIELD_INFORMATION_BARRIER_ITEM_OWNER_TRANSFER_BLOCKED`, `SHIELD_INFORMATION_BARRIER_PENDING`, `SHIELD_INFORMATION_BARRIER_SHARED_ITEM_ACCESS_BLOCKED`, `SHIELD_JUSTIFICATION_APPROVAL`, `SHIELD_PREVIEW_BLOCKED`, `SHIELD_SHARED_LINK_ACCESS_BLOCKED`, `SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_CREATE`, `SHIELD_SHARED_LINK_STATUS_RESTRICTED_ON_UPDATE`, `SIGN_DOCUMENT_ASSIGNED`, `SIGN_DOCUMENT_CANCELLED`, `SIGN_DOCUMENT_COMPLETED`, `SIGN_DOCUMENT_CONVERTED`, `SIGN_DOCUMENT_CREATED`, `SIGN_DOCUMENT_DECLINED`, `SIGN_DOCUMENT_EXPIRED`, `SIGN_DOCUMENT_SIGNED`, `SIGN_DOCUMENT_VIEWED_BY_SIGNED`, `SIGN_DOCUMENT_VIEWED_BY_SIGNER`, `SIGNER_DOWNLOADED`, `SIGNER_FORWARDED`, `STORAGE_EXPIRATION`, `TAG_ITEM_CREATE`, `TASK_ASSIGNMENT_CREATE`, `TASK_ASSIGNMENT_DELETE`, `TASK_ASSIGNMENT_UPDATE`, `TASK_CREATE`, `TASK_UPDATE`, `TERMS_OF_SERVICE_ACCEPT`, `TERMS_OF_SERVICE_REJECT`, `UNDELETE`, `UNFAVORITE`, `UNLOCK`, `UNSHARE`, `UPDATE_COLLABORATION_EXPIRATION`, `UPDATE_SHARE_EXPIRATION`, `UPLOAD`, `USER_AUTHENTICATE_OAUTH2_ACCESS_TOKEN_CREATE`, `WATERMARK_LABEL_CREATE`, `WATERMARK_LABEL_DELETE`, `WORKFLOW_AUTOMATION_CREATE`, `WORKFLOW_AUTOMATION_DELETE`, `WORKFLOW_AUTOMATION_UPDATE`. |
  | `session_id` | `string` | No | The session of the user that performed the action. Not all events will populate this attribute. |
  | `source` | `Event source resource` | No | The resource that triggered this event. For more information, check out the guide on event triggers. |
  | `additional_details` | `object` | No | This object provides additional information about the event if available. This can include how a user performed an event as well as additional information to correlate an event to external KeySafe logs. Not all events have an `additional_details` object. This object is only available in the Enterprise Events. |

  ```json Example theme={null}
  {
    "type": "event",
    "created_at": "2022-12-12T10:53:43-08:00",
    "recorded_at": "2022-12-12T10:54:43-08:00",
    "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "event_type": "FILE_MARKED_MALICIOUS",
    "session_id": "70090280850c8d2a1933c1",
    "source": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com",
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "language": "en",
      "timezone": "Africa/Bujumbura",
      "space_amount": 11345156112,
      "space_used": 1237009912,
      "max_upload_size": 2147483648,
      "status": "active",
      "job_title": "CEO",
      "phone": "6509241374",
      "address": "900 Jefferson Ave, Redwood City, CA 94063",
      "avatar_url": "https://www.box.com/api/avatar/large/181216415",
      "notification_email": {
        "email": "notifications@example.com",
        "is_confirmed": true
      }
    },
    "additional_details": {
      "key": "value"
    }
  }
  ```
</Accordion>

## Events

A list of event objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `chunk_size` | `integer` | No | The number of events returned in this response. |
  | `next_stream_position` | `string` | No | The stream position of the start of the next page (chunk) of events. |
  | `entries` | array of [Event](#event) | No | A list of events. |

  ```json Example theme={null}
  {
    "chunk_size": 2,
    "next_stream_position": "1152922976252290886",
    "entries": [
      {
        "type": "event",
        "created_at": "2022-12-12T10:53:43-08:00",
        "recorded_at": "2022-12-12T10:54:43-08:00",
        "event_id": "f82c3ba03e41f7e8a7608363cc6c0390183c3f83",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "event_type": "FILE_MARKED_MALICIOUS",
        "session_id": "70090280850c8d2a1933c1",
        "source": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com",
          "created_at": "2012-12-12T10:53:43-08:00",
          "modified_at": "2012-12-12T10:53:43-08:00",
          "language": "en",
          "timezone": "Africa/Bujumbura",
          "space_amount": 11345156112,
          "space_used": 1237009912,
          "max_upload_size": 2147483648,
          "status": "active",
          "job_title": "CEO",
          "phone": "6509241374",
          "address": "900 Jefferson Ave, Redwood City, CA 94063",
          "avatar_url": "https://www.box.com/api/avatar/large/181216415",
          "notification_email": {
            "email": "notifications@example.com",
            "is_confirmed": true
          }
        },
        "additional_details": {
          "key": "value"
        }
      }
    ]
  }
  ```
</Accordion>

## Real-time servers

A list of real-time servers that can be used for long-polling.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `chunk_size` | `integer` | No | The number of items in this response. |
  | `entries` | array of `Real-time server` | No | A list of real-time servers. |

  ```json Example theme={null}
  {
    "chunk_size": 1,
    "entries": [
      {
        "type": "realtime_server",
        "url": "http://2.realtime.services.box.net/subscribe?channel=cc807c9c4869ffb1c81a&stream_type=all",
        "ttl": "10",
        "max_retries": "10",
        "retry_timeout": 610
      }
    ]
  }
  ```
</Accordion>


# File requests resources
Source: https://developer.box.com/reference/file-requests-resources



File Requests provide a fast and secure way to request files and associated metadata from anyone. Users can create new file requests based on an existing file request, update file request settings, activate, deactivate, and delete file requests programmatically.

## File Request

A standard representation of a file request, as returned from any file request API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this file request. Read-only. |
  | `type` | `enum<string>` | Yes | The value will always be `file_request`. Available options: `file_request`. Read-only. |
  | `title` | `string` | No | The title of file request. This is shown in the Box UI to users uploading files. This defaults to title of the file request that was copied to create this file request. |
  | `description` | `string` | No | The optional description of this file request. This is shown in the Box UI to users uploading files. This defaults to description of the file request that was copied to create this file request. Can be `null`. |
  | `status` | `enum<string>` | No | The status of the file request. This defaults to `active`. When the status is set to `inactive`, the file request will no longer accept new submissions, and any visitor to the file request URL will receive a `HTTP 404` status code. This defaults to status of file request that was copied to create this file request. Available options: `active`, `inactive`. |
  | `is_email_required` | `boolean` | No | Whether a file request submitter is required to provide their email address. When this setting is set to true, the Box UI will show an email field on the file request form. This defaults to setting of file request that was copied to create this file request. |
  | `is_description_required` | `boolean` | No | Whether a file request submitter is required to provide a description of the files they are submitting. When this setting is set to true, the Box UI will show a description field on the file request form. This defaults to setting of file request that was copied to create this file request. |
  | `expires_at` | `string` | No | The date after which a file request will no longer accept new submissions. After this date, the `status` will automatically be set to `inactive`. |
  | `folder` | [Folder (Mini)](/reference/folders-resources#folder-mini) | Yes | The folder that this file request is associated with. Files submitted through the file request form will be uploaded to this folder. |
  | `url` | `string` | No | The generated URL for this file request. This URL can be shared with users to let them upload files to the associated folder. Read-only. |
  | `etag` | `string` | No | The HTTP `etag` of this file. This can be used in combination with the `If-Match` header when updating a file request. By providing that header, a change will only be performed on the file request if the `etag` on the file request still matches the `etag` provided in the `If-Match` header. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this file request. |
  | `created_at` | `string` | Yes | The date and time when the file request was created. |
  | `updated_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this file request. |
  | `updated_at` | `string` | Yes | The date and time when the file request was last updated. |

  ```json Example theme={null}
  {
    "id": "42037322",
    "type": "file_request",
    "title": "Please upload documents",
    "description": "Following documents are requested for your process",
    "status": "active",
    "is_email_required": true,
    "is_description_required": true,
    "expires_at": "2020-09-28T10:53:43-08:00",
    "folder": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "url": "/f/19e57f40ace247278a8e3d336678c64a",
    "etag": "1",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2020-09-28T10:53:43-08:00",
    "updated_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "updated_at": "2020-09-28T10:53:43-08:00"
  }
  ```
</Accordion>


# File version legal holds resources
Source: https://developer.box.com/reference/file-version-legal-holds-resources



A legal hold is a process that an enterprise can use to preserve all forms of potentially relevant information when litigation is pending or reasonably anticipated. A File Version Legal Hold represents all the policies that are assigned to a specific file version.

## File version legal hold

File version legal hold is an entity representing all holds on a File Version.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this file version legal hold. |
  | `type` | `enum<string>` | No | The value will always be `file_version_legal_hold`. Available options: `file_version_legal_hold`. |
  | `file_version` | `File version (Mini)` | No | The file version that is held. |
  | `file` | [File (Mini)](/reference/files-resources#file-mini) | No | The file for the file version held. Note that there is no guarantee that the current version of this file is held. |
  | `legal_hold_policy_assignments` | array of [Legal hold policy assignment](/reference/legal-hold-policy-assignments-resources#legal-hold-policy-assignment) | No | List of assignments contributing to this Hold. |
  | `deleted_at` | `string` | No | Time that this File-Version-Legal-Hold was deleted. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "file_version_legal_hold",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "file": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    },
    "legal_hold_policy_assignments": [
      {
        "id": "11446498",
        "type": "legal_hold_policy_assignment",
        "legal_hold_policy": {
          "id": "11446498",
          "type": "legal_hold_policy"
        },
        "assigned_to": {
          "type": "folder",
          "id": "6564564"
        },
        "assigned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "assigned_at": "2012-12-12T10:53:43-08:00",
        "deleted_at": "2012-12-12T10:53:43-08:00"
      }
    ],
    "deleted_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## File version legal holds

A list of file versions with legal holds.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [File version legal hold](#file-version-legal-hold) | No | A list of file version legal holds. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "file_version_legal_hold",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "file": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "legal_hold_policy_assignments": [
          {
            "id": "11446498",
            "type": "legal_hold_policy_assignment",
            "legal_hold_policy": {
              "id": "11446498",
              "type": "legal_hold_policy"
            },
            "assigned_to": {
              "type": "folder",
              "id": "6564564"
            },
            "assigned_by": {
              "id": "11446498",
              "type": "user",
              "name": "Aaron Levie",
              "login": "ceo@example.com"
            },
            "assigned_at": "2012-12-12T10:53:43-08:00",
            "deleted_at": "2012-12-12T10:53:43-08:00"
          }
        ],
        "deleted_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# File version retentions resources
Source: https://developer.box.com/reference/file-version-retentions-resources



A retention policy blocks permanent deletion of content for a specified amount of time. A file version retention is a record for a retained file.

## File version retention

A retention policy blocks permanent deletion of content for a specified amount of time. Admins can apply policies to specified folders, or an entire enterprise. A file version retention is a record for a retained file version. To use this feature, you must have the manage retention policies scope enabled for your API key in your application management console. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this file version retention. |
  | `type` | `enum<string>` | No | The value will always be `file_version_retention`. Available options: `file_version_retention`. |
  | `file_version` | `File version (Mini)` | No | The file version this file version retention was applied to. |
  | `file` | [File (Mini)](/reference/files-resources#file-mini) | No | The file this file version retention was applied to. |
  | `applied_at` | `string` | No | When this file version retention object was created. |
  | `disposition_at` | `string` | No | When the retention expires on this file version retention. |
  | `winning_retention_policy` | [Retention policy (Mini)](/reference/retention-policies-resources#retention-policy-mini) | No | The winning retention policy applied to this file version retention. A file version can have multiple retention policies applied. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "file_version_retention",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "file": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    },
    "applied_at": "2012-12-12T10:53:43-08:00",
    "disposition_at": "2012-12-12T10:53:43-08:00",
    "winning_retention_policy": {
      "id": "12345",
      "type": "retention_policy",
      "policy_name": "Some Policy Name",
      "retention_length": "365",
      "disposition_action": "permanently_delete",
      "max_extension_length": "365"
    }
  }
  ```
</Accordion>

## File version retentions

A list of file version retentions. **Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [File version retention](#file-version-retention) | No | A list of file version retentions. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "file_version_retention",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "file": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "applied_at": "2012-12-12T10:53:43-08:00",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "winning_retention_policy": {
          "id": "12345",
          "type": "retention_policy",
          "policy_name": "Some Policy Name",
          "retention_length": "365",
          "disposition_action": "permanently_delete",
          "max_extension_length": "365"
        }
      }
    ]
  }
  ```
</Accordion>


# File versions resources
Source: https://developer.box.com/reference/file-versions-resources



A set of endpoints used to manage specific versions of a file.

## File versions

A list of file versions.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of `File version (Full)` | No | A list of file versions. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
        "name": "tigers.jpeg",
        "size": 629644,
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "trashed_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "restored_at": "2012-12-12T10:53:43-08:00",
        "restored_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "purged_at": "2012-12-12T10:53:43-08:00",
        "uploader_display_name": "Ellis Wiggins",
        "version_number": "1"
      }
    ]
  }
  ```
</Accordion>


# Files resources
Source: https://developer.box.com/reference/files-resources



Files, together with Folders, are at the core of the Box API. Files can be uploaded and downloaded, as well as hold important metadata information about the content.

## File

A standard representation of a file, as returned from any file API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent 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/123` the `file_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `file`. Available options: `file`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the file. |
  | `sha1` | `string` | No | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
  | `file_version` | `File version (Mini)` | No | The information about the current version of the file. |
  | `description` | `string` | No | The optional description of this file. If the description exceeds 255 characters, the first 255 characters are set as a file description and the rest of it is ignored. |
  | `size` | `integer` | No | The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. |
  | `path_collection` | `object` | No | A list of parent folders for an item. |
  | `created_at` | `string` | No | The date and time when the file was created on Box. |
  | `modified_at` | `string` | No | The date and time when the file was last updated on Box. |
  | `trashed_at` | `string` | No | The time at which this file was put in the trash. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this file is expected to be purged from the trash. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this file was originally created, which might be before it was uploaded to Box. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this file was last updated, which might be before it was uploaded to Box. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this file. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this file. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this file. |
  | `shared_link` | `object` | No | Shared links provide direct, read-only access to files or folder on Box. Shared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users. Can be `null`. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The folder that this file is located within. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `item_status` | `enum<string>` | No | Defines if this item has been deleted or not. - `active` when the item has is not in the trash - `trashed` when the item has been moved to the trash but not deleted - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "file",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "description": "Contract for Q1 renewal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": {
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "vanity_url": "https://acme.app.box.com/v/my_url/",
      "vanity_name": "my_url",
      "access": "open",
      "effective_access": "company",
      "effective_permission": "can_download",
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "is_password_enabled": true,
      "permissions": {
        "can_download": true,
        "can_preview": true,
        "can_edit": false
      },
      "download_count": 3,
      "preview_count": 3
    },
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "active"
  }
  ```
</Accordion>

## File (Base)

The bare basic representation of a file, the minimal amount of fields returned when using the `fields` query parameter.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent 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/123` the `file_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `file`. Available options: `file`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "file"
  }
  ```
</Accordion>

## File (Full)

A full representation of a file, as can be returned from any file API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent 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/123` the `file_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `file`. Available options: `file`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the file. |
  | `sha1` | `string` | No | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
  | `file_version` | `File version (Mini)` | No | The information about the current version of the file. |
  | `description` | `string` | No | The optional description of this file. If the description exceeds 255 characters, the first 255 characters are set as a file description and the rest of it is ignored. |
  | `size` | `integer` | No | The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. |
  | `path_collection` | `object` | No | A list of parent folders for an item. |
  | `created_at` | `string` | No | The date and time when the file was created on Box. |
  | `modified_at` | `string` | No | The date and time when the file was last updated on Box. |
  | `trashed_at` | `string` | No | The time at which this file was put in the trash. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this file is expected to be purged from the trash. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this file was originally created, which might be before it was uploaded to Box. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this file was last updated, which might be before it was uploaded to Box. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this file. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this file. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this file. |
  | `shared_link` | `object` | No | Shared links provide direct, read-only access to files or folder on Box. Shared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users. Can be `null`. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The folder that this file is located within. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `item_status` | `enum<string>` | No | Defines if this item has been deleted or not. - `active` when the item has is not in the trash - `trashed` when the item has been moved to the trash but not deleted - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |
  | `version_number` | `string` | No | The version number of this file. |
  | `comment_count` | `integer` | No | The number of comments on this file. |
  | `permissions` | `object` | No | The permissions that the authenticated user has for a file. |
  | `tags` | array of `string` | No | The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise. |
  | `lock` | `object` | No | The lock held on a file. A lock prevents a file from being moved, renamed, or otherwise changed by anyone else than the user who created the lock. Can be `null`. |
  | `extension` | `string` | No | Indicates the (optional) file extension for this file. By default, this is set to an empty string. |
  | `is_package` | `boolean` | No | Indicates if the file is a package. Packages are commonly used by Mac Applications and can include iWork files. |
  | `expiring_embed_link` | `object` | No | An expiring Box Embed Link. |
  | `watermark_info` | `object` | No | Details about the watermark applied to this item. |
  | `is_accessible_via_shared_link` | `boolean` | No | Specifies if the file can be accessed via the direct shared link or a shared link to a parent folder. |
  | `allowed_invitee_roles` | array of `enum<string>` | No | A list of the types of roles that user can be invited at when sharing this file. |
  | `is_externally_owned` | `boolean` | No | Specifies if this file is owned by a user outside of the authenticated enterprise. |
  | `has_collaborations` | `boolean` | No | Specifies if this file has any other collaborators. |
  | `metadata` | `object` | No | A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`. To access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise. Then use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID. To request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata.<scope>.<templateKey>` For example, `?fields=metadata.enterprise_27335.marketingCollateral`. |
  | `expires_at` | `string` | No | When the file will automatically be deleted. Can be `null`. |
  | `representations` | `object` | No | A list of file representations. |
  | `classification` | `object` | No | The classification applied to an item. Can be `null`. |
  | `uploader_display_name` | `string` | No | The display name of the user that uploaded the file. In most cases this is the name of the user logged in at the time of the upload. If the file was uploaded using a File Request form that requires the user to provide an email address, this field is populated with that email address. If an email address was not required in the File Request form, this field is set to return a value of `File Request`. In all other anonymous cases where no email was provided this field will default to a value of `Someone`. |
  | `disposition_at` | `string` | No | The retention expiration timestamp for the given file. Can be `null`. |
  | `shared_link_permission_options` | array of `enum<string>` | No | A list of the types of roles that user can be invited at when sharing this file. Can be `null`. |
  | `is_associated_with_app_item` | `boolean` | No | This field will return true if the file or any ancestor of the file is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the file. |
  | `collections` | array of [Collection](/reference/collections-resources#collection) | No | The collections that this file belongs to. For more information, see the [collections guide](/guides/collections). |
  | `is_download_available` | `boolean` | No | Whether the file's binary content is eligible to be downloaded. This is a content-level flag and does not reflect whether the current user is authorized to download the file. Use `permissions.can_download`, when available, for that. |
  | `download_url` | `string` | No | A pre-authorized, expiring URL for directly downloading the file's content. Requires authentication and is valid only for the current session. This field is only returned for files, not folders or web links. |
  | `authenticated_download_url` | `string` | No | A stable API URL for the file content endpoint, `/2.0/files/{id}/content`. Unlike `download_url`, authorization is evaluated when the URL is requested with a valid access token. This field is only returned for files, not folders or web links. |
  | `allowed_shared_link_access_levels` | array of `enum<string>` | No | The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this file. The list depends on item policy and user authorization, so it may be narrower than the levels available to the owner. An empty array means no access level is available to this user. |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "file",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "description": "Contract for Q1 renewal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": {
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "vanity_url": "https://acme.app.box.com/v/my_url/",
      "vanity_name": "my_url",
      "access": "open",
      "effective_access": "company",
      "effective_permission": "can_download",
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "is_password_enabled": true,
      "permissions": {
        "can_download": true,
        "can_preview": true,
        "can_edit": false
      },
      "download_count": 3,
      "preview_count": 3
    },
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "active",
    "version_number": "1",
    "comment_count": 10,
    "permissions": {
      "can_delete": true,
      "can_download": true,
      "can_invite_collaborator": true,
      "can_rename": true,
      "can_set_share_access": true,
      "can_share": true,
      "can_annotate": true,
      "can_comment": true,
      "can_preview": true,
      "can_upload": true,
      "can_view_annotations_all": true,
      "can_view_annotations_self": true,
      "can_apply_watermark": true
    },
    "tags": [
      "approved"
    ],
    "lock": {
      "id": "11446498",
      "type": "lock",
      "created_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "expired_at": "2012-12-12T10:53:43-08:00",
      "is_download_prevented": true,
      "app_type": "office_wopiplus"
    },
    "extension": "pdf",
    "is_package": true,
    "expiring_embed_link": {
      "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
      "expires_in": 3600,
      "token_type": "bearer",
      "restricted_to": [
        {
          "scope": "item_download",
          "object": {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          }
        }
      ],
      "url": "https://cloud.app.box.com/preview/expiring_embed/..."
    },
    "watermark_info": {
      "is_watermarked": true,
      "is_watermark_inherited": false,
      "is_watermarked_by_access_policy": false
    },
    "is_accessible_via_shared_link": true,
    "allowed_invitee_roles": [
      "editor"
    ],
    "is_externally_owned": true,
    "has_collaborations": true,
    "metadata": {
      "enterprise_27335": {
        "marketingCollateral": {
          "$canEdit": true,
          "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
          "$parent": "folder_59449484661",
          "$scope": "enterprise_27335",
          "$template": "marketingCollateral",
          "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
          "$typeVersion": 2,
          "$version": 1
        }
      }
    },
    "expires_at": "2012-12-12T10:53:43-08:00",
    "representations": {
      "entries": [
        {
          "content": {
            "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
          },
          "info": {
            "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
          },
          "properties": {
            "dimensions": "2048x2048",
            "paged": "true",
            "thumb": "true"
          },
          "representation": "png",
          "status": {
            "state": "success"
          }
        }
      ]
    },
    "classification": {
      "name": "Top Secret",
      "definition": "Content that should not be shared outside the company.",
      "color": "#FF0000"
    },
    "uploader_display_name": "Ellis Wiggins",
    "disposition_at": "2012-12-12T10:53:43-08:00",
    "shared_link_permission_options": [
      "can_preview"
    ],
    "is_associated_with_app_item": true,
    "collections": [
      {
        "id": "11446498",
        "type": "collection",
        "name": "Favorites",
        "collection_type": "favorites"
      }
    ],
    "is_download_available": true,
    "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
    "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
    "allowed_shared_link_access_levels": [
      "open"
    ]
  }
  ```
</Accordion>

## File (Mini)

A mini representation of a file, used when nested under another resource.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent 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/123` the `file_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `file`. Available options: `file`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the file. |
  | `sha1` | `string` | No | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
  | `file_version` | `File version (Mini)` | No | The information about the current version of the file. |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "file",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    }
  }
  ```
</Accordion>

## Files

A list of files.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | The number of files. |
  | `entries` | array of [File (Full)](#file-full) | No | A list of files. |

  ```json Example theme={null}
  {
    "total_count": 1,
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "description": "Contract for Q1 renewal",
        "size": 629644,
        "path_collection": {
          "total_count": 1,
          "entries": [
            {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          ]
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "purged_at": "2012-12-12T10:53:43-08:00",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "vanity_url": "https://acme.app.box.com/v/my_url/",
          "vanity_name": "my_url",
          "access": "open",
          "effective_access": "company",
          "effective_permission": "can_download",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_preview": true,
            "can_edit": false
          },
          "download_count": 3,
          "preview_count": 3
        },
        "parent": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "item_status": "active",
        "version_number": "1",
        "comment_count": 10,
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true,
          "can_apply_watermark": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "expired_at": "2012-12-12T10:53:43-08:00",
          "is_download_prevented": true,
          "app_type": "office_wopiplus"
        },
        "extension": "pdf",
        "is_package": true,
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "token_type": "bearer",
          "restricted_to": [
            {
              "scope": "item_download",
              "object": {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            }
          ],
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "watermark_info": {
          "is_watermarked": true,
          "is_watermark_inherited": false,
          "is_watermarked_by_access_policy": false
        },
        "is_accessible_via_shared_link": true,
        "allowed_invitee_roles": [
          "editor"
        ],
        "is_externally_owned": true,
        "has_collaborations": true,
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "expires_at": "2012-12-12T10:53:43-08:00",
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "classification": {
          "name": "Top Secret",
          "definition": "Content that should not be shared outside the company.",
          "color": "#FF0000"
        },
        "uploader_display_name": "Ellis Wiggins",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "shared_link_permission_options": [
          "can_preview"
        ],
        "is_associated_with_app_item": true,
        "collections": [
          {
            "id": "11446498",
            "type": "collection",
            "name": "Favorites",
            "collection_type": "favorites"
          }
        ],
        "is_download_available": true,
        "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
        "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
        "allowed_shared_link_access_levels": [
          "open"
        ]
      }
    ]
  }
  ```
</Accordion>


# Folder Locks resources
Source: https://developer.box.com/reference/folder-locks-resources



Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.

## Folder Lock

Folder locks define access restrictions placed by folder owners to prevent specific folders from being moved or deleted.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `folder` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The folder that the lock applies to. |
  | `id` | `string` | No | The unique identifier for this folder lock. |
  | `type` | `string` | No | The object type, always `folder_lock`. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user or group that created the lock. |
  | `created_at` | `string` | No | When the folder lock object was created. |
  | `locked_operations` | `object` | No | The operations that have been locked. Currently the `move` and `delete` operations cannot be locked separately, and both need to be set to `true`. |
  | `lock_type` | `string` | No | The lock type, always `freeze`. |

  ```json Example theme={null}
  {
    "folder": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "id": "12345678",
    "type": "folder_lock",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "created_at": "2020-09-14T23:12:53Z",
    "locked_operations": {
      "move": true,
      "delete": true
    },
    "lock_type": "freeze"
  }
  ```
</Accordion>

## Folder Locks

A list of folder locks.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Folder Lock](#folder-lock) | No | A list of folder locks. |
  | `limit` | `string` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "folder": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "id": "12345678",
        "type": "folder_lock",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "created_at": "2020-09-14T23:12:53Z",
        "locked_operations": {
          "move": true,
          "delete": true
        },
        "lock_type": "freeze"
      }
    ],
    "limit": "1000",
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Folders resources
Source: https://developer.box.com/reference/folders-resources



Folders, together with Files, are at the core of the Box API. Folders can be uploaded and downloaded, as well as hold important metadata information about the content.

## Folder

A standard representation of a folder, as returned from any folder API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `folder`. Available options: `folder`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the folder. |
  | `created_at` | `string` | No | The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `modified_at` | `string` | No | The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `description` | `string` | No | The optional description of this folder. |
  | `size` | `integer` | No | The folder size in bytes. Be careful parsing this integer as its value can get very large. |
  | `path_collection` | `object` | No | A list of parent folders for an item. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this folder. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this folder. |
  | `trashed_at` | `string` | No | The time at which this folder was put in the trash. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this folder is expected to be purged from the trash. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this folder was originally created. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this folder was last updated. Can be `null`. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this folder. |
  | `shared_link` | `object` | No | Shared links provide direct, read-only access to files or folder on Box. Shared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users. Can be `null`. |
  | `folder_upload_email` | `object` | No | The `folder_upload_email` parameter is not `null` if one of the following options is **true**: - The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted. - The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked). If the conditions are not met, the parameter will have the following value: `folder_upload_email: null`. Can be `null`. |
  | `parent` | [Folder (Mini)](#folder-mini) | No | The optional folder that this folder is located within. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `item_status` | `enum<string>` | No | Defines if this item has been deleted or not. - `active` when the item has is not in the trash - `trashed` when the item has been moved to the trash but not deleted - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |
  | `item_collection` | [Items](#items) | No | A page of the items that are in the folder. This field can only be requested when querying a folder's information, not when querying a folder's items. |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "description": "Legal contracts for the new ACME deal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": {
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "vanity_url": "https://acme.app.box.com/v/my_url/",
      "vanity_name": "my_url",
      "access": "open",
      "effective_access": "company",
      "effective_permission": "can_download",
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "is_password_enabled": true,
      "permissions": {
        "can_download": true,
        "can_preview": true,
        "can_edit": false
      },
      "download_count": 3,
      "preview_count": 3
    },
    "folder_upload_email": {
      "access": "open",
      "email": "upload.Contracts.asd7asd@u.box.com"
    },
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "active",
    "item_collection": {
      "limit": 1000,
      "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
      "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
      "total_count": 5000,
      "offset": 2000,
      "order": [
        {
          "by": "type",
          "direction": "ASC"
        }
      ],
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          },
          "description": "Contract for Q1 renewal",
          "size": 629644,
          "path_collection": {
            "total_count": 1,
            "entries": [
              {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            ]
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "modified_at": "2012-12-12T10:53:43-08:00",
          "trashed_at": "2012-12-12T10:53:43-08:00",
          "purged_at": "2012-12-12T10:53:43-08:00",
          "content_created_at": "2012-12-12T10:53:43-08:00",
          "content_modified_at": "2012-12-12T10:53:43-08:00",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "modified_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "owned_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "shared_link": {
            "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
            "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
            "vanity_url": "https://acme.app.box.com/v/my_url/",
            "vanity_name": "my_url",
            "access": "open",
            "effective_access": "company",
            "effective_permission": "can_download",
            "unshared_at": "2018-04-13T13:53:23-07:00",
            "is_password_enabled": true,
            "permissions": {
              "can_download": true,
              "can_preview": true,
              "can_edit": false
            },
            "download_count": 3,
            "preview_count": 3
          },
          "parent": {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          },
          "item_status": "active",
          "version_number": "1",
          "comment_count": 10,
          "permissions": {
            "can_delete": true,
            "can_download": true,
            "can_invite_collaborator": true,
            "can_rename": true,
            "can_set_share_access": true,
            "can_share": true,
            "can_annotate": true,
            "can_comment": true,
            "can_preview": true,
            "can_upload": true,
            "can_view_annotations_all": true,
            "can_view_annotations_self": true,
            "can_apply_watermark": true
          },
          "tags": [
            "approved"
          ],
          "lock": {
            "id": "11446498",
            "type": "lock",
            "created_by": {
              "id": "11446498",
              "type": "user",
              "name": "Aaron Levie",
              "login": "ceo@example.com"
            },
            "created_at": "2012-12-12T10:53:43-08:00",
            "expired_at": "2012-12-12T10:53:43-08:00",
            "is_download_prevented": true,
            "app_type": "office_wopiplus"
          },
          "extension": "pdf",
          "is_package": true,
          "expiring_embed_link": {
            "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
            "expires_in": 3600,
            "token_type": "bearer",
            "restricted_to": [
              {
                "scope": "item_download",
                "object": {
                  "id": "12345",
                  "etag": "1",
                  "type": "folder",
                  "sequence_id": "3",
                  "name": "Contracts"
                }
              }
            ],
            "url": "https://cloud.app.box.com/preview/expiring_embed/..."
          },
          "watermark_info": {
            "is_watermarked": true,
            "is_watermark_inherited": false,
            "is_watermarked_by_access_policy": false
          },
          "is_accessible_via_shared_link": true,
          "allowed_invitee_roles": [
            "editor"
          ],
          "is_externally_owned": true,
          "has_collaborations": true,
          "metadata": {
            "enterprise_27335": {
              "marketingCollateral": {
                "$canEdit": true,
                "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
                "$parent": "folder_59449484661",
                "$scope": "enterprise_27335",
                "$template": "marketingCollateral",
                "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
                "$typeVersion": 2,
                "$version": 1
              }
            }
          },
          "expires_at": "2012-12-12T10:53:43-08:00",
          "representations": {
            "entries": [
              {
                "content": {
                  "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
                },
                "info": {
                  "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
                },
                "properties": {
                  "dimensions": "2048x2048",
                  "paged": "true",
                  "thumb": "true"
                },
                "representation": "png",
                "status": {
                  "state": "success"
                }
              }
            ]
          },
          "classification": {
            "name": "Top Secret",
            "definition": "Content that should not be shared outside the company.",
            "color": "#FF0000"
          },
          "uploader_display_name": "Ellis Wiggins",
          "disposition_at": "2012-12-12T10:53:43-08:00",
          "shared_link_permission_options": [
            "can_preview"
          ],
          "is_associated_with_app_item": true,
          "collections": [
            {
              "id": "11446498",
              "type": "collection",
              "name": "Favorites",
              "collection_type": "favorites"
            }
          ],
          "is_download_available": true,
          "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
          "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
          "allowed_shared_link_access_levels": [
            "open"
          ]
        }
      ]
    }
  }
  ```
</Accordion>

## Folder (Base)

The bare basic representation of a folder, the minimal amount of fields returned when using the `fields` query parameter.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `folder`. Available options: `folder`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "folder"
  }
  ```
</Accordion>

## Folder (Full)

A full representation of a folder, as can be returned from any folder API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `folder`. Available options: `folder`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the folder. |
  | `created_at` | `string` | No | The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `modified_at` | `string` | No | The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `description` | `string` | No | The optional description of this folder. |
  | `size` | `integer` | No | The folder size in bytes. Be careful parsing this integer as its value can get very large. |
  | `path_collection` | `object` | No | A list of parent folders for an item. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this folder. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this folder. |
  | `trashed_at` | `string` | No | The time at which this folder was put in the trash. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this folder is expected to be purged from the trash. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this folder was originally created. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this folder was last updated. Can be `null`. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this folder. |
  | `shared_link` | `object` | No | Shared links provide direct, read-only access to files or folder on Box. Shared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users. Can be `null`. |
  | `folder_upload_email` | `object` | No | The `folder_upload_email` parameter is not `null` if one of the following options is **true**: - The **Allow uploads to this folder via email** and the **Only allow email uploads from collaborators in this folder** are [enabled for a folder in the Admin Console](https://support.box.com/hc/en-us/articles/360043697534-Upload-to-Box-Through-Email), and the user has at least **Upload** permissions granted. - The **Allow uploads to this folder via email** setting is enabled for a folder in the Admin Console, and the **Only allow email uploads from collaborators in this folder** setting is deactivated (unchecked). If the conditions are not met, the parameter will have the following value: `folder_upload_email: null`. Can be `null`. |
  | `parent` | [Folder (Mini)](#folder-mini) | No | The optional folder that this folder is located within. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `item_status` | `enum<string>` | No | Defines if this item has been deleted or not. - `active` when the item has is not in the trash - `trashed` when the item has been moved to the trash but not deleted - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |
  | `item_collection` | [Items](#items) | No | A page of the items that are in the folder. This field can only be requested when querying a folder's information, not when querying a folder's items. |
  | `sync_state` | `enum<string>` | No | Specifies whether a folder should be synced to a user's device or not. This is used by Box Sync (discontinued) and is not used by Box Drive. Available options: `synced`, `not_synced`, `partially_synced`. |
  | `has_collaborations` | `boolean` | No | Specifies if this folder has any other collaborators. |
  | `permissions` | `object` | No | The permissions that the authenticated user has for a folder. |
  | `tags` | array of `string` | No | The tags for this item. These tags are shown in the Box web app and mobile apps next to an item. To add or remove a tag, retrieve the item's current tags, modify them, and then update this field. There is a limit of 100 tags per item, and 10,000 unique tags per enterprise. |
  | `can_non_owners_invite` | `boolean` | No | Specifies if users who are not the owner of the folder can invite new collaborators to the folder. |
  | `is_externally_owned` | `boolean` | No | Specifies if this folder is owned by a user outside of the authenticated enterprise. |
  | `metadata` | `object` | No | A list of metadata instances, nested within key-value pairs of their `scope` and `templateKey`. To access the metadata for a file or folder, first use the metadata endpoints to determine the metadata templates available to your enterprise. Then use the `GET /files/:id` or `GET /folder/:id` endpoint with the `fields` query parameter to get the metadata by ID. To request a metadata instance for a particular `scope` and `templateKey` use the following format for the `fields` parameter: `metadata.<scope>.<templateKey>` For example, `?fields=metadata.enterprise_27335.marketingCollateral`. |
  | `is_collaboration_restricted_to_enterprise` | `boolean` | No | Specifies if new invites to this folder are restricted to users within the enterprise. This does not affect existing collaborations. |
  | `allowed_shared_link_access_levels` | array of `enum<string>` | No | The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this folder. The list depends on item policy and user authorization. For some folders, like the root folder, this is always empty as sharing is not allowed at that level. |
  | `allowed_invitee_roles` | array of `enum<string>` | No | A list of the types of roles that user can be invited at when sharing this folder. |
  | `watermark_info` | `object` | No | Details about the watermark applied to this item. |
  | `is_accessible_via_shared_link` | `boolean` | No | Specifies if the folder can be accessed with the direct shared link or a shared link to a parent folder. |
  | `can_non_owners_view_collaborators` | `boolean` | No | Specifies if collaborators who are not owners of this folder are restricted from viewing other collaborations on this folder. It also restricts non-owners from inviting new collaborators. |
  | `classification` | `object` | No | The classification applied to an item. Can be `null`. |
  | `is_associated_with_app_item` | `boolean` | No | This field will return true if the folder or any ancestor of the folder is associated with at least one app item. Note that this will return true even if the context user does not have access to the app item(s) associated with the folder. |
  | `collections` | array of [Collection](/reference/collections-resources#collection) | No | The collections that this folder belongs to. For more information, see the [collections guide](/guides/collections). |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "description": "Legal contracts for the new ACME deal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": {
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "vanity_url": "https://acme.app.box.com/v/my_url/",
      "vanity_name": "my_url",
      "access": "open",
      "effective_access": "company",
      "effective_permission": "can_download",
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "is_password_enabled": true,
      "permissions": {
        "can_download": true,
        "can_preview": true,
        "can_edit": false
      },
      "download_count": 3,
      "preview_count": 3
    },
    "folder_upload_email": {
      "access": "open",
      "email": "upload.Contracts.asd7asd@u.box.com"
    },
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "active",
    "item_collection": {
      "limit": 1000,
      "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
      "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
      "total_count": 5000,
      "offset": 2000,
      "order": [
        {
          "by": "type",
          "direction": "ASC"
        }
      ],
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          },
          "description": "Contract for Q1 renewal",
          "size": 629644,
          "path_collection": {
            "total_count": 1,
            "entries": [
              {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            ]
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "modified_at": "2012-12-12T10:53:43-08:00",
          "trashed_at": "2012-12-12T10:53:43-08:00",
          "purged_at": "2012-12-12T10:53:43-08:00",
          "content_created_at": "2012-12-12T10:53:43-08:00",
          "content_modified_at": "2012-12-12T10:53:43-08:00",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "modified_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "owned_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "shared_link": {
            "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
            "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
            "vanity_url": "https://acme.app.box.com/v/my_url/",
            "vanity_name": "my_url",
            "access": "open",
            "effective_access": "company",
            "effective_permission": "can_download",
            "unshared_at": "2018-04-13T13:53:23-07:00",
            "is_password_enabled": true,
            "permissions": {
              "can_download": true,
              "can_preview": true,
              "can_edit": false
            },
            "download_count": 3,
            "preview_count": 3
          },
          "parent": {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          },
          "item_status": "active",
          "version_number": "1",
          "comment_count": 10,
          "permissions": {
            "can_delete": true,
            "can_download": true,
            "can_invite_collaborator": true,
            "can_rename": true,
            "can_set_share_access": true,
            "can_share": true,
            "can_annotate": true,
            "can_comment": true,
            "can_preview": true,
            "can_upload": true,
            "can_view_annotations_all": true,
            "can_view_annotations_self": true,
            "can_apply_watermark": true
          },
          "tags": [
            "approved"
          ],
          "lock": {
            "id": "11446498",
            "type": "lock",
            "created_by": {
              "id": "11446498",
              "type": "user",
              "name": "Aaron Levie",
              "login": "ceo@example.com"
            },
            "created_at": "2012-12-12T10:53:43-08:00",
            "expired_at": "2012-12-12T10:53:43-08:00",
            "is_download_prevented": true,
            "app_type": "office_wopiplus"
          },
          "extension": "pdf",
          "is_package": true,
          "expiring_embed_link": {
            "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
            "expires_in": 3600,
            "token_type": "bearer",
            "restricted_to": [
              {
                "scope": "item_download",
                "object": {
                  "id": "12345",
                  "etag": "1",
                  "type": "folder",
                  "sequence_id": "3",
                  "name": "Contracts"
                }
              }
            ],
            "url": "https://cloud.app.box.com/preview/expiring_embed/..."
          },
          "watermark_info": {
            "is_watermarked": true,
            "is_watermark_inherited": false,
            "is_watermarked_by_access_policy": false
          },
          "is_accessible_via_shared_link": true,
          "allowed_invitee_roles": [
            "editor"
          ],
          "is_externally_owned": true,
          "has_collaborations": true,
          "metadata": {
            "enterprise_27335": {
              "marketingCollateral": {
                "$canEdit": true,
                "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
                "$parent": "folder_59449484661",
                "$scope": "enterprise_27335",
                "$template": "marketingCollateral",
                "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
                "$typeVersion": 2,
                "$version": 1
              }
            }
          },
          "expires_at": "2012-12-12T10:53:43-08:00",
          "representations": {
            "entries": [
              {
                "content": {
                  "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
                },
                "info": {
                  "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
                },
                "properties": {
                  "dimensions": "2048x2048",
                  "paged": "true",
                  "thumb": "true"
                },
                "representation": "png",
                "status": {
                  "state": "success"
                }
              }
            ]
          },
          "classification": {
            "name": "Top Secret",
            "definition": "Content that should not be shared outside the company.",
            "color": "#FF0000"
          },
          "uploader_display_name": "Ellis Wiggins",
          "disposition_at": "2012-12-12T10:53:43-08:00",
          "shared_link_permission_options": [
            "can_preview"
          ],
          "is_associated_with_app_item": true,
          "collections": [
            {
              "id": "11446498",
              "type": "collection",
              "name": "Favorites",
              "collection_type": "favorites"
            }
          ],
          "is_download_available": true,
          "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
          "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
          "allowed_shared_link_access_levels": [
            "open"
          ]
        }
      ]
    },
    "sync_state": "synced",
    "has_collaborations": true,
    "permissions": {
      "can_delete": true,
      "can_download": true,
      "can_invite_collaborator": true,
      "can_rename": true,
      "can_set_share_access": true,
      "can_share": true,
      "can_upload": true,
      "can_apply_watermark": true
    },
    "tags": [
      "approved"
    ],
    "can_non_owners_invite": true,
    "is_externally_owned": true,
    "metadata": {
      "enterprise_27335": {
        "marketingCollateral": {
          "$canEdit": true,
          "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
          "$parent": "folder_59449484661",
          "$scope": "enterprise_27335",
          "$template": "marketingCollateral",
          "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
          "$typeVersion": 2,
          "$version": 1
        }
      }
    },
    "is_collaboration_restricted_to_enterprise": true,
    "allowed_shared_link_access_levels": [
      "open"
    ],
    "allowed_invitee_roles": [
      "editor"
    ],
    "watermark_info": {
      "is_watermarked": true,
      "is_watermark_inherited": false,
      "is_watermarked_by_access_policy": false
    },
    "is_accessible_via_shared_link": true,
    "can_non_owners_view_collaborators": true,
    "classification": {
      "name": "Top Secret",
      "definition": "Content that should not be shared outside the company.",
      "color": "#FF0000"
    },
    "is_associated_with_app_item": true,
    "collections": [
      {
        "id": "11446498",
        "type": "collection",
        "name": "Favorites",
        "collection_type": "favorites"
      }
    ]
  }
  ```
</Accordion>

## Folder (Mini)

A mini representation of a file version, used when nested under another resource.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `folder`. Available options: `folder`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the folder. |

  ```json Example theme={null}
  {
    "id": "12345",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts"
  }
  ```
</Accordion>

## Items

A list of files, folders, and web links in their mini representation.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of `Item` | No | The items in this collection. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "total_count": 5000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "description": "Contract for Q1 renewal",
        "size": 629644,
        "path_collection": {
          "total_count": 1,
          "entries": [
            {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          ]
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "purged_at": "2012-12-12T10:53:43-08:00",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "vanity_url": "https://acme.app.box.com/v/my_url/",
          "vanity_name": "my_url",
          "access": "open",
          "effective_access": "company",
          "effective_permission": "can_download",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_preview": true,
            "can_edit": false
          },
          "download_count": 3,
          "preview_count": 3
        },
        "parent": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "item_status": "active",
        "version_number": "1",
        "comment_count": 10,
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true,
          "can_apply_watermark": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "expired_at": "2012-12-12T10:53:43-08:00",
          "is_download_prevented": true,
          "app_type": "office_wopiplus"
        },
        "extension": "pdf",
        "is_package": true,
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "token_type": "bearer",
          "restricted_to": [
            {
              "scope": "item_download",
              "object": {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            }
          ],
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "watermark_info": {
          "is_watermarked": true,
          "is_watermark_inherited": false,
          "is_watermarked_by_access_policy": false
        },
        "is_accessible_via_shared_link": true,
        "allowed_invitee_roles": [
          "editor"
        ],
        "is_externally_owned": true,
        "has_collaborations": true,
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "expires_at": "2012-12-12T10:53:43-08:00",
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "classification": {
          "name": "Top Secret",
          "definition": "Content that should not be shared outside the company.",
          "color": "#FF0000"
        },
        "uploader_display_name": "Ellis Wiggins",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "shared_link_permission_options": [
          "can_preview"
        ],
        "is_associated_with_app_item": true,
        "collections": [
          {
            "id": "11446498",
            "type": "collection",
            "name": "Favorites",
            "collection_type": "favorites"
          }
        ],
        "is_download_available": true,
        "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
        "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
        "allowed_shared_link_access_levels": [
          "open"
        ]
      }
    ]
  }
  ```
</Accordion>

## Items

A list of files, folders, and web links in their mini representation.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of `Item` | No | The items in this collection. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "description": "Contract for Q1 renewal",
        "size": 629644,
        "path_collection": {
          "total_count": 1,
          "entries": [
            {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          ]
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "purged_at": "2012-12-12T10:53:43-08:00",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "vanity_url": "https://acme.app.box.com/v/my_url/",
          "vanity_name": "my_url",
          "access": "open",
          "effective_access": "company",
          "effective_permission": "can_download",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_preview": true,
            "can_edit": false
          },
          "download_count": 3,
          "preview_count": 3
        },
        "parent": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "item_status": "active",
        "version_number": "1",
        "comment_count": 10,
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true,
          "can_apply_watermark": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "expired_at": "2012-12-12T10:53:43-08:00",
          "is_download_prevented": true,
          "app_type": "office_wopiplus"
        },
        "extension": "pdf",
        "is_package": true,
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "token_type": "bearer",
          "restricted_to": [
            {
              "scope": "item_download",
              "object": {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            }
          ],
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "watermark_info": {
          "is_watermarked": true,
          "is_watermark_inherited": false,
          "is_watermarked_by_access_policy": false
        },
        "is_accessible_via_shared_link": true,
        "allowed_invitee_roles": [
          "editor"
        ],
        "is_externally_owned": true,
        "has_collaborations": true,
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "expires_at": "2012-12-12T10:53:43-08:00",
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "classification": {
          "name": "Top Secret",
          "definition": "Content that should not be shared outside the company.",
          "color": "#FF0000"
        },
        "uploader_display_name": "Ellis Wiggins",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "shared_link_permission_options": [
          "can_preview"
        ],
        "is_associated_with_app_item": true,
        "collections": [
          {
            "id": "11446498",
            "type": "collection",
            "name": "Favorites",
            "collection_type": "favorites"
          }
        ],
        "is_download_available": true,
        "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
        "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
        "allowed_shared_link_access_levels": [
          "open"
        ]
      }
    ]
  }
  ```
</Accordion>


# List allowed collaboration domains
Source: https://developer.box.com/reference/get-collaboration-whitelist-entries

box-openapi.json GET /collaboration_whitelist_entries
Returns the list domains that have been deemed safe to create collaborations for within the current enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get allowed collaboration domain
Source: https://developer.box.com/reference/get-collaboration-whitelist-entries-id

box-openapi.json GET /collaboration_whitelist_entries/{collaboration_whitelist_entry_id}
Returns a domain that has been deemed safe to create collaborations for within the current enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List users exempt from collaboration domain restrictions
Source: https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets

box-openapi.json GET /collaboration_whitelist_exempt_targets
Returns a list of users who have been exempt from the collaboration domain restrictions.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get user exempt from collaboration domain restrictions
Source: https://developer.box.com/reference/get-collaboration-whitelist-exempt-targets-id

box-openapi.json GET /collaboration_whitelist_exempt_targets/{collaboration_whitelist_exempt_target_id}
Returns a users who has been exempt from the collaboration domain restrictions.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List pending collaborations
Source: https://developer.box.com/reference/get-collaborations

box-openapi.json GET /collaborations
Retrieves all pending collaboration invites for this user.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get collaboration
Source: https://developer.box.com/reference/get-collaborations-id

box-openapi.json GET /collaborations/{collaboration_id}
Retrieves a single collaboration.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all collections
Source: https://developer.box.com/reference/get-collections

box-openapi.json GET /collections
Retrieves all collections for a given user.

Currently, only the `favorites` collection is supported.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get collection by ID
Source: https://developer.box.com/reference/get-collections-id

box-openapi.json GET /collections/{collection_id}
Retrieves a collection by its ID.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List collection items
Source: https://developer.box.com/reference/get-collections-id-items

box-openapi.json GET /collections/{collection_id}/items
Retrieves the files and/or folders contained within this collection.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get comment
Source: https://developer.box.com/reference/get-comments-id

box-openapi.json GET /comments/{comment_id}
Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get device pin
Source: https://developer.box.com/reference/get-device-pinners-id

box-openapi.json GET /device_pinners/{device_pinner_id}
Retrieves information about an individual device pin.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List enterprise device pins
Source: https://developer.box.com/reference/get-enterprises-id-device-pinners

box-openapi.json GET /enterprises/{enterprise_id}/device_pinners
Retrieves all the device pins within an enterprise.

The user must have admin privileges, and the application needs the "manage enterprise" scope to make this call.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List user and enterprise events
Source: https://developer.box.com/reference/get-events

box-openapi.json GET /events
Returns up to a year of past events for a given user or for the entire enterprise.

By default this returns events for the authenticated user. To retrieve events for the entire enterprise, set the `stream_type` to `admin_logs_streaming` for live monitoring of new events, or `admin_logs` for querying across historical events. The user making the API call will need to have admin privileges, and the application will need to have the scope `manage enterprise properties` checked.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get file request
Source: https://developer.box.com/reference/get-file-requests-id

box-openapi.json GET /file_requests/{file_request_id}
Retrieves the information about a file request.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List file version legal holds
Source: https://developer.box.com/reference/get-file-version-legal-holds

box-openapi.json GET /file_version_legal_holds
Get a list of file versions on legal hold for a legal hold assignment.

Due to ongoing re-architecture efforts this API might not return all file versions for this policy ID.

Instead, this API will only return file versions held in the legacy architecture. Two new endpoints will available to request any file versions held in the new architecture.

For file versions held in the new architecture, the `GET /legal_hold_policy_assignments/:id/file_versions_on_hold` API can be used to return all past file versions available for this policy assignment, and the `GET /legal_hold_policy_assignments/:id/files_on_hold` API can be used to return any current (latest) versions of a file under legal hold.

The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID.

Once the re-architecture is completed this API will be deprecated.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get file version legal hold
Source: https://developer.box.com/reference/get-file-version-legal-holds-id

box-openapi.json GET /file_version_legal_holds/{file_version_legal_hold_id}
Retrieves information about the legal hold policies assigned to a file version.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List file version retentions
Source: https://developer.box.com/reference/get-file-version-retentions

box-openapi.json GET /file_version_retentions
Retrieves all file version retentions for the given enterprise.

**Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get retention on file
Source: https://developer.box.com/reference/get-file-version-retentions-id

box-openapi.json GET /file_version_retentions/{file_version_retention_id}
Returns information about a file version retention.

**Note**: File retention API is now **deprecated**. To get information about files and file versions under retention, see [files under retention](/reference/get-retention-policy-assignments-id-files-under-retention) or [file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention) endpoints.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get file information
Source: https://developer.box.com/reference/get-files-id

box-openapi.json GET /files/{file_id}
Retrieves the details about a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List file collaborations
Source: https://developer.box.com/reference/get-files-id-collaborations

box-openapi.json GET /files/{file_id}/collaborations
Retrieves a list of pending and active collaborations for a file. This returns all the users that have access to the file or have been invited to the file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List file comments
Source: https://developer.box.com/reference/get-files-id-comments

box-openapi.json GET /files/{file_id}/comments
Retrieves a list of comments for a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Download file
Source: https://developer.box.com/reference/get-files-id-content

box-openapi.json GET /files/{file_id}/content
Returns the contents of a file in binary format.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get file thumbnail
Source: https://developer.box.com/reference/get-files-id-thumbnail-id

box-openapi.json GET /files/{file_id}/thumbnail.{extension}
Retrieves a thumbnail, or smaller image representation, of a file.

Sizes of `32x32`,`64x64`, `128x128`, and `256x256` can be returned in the `.png` format and sizes of `32x32`, `160x160`, and `320x320` can be returned in the `.jpg` format.

Thumbnails can be generated for the image and video file formats listed [found on our community site][1].

[1]: https://community.box.com/t5/Migrating-and-Previewing-Content/File-Types-and-Fonts-Supported-in-Box-Content-Preview/ta-p/327

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all file versions
Source: https://developer.box.com/reference/get-files-id-versions

box-openapi.json GET /files/{file_id}/versions
Retrieve a list of the past versions for a file.

Versions are only tracked by Box users with premium accounts. To fetch the ID of the current version of a file, use the `GET /file/:id` API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get file version
Source: https://developer.box.com/reference/get-files-id-versions-id

box-openapi.json GET /files/{file_id}/versions/{file_version_id}
Retrieve a specific version of a file.

Versions are only tracked for Box users with premium accounts.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List folder locks
Source: https://developer.box.com/reference/get-folder-locks

box-openapi.json GET /folder_locks
Retrieves folder lock details for a given folder.

You must be authenticated as the owner or co-owner of the folder to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get folder information
Source: https://developer.box.com/reference/get-folders-id

box-openapi.json GET /folders/{folder_id}
Retrieves details for a folder, including the first 100 entries in the folder.

Passing `sort`, `direction`, `offset`, and `limit` parameters in query allows you to manage the list of returned [folder items](/reference/resources/folder--full#param-item-collection).

To fetch more items within the folder, use the [Get items in a folder](/reference/get-folders-id-items) endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List folder collaborations
Source: https://developer.box.com/reference/get-folders-id-collaborations

box-openapi.json GET /folders/{folder_id}/collaborations
Retrieves a list of pending and active collaborations for a folder. This returns all the users that have access to the folder or have been invited to the folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List items in folder
Source: https://developer.box.com/reference/get-folders-id-items

box-openapi.json GET /folders/{folder_id}/items
Retrieves a page of items in a folder. These items can be files, folders, and web links.

To request more information about the folder itself, like its size, use the [Get a folder](/reference/get-folders-id) endpoint instead.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get group membership
Source: https://developer.box.com/reference/get-group-memberships-id

box-openapi.json GET /group_memberships/{group_membership_id}
Retrieves a specific group membership. Only admins of this group or users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List groups for enterprise
Source: https://developer.box.com/reference/get-groups

box-openapi.json GET /groups
Retrieves all of the groups for a given enterprise. The user must have admin permissions to inspect enterprise's groups.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get group
Source: https://developer.box.com/reference/get-groups-id

box-openapi.json GET /groups/{group_id}
Retrieves information about a group. Only members of this group or users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List group collaborations
Source: https://developer.box.com/reference/get-groups-id-collaborations

box-openapi.json GET /groups/{group_id}/collaborations
Retrieves all the collaborations for a group. The user must have admin permissions to inspect enterprise's groups.

Each collaboration object has details on which files or folders the group has access to and with what role.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List members of group
Source: https://developer.box.com/reference/get-groups-id-memberships

box-openapi.json GET /groups/{group_id}/memberships
Retrieves all the members for a group. Only members of this group or users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List Slack integration mappings
Source: https://developer.box.com/reference/get-integration-mappings-slack

box-openapi.json GET /integration_mappings/slack
Lists [Slack integration mappings](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) in a users' enterprise.

You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List Teams integration mappings
Source: https://developer.box.com/reference/get-integration-mappings-teams

box-openapi.json GET /integration_mappings/teams
Lists [Teams integration mappings](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) in a users' enterprise. You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List user's email aliases
Source: https://developer.box.com/reference/get-users-id-email-aliases

box-openapi.json GET /users/{user_id}/email_aliases
Retrieves all email aliases for a user. The collection does not include the primary login for the user.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List user's groups
Source: https://developer.box.com/reference/get-users-id-memberships

box-openapi.json GET /users/{user_id}/memberships
Retrieves all the groups for a user. Only members of this group or users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Groups resources
Source: https://developer.box.com/reference/groups-resources



Groups created in an enterprise.

## Group

A standard representation of a group, as returned from any group API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this object. |
  | `type` | `enum<string>` | Yes | The value will always be `group`. Available options: `group`. |
  | `name` | `string` | No | The name of the group. |
  | `group_type` | `enum<string>` | No | The type of the group. Available options: `managed_group`, `all_users_group`. |
  | `created_at` | `string` | No | When the group object was created. |
  | `modified_at` | `string` | No | When the group object was last modified. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "group",
    "name": "Support",
    "group_type": "managed_group",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Group (Base)

A base representation of a group.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this object. |
  | `type` | `enum<string>` | Yes | The value will always be `group`. Available options: `group`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "group"
  }
  ```
</Accordion>

## Group (Full)

Groups contain a set of users, and can be used in place of users in some operations, such as collaborations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this object. |
  | `type` | `enum<string>` | Yes | The value will always be `group`. Available options: `group`. |
  | `name` | `string` | No | The name of the group. |
  | `group_type` | `enum<string>` | No | The type of the group. Available options: `managed_group`, `all_users_group`. |
  | `created_at` | `string` | No | When the group object was created. |
  | `modified_at` | `string` | No | When the group object was last modified. |
  | `provenance` | `string` | No | Keeps track of which external source this group is coming from (e.g. "Active Directory", "Google Groups", "Facebook Groups"). Setting this will also prevent Box users from editing the group name and its members directly via the Box web application. This is desirable for one-way syncing of groups. |
  | `external_sync_identifier` | `string` | No | An arbitrary identifier that can be used by external group sync tools to link this Box Group to an external group. Example values of this field could be an Active Directory Object ID or a Google Group ID. We recommend you use of this field in order to avoid issues when group names are updated in either Box or external systems. |
  | `description` | `string` | No | Human readable description of the group. |
  | `invitability_level` | `enum<string>` | No | Specifies who can invite the group to collaborate on items. When set to `admins_only` the enterprise admin, co-admins, and the group's admin can invite the group. When set to `admins_and_members` all the admins listed above and group members can invite the group. When set to `all_managed_users` all managed users in the enterprise can invite the group. Available options: `admins_only`, `admins_and_members`, `all_managed_users`. |
  | `member_viewability_level` | `enum<string>` | No | Specifies who can view the members of the group (Get Memberships for Group). - `admins_only` - the enterprise admin, co-admins, group's group admin. - `admins_and_members` - all admins and group members. - `all_managed_users` - all managed users in the enterprise. Available options: `admins_only`, `admins_and_members`, `all_managed_users`. |
  | `permissions` | `object` | No | The permissions that the authenticated user has for a group. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "group",
    "name": "Support",
    "group_type": "managed_group",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "provenance": "Active Directory",
    "external_sync_identifier": "AD:123456",
    "description": "Support Group - as imported from Active Directory",
    "invitability_level": "admins_only",
    "member_viewability_level": "admins_only",
    "permissions": {
      "can_invite_as_collaborator": true
    }
  }
  ```
</Accordion>

## Group (Mini)

Mini representation of a group, including id and name of group.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this object. |
  | `type` | `enum<string>` | Yes | The value will always be `group`. Available options: `group`. |
  | `name` | `string` | No | The name of the group. |
  | `group_type` | `enum<string>` | No | The type of the group. Available options: `managed_group`, `all_users_group`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "group",
    "name": "Support",
    "group_type": "managed_group"
  }
  ```
</Accordion>

## Groups

A list of groups.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of [Group (Full)](#group-full) | No | A list of groups. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "11446498",
        "type": "group",
        "name": "Support",
        "group_type": "managed_group",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "provenance": "Active Directory",
        "external_sync_identifier": "AD:123456",
        "description": "Support Group - as imported from Active Directory",
        "invitability_level": "admins_only",
        "member_viewability_level": "admins_only",
        "permissions": {
          "can_invite_as_collaborator": true
        }
      }
    ]
  }
  ```
</Accordion>


# Integration mappings resources
Source: https://developer.box.com/reference/integration-mappings-resources



Integration Mappings allow the users to manage where content from partner apps is stored in Box.

## Integration mapping Slack

A Slack specific representation of an integration mapping object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | A unique identifier of a folder mapping (part of a composite key together with `integration_type`). |
  | `type` | `enum<string>` | Yes | Mapping type. Available options: `integration_mapping`. |
  | `integration_type` | `enum<string>` | No | Identifies the Box partner app, with which the mapping is associated. Currently only supports Slack. (part of the composite key together with `id`). Available options: `slack`. |
  | `is_manually_created` | `boolean` | No | Identifies whether the mapping has been manually set (as opposed to being automatically created). |
  | `options` | `Integration mapping options for type Slack` | No | |
  | `created_by` | [User (Integration Mappings)](/reference/users-resources#user-integration-mappings) | No | An object representing the user who created the integration mapping. |
  | `modified_by` | [User (Integration Mappings)](/reference/users-resources#user-integration-mappings) | No | The user who last modified the integration mapping. |
  | `partner_item` | `Integration mapping mapped item schema for type Slack` | Yes | Mapped item object for Slack. |
  | `box_item` | [Folder (Mini)](/reference/folders-resources#folder-mini) | Yes | The Box folder, to which the object from the partner app domain (referenced in `partner_item_id`) is mapped. |
  | `created_at` | `string` | No | When the integration mapping object was created. |
  | `modified_at` | `string` | No | When the integration mapping object was last modified. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "integration_mapping",
    "integration_type": "slack",
    "is_manually_created": true,
    "options": {
      "is_access_management_disabled": true
    },
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "partner_item": {
      "id": "C12378991223",
      "type": "channel",
      "slack_org_id": "E1234567"
    },
    "box_item": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Integration mapping Teams

A Microsoft Teams specific representation of an integration mapping object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | A unique identifier of a folder mapping (part of a composite key together with `integration_type`). |
  | `type` | `enum<string>` | Yes | Mapping type. Available options: `integration_mapping`. |
  | `integration_type` | `enum<string>` | No | Identifies the Box partner app, with which the mapping is associated. Supports Slack and Teams. (part of the composite key together with `id`). Available options: `teams`. |
  | `is_overridden_by_manual_mapping` | `boolean` | No | Identifies whether the mapping has been manually set by the team owner from UI for channels (as opposed to being automatically created). |
  | `partner_item` | `Integration mapping mapped item schema for type Teams` | Yes | Mapped item object for Teams. |
  | `box_item` | `Folder reference` | Yes | The Box folder, to which the object from the partner app domain (referenced in `partner_item_id`) is mapped. |
  | `created_at` | `string` | No | When the integration mapping object was created. |
  | `modified_at` | `string` | No | When the integration mapping object was last modified. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "integration_mapping",
    "integration_type": "teams",
    "is_overridden_by_manual_mapping": true,
    "partner_item": {
      "id": "19%3ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2",
      "type": "channel",
      "tenant_id": "E1234567",
      "team_id": "hjgjgjg-bhhj-564a-b643-hghgj685u"
    },
    "box_item": {
      "type": "folder",
      "id": "42037322"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Integration mappings Slack

A list of integration mapping objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `entries` | array of [Integration mapping Slack](#integration-mapping-slack) | No | A list of integration mappings. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "entries": [
      {
        "id": "12345",
        "type": "integration_mapping",
        "integration_type": "slack",
        "is_manually_created": true,
        "options": {
          "is_access_management_disabled": true
        },
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "partner_item": {
          "id": "C12378991223",
          "type": "channel",
          "slack_org_id": "E1234567"
        },
        "box_item": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>

## Integration mappings Teams

A list of integration mapping objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Integration mapping Teams](#integration-mapping-teams) | No | A list of integration mappings. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "integration_mapping",
        "integration_type": "teams",
        "is_overridden_by_manual_mapping": true,
        "partner_item": {
          "id": "19%3ABCD-Avgfggkggyftdtfgghjhkhkhh%40thread:tacv2",
          "type": "channel",
          "tenant_id": "E1234567",
          "team_id": "hjgjgjg-bhhj-564a-b643-hghgj685u"
        },
        "box_item": {
          "type": "folder",
          "id": "42037322"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# Group memberships resources
Source: https://developer.box.com/reference/memberships-resources



Group memberships signify that a user is a part of the group.

## Group membership

Membership is used to signify that a user is part of a group.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this group membership. |
  | `type` | `enum<string>` | No | The value will always be `group_membership`. Available options: `group_membership`. |
  | `user` | [User (Mini)](/reference/users-resources#user-mini) | No | The user that the membership applies to. |
  | `group` | [Group (Mini)](/reference/groups-resources#group-mini) | No | The group that the membership applies to. |
  | `role` | `enum<string>` | No | The role of the user in the group. Available options: `member`, `admin`. |
  | `created_at` | `string` | No | The time this membership was created. |
  | `modified_at` | `string` | No | The time this membership was last modified. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "group_membership",
    "user": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "group": {
      "id": "11446498",
      "type": "group",
      "name": "Support",
      "group_type": "managed_group"
    },
    "role": "member",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Group memberships

A list of group memberships.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of [Group membership](#group-membership) | No | A list of group memberships. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "11446498",
        "type": "group_membership",
        "user": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "group": {
          "id": "11446498",
          "type": "group",
          "name": "Support",
          "group_type": "managed_group"
        },
        "role": "member",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# Get events long poll endpoint
Source: https://developer.box.com/reference/options-events

/box-openapi.json OPTIONS /events

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add domain to list of allowed collaboration domains
Source: https://developer.box.com/reference/post-collaboration-whitelist-entries

box-openapi.json POST /collaboration_whitelist_entries
Creates a new entry in the list of allowed domains to allow collaboration for.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create user exemption from collaboration domain restrictions
Source: https://developer.box.com/reference/post-collaboration-whitelist-exempt-targets

box-openapi.json POST /collaboration_whitelist_exempt_targets
Exempts a user from the restrictions set out by the allowed list of domains for collaborations.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create collaboration
Source: https://developer.box.com/reference/post-collaborations

box-openapi.json POST /collaborations
Adds a collaboration for a single user or a single group to a file or folder.

Collaborations can be created using email address, user IDs, or a group IDs.

If a collaboration is being created with a group, access to this endpoint is dependent on the group's ability to be invited.

If collaboration is in `pending` status, field `name` is redacted when:

- a collaboration was created using `user_id`,
- a collaboration was created using `login`.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create comment
Source: https://developer.box.com/reference/post-comments

box-openapi.json POST /comments
Adds a comment by the user to a specific file, or as a reply to an other comment.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Copy file request
Source: https://developer.box.com/reference/post-file-requests-id-copy

box-openapi.json POST /file_requests/{file_request_id}/copy
Copies an existing file request that is already present on one folder, and applies it to another folder.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Copy file
Source: https://developer.box.com/reference/post-files-id-copy

box-openapi.json POST /files/{file_id}/copy
Creates a copy of a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Promote file version
Source: https://developer.box.com/reference/post-files-id-versions-current

box-openapi.json POST /files/{file_id}/versions/current
Promote a specific version of a file.

If previous versions exist, this method can be used to promote one of the older versions to the top of the version history.

This creates a new copy of the old version and puts it at the top of the versions history. The file will have the exact same contents as the older version, with the same hash digest, `etag`, and name as the original.

Other properties such as comments do not get updated to their former values.

Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create folder lock
Source: https://developer.box.com/reference/post-folder-locks

box-openapi.json POST /folder_locks
Creates a folder lock on a folder, preventing it from being moved and/or deleted.

You must be authenticated as the owner or co-owner of the folder to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create folder
Source: https://developer.box.com/reference/post-folders

box-openapi.json POST /folders
Creates a new empty folder within the specified parent folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Copy folder
Source: https://developer.box.com/reference/post-folders-id-copy

box-openapi.json POST /folders/{folder_id}/copy
Creates a copy of a folder within a destination folder.

The original folder will not be changed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add classification to folder
Source: https://developer.box.com/reference/post-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json POST /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Adds a classification to a folder by specifying the label of the classification to add.

This API can also be called by including the enterprise ID in the URL explicitly, for example `/folders/:id/enterprise_12345/securityClassification-6VMVochwUWo`.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add user to group
Source: https://developer.box.com/reference/post-group-memberships

box-openapi.json POST /group_memberships
Creates a group membership. Only users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create group
Source: https://developer.box.com/reference/post-groups

box-openapi.json POST /groups
Creates a new group of users in an enterprise. Only users with admin permissions can create new groups.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create Slack integration mapping
Source: https://developer.box.com/reference/post-integration-mappings-slack

box-openapi.json POST /integration_mappings/slack
Creates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack) by mapping a Slack channel to a Box item.

You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create Teams integration mapping
Source: https://developer.box.com/reference/post-integration-mappings-teams

box-openapi.json POST /integration_mappings/teams
Creates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams) by mapping a Teams channel to a Box item. You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create email alias
Source: https://developer.box.com/reference/post-users-id-email-aliases

box-openapi.json POST /users/{user_id}/email_aliases
Adds a new email alias to a user account..

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update collaboration
Source: https://developer.box.com/reference/put-collaborations-id

box-openapi.json PUT /collaborations/{collaboration_id}
Updates a collaboration. Can be used to change the owner of an item, or to accept collaboration invites. In case of accepting collaboration invite, role is not required.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update comment
Source: https://developer.box.com/reference/put-comments-id

box-openapi.json PUT /comments/{comment_id}
Update the message of a comment.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update file request
Source: https://developer.box.com/reference/put-file-requests-id

box-openapi.json PUT /file_requests/{file_request_id}
Updates a file request. This can be used to activate or deactivate a file request.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update file
Source: https://developer.box.com/reference/put-files-id

box-openapi.json PUT /files/{file_id}
Updates a file. This can be used to rename or move a file, create a shared link, or lock a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Restore file version
Source: https://developer.box.com/reference/put-files-id-versions-id

box-openapi.json PUT /files/{file_id}/versions/{file_version_id}
Restores a specific version of a file after it was deleted. Don't use this endpoint to restore Box Notes, as it works with file formats such as PDF, DOC, PPTX or similar.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update folder
Source: https://developer.box.com/reference/put-folders-id

box-openapi.json PUT /folders/{folder_id}
Updates a folder. This can be also be used to move the folder, create shared links, update collaborations, and more.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update classification on folder
Source: https://developer.box.com/reference/put-folders-id-metadata-enterprise-securityClassification-6VMVochwUWo

box-openapi.json PUT /folders/{folder_id}/metadata/enterprise/securityClassification-6VMVochwUWo
Updates a classification on a folder.

The classification can only be updated if a classification has already been applied to the folder before. When editing classifications, only values are defined for the enterprise will be accepted.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update group membership
Source: https://developer.box.com/reference/put-group-memberships-id

box-openapi.json PUT /group_memberships/{group_membership_id}
Updates a user's group membership. Only admins of this group or users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update group
Source: https://developer.box.com/reference/put-groups-id

box-openapi.json PUT /groups/{group_id}
Updates a specific group. Only admins of this group or users with admin-level permissions will be able to use this API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update Slack integration mapping
Source: https://developer.box.com/reference/put-integration-mappings-slack-id

box-openapi.json PUT /integration_mappings/slack/{integration_mapping_id}
Updates a [Slack integration mapping](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack). Supports updating the Box folder ID and options.

You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update Teams integration mapping
Source: https://developer.box.com/reference/put-integration-mappings-teams-id

box-openapi.json PUT /integration_mappings/teams/{integration_mapping_id}
Updates a [Teams integration mapping](https://support.box.com/hc/en-us/articles/360044681474-Using-Box-for-Teams). Supports updating the Box folder ID and options. You need Admin or Co-Admin role to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Collaborations resources
Source: https://developer.box.com/reference/user-collaborations-resources



Collaborations define access permissions for users and groups to files and folders, similar to access control lists.

## Collaboration

Collaborations define access permissions for users and groups to files and folders, similar to access control lists. A collaboration object grants a user or group access to a file or folder with permissions defined by a specific role.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this collaboration. |
  | `type` | `enum<string>` | Yes | The value will always be `collaboration`. Available options: `collaboration`. |
  | `item` | `Collaboration item` | No | The file or folder to which access is granted. The field is `null` when the collaboration `status` is `pending` or the collaboration is created on an app item (see `app_item` field). Can be `null`. |
  | `app_item` | [App item](/reference/app-item-associations-resources#app-item) | No | An `app_item` to which access is granted. The field is `null` when the collaboration is created on an item (see `item` field), or the `app_item` is inaccessible. The role cascades to all items associated with the `app_item`. Can be `null`. |
  | `accessible_by` | `Collaboration access grantee` | No | |
  | `invite_email` | `string` | No | The email address used to invite an unregistered collaborator, if they are not a registered user. Can be `null`. |
  | `role` | `enum<string>` | No | The level of access granted. Available options: `editor`, `viewer`, `previewer`, `uploader`, `previewer uploader`, `viewer uploader`, `co-owner`, `owner`. |
  | `expires_at` | `string` | No | When the collaboration will expire, or `null` if no expiration date is set. Can be `null`. |
  | `is_access_only` | `boolean` | No | If set to `true`, collaborators have access to shared items, but such items won't be visible in the All Files list. Additionally, collaborators won't see the path to the root folder for the shared item. |
  | `status` | `enum<string>` | No | The status of the collaboration invitation. If the status is `pending`, `name` returns an empty string. Available options: `accepted`, `pending`, `rejected`. |
  | `acknowledged_at` | `string` | No | When the `status` of the collaboration object changed to `accepted` or `rejected`. |
  | `created_by` | [User (Collaborations)](/reference/users-resources#user-collaborations) | No | The user who created the collaboration object. |
  | `created_at` | `string` | No | When the collaboration object was created. |
  | `modified_at` | `string` | No | When the collaboration object was last modified. |
  | `acceptance_requirements_status` | `object` | No | |

  ```json Example theme={null}
  {
    "id": "12345678",
    "type": "collaboration",
    "item": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    },
    "app_item": {
      "id": "12345678",
      "type": "app_item",
      "application_type": "hubs"
    },
    "accessible_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com",
      "is_active": true
    },
    "invite_email": "john@example.com",
    "role": "editor",
    "expires_at": "2012-12-26T10:53:43-08:00",
    "is_access_only": true,
    "status": "accepted",
    "acknowledged_at": "2012-12-12T10:55:20-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com",
      "is_active": true
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "acceptance_requirements_status": {
      "terms_of_service_requirement": {
        "is_accepted": true,
        "terms_of_service": {
          "id": "11446498",
          "type": "terms_of_service"
        }
      },
      "strong_password_requirement": {
        "enterprise_has_strong_password_required_for_external_users": true,
        "user_has_strong_password": true
      },
      "two_factor_authentication_requirement": {
        "enterprise_has_two_factor_auth_enabled": true,
        "user_has_two_factor_authentication_enabled": true
      }
    }
  }
  ```
</Accordion>

## Collaborations

A list of collaborations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Collaboration](#collaboration) | No | A list of collaborations. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345678",
        "type": "collaboration",
        "item": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "app_item": {
          "id": "12345678",
          "type": "app_item",
          "application_type": "hubs"
        },
        "accessible_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com",
          "is_active": true
        },
        "invite_email": "john@example.com",
        "role": "editor",
        "expires_at": "2012-12-26T10:53:43-08:00",
        "is_access_only": true,
        "status": "accepted",
        "acknowledged_at": "2012-12-12T10:55:20-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com",
          "is_active": true
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "acceptance_requirements_status": {
          "terms_of_service_requirement": {
            "is_accepted": true,
            "terms_of_service": {
              "id": "11446498",
              "type": "terms_of_service"
            }
          },
          "strong_password_requirement": {
            "enterprise_has_strong_password_required_for_external_users": true,
            "user_has_strong_password": true
          },
          "two_factor_authentication_requirement": {
            "enterprise_has_two_factor_auth_enabled": true,
            "user_has_two_factor_authentication_enabled": true
          }
        }
      }
    ]
  }
  ```
</Accordion>

## Collaborations

A list of collaborations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of [Collaboration](#collaboration) | No | A list of collaborations. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "entries": [
      {
        "id": "12345678",
        "type": "collaboration",
        "item": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "app_item": {
          "id": "12345678",
          "type": "app_item",
          "application_type": "hubs"
        },
        "accessible_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com",
          "is_active": true
        },
        "invite_email": "john@example.com",
        "role": "editor",
        "expires_at": "2012-12-26T10:53:43-08:00",
        "is_access_only": true,
        "status": "accepted",
        "acknowledged_at": "2012-12-12T10:55:20-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com",
          "is_active": true
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "acceptance_requirements_status": {
          "terms_of_service_requirement": {
            "is_accepted": true,
            "terms_of_service": {
              "id": "11446498",
              "type": "terms_of_service"
            }
          },
          "strong_password_requirement": {
            "enterprise_has_strong_password_required_for_external_users": true,
            "user_has_strong_password": true
          },
          "two_factor_authentication_requirement": {
            "enterprise_has_two_factor_auth_enabled": true,
            "user_has_two_factor_authentication_enabled": true
          }
        }
      }
    ]
  }
  ```
</Accordion>


# Remove metadata instance from file
Source: https://developer.box.com/reference/delete-files-id-metadata-id-id

box-openapi.json DELETE /files/{file_id}/metadata/{scope}/{template_key}
Deletes a piece of file metadata.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove metadata instance from folder
Source: https://developer.box.com/reference/delete-folders-id-metadata-id-id

box-openapi.json DELETE /folders/{folder_id}/metadata/{scope}/{template_key}
Deletes a piece of folder metadata.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove legal hold policy
Source: https://developer.box.com/reference/delete-legal-hold-policies-id

box-openapi.json DELETE /legal_hold_policies/{legal_hold_policy_id}
Delete an existing legal hold policy.

This is an asynchronous process. The policy will not be fully deleted yet when the response returns.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Unassign legal hold policy
Source: https://developer.box.com/reference/delete-legal-hold-policy-assignments-id

box-openapi.json DELETE /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}
Remove a legal hold from an item.

This is an asynchronous process. The policy will not be fully removed yet when the response returns.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove metadata cascade policy
Source: https://developer.box.com/reference/delete-metadata-cascade-policies-id

box-openapi.json DELETE /metadata_cascade_policies/{metadata_cascade_policy_id}
Deletes a metadata cascade policy.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove metadata taxonomy
Source: https://developer.box.com/reference/delete-metadata-taxonomies-id-id

box-openapi.json DELETE /metadata_taxonomies/{namespace}/{taxonomy_key}
Delete a metadata taxonomy. This deletion is permanent and cannot be reverted.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove metadata taxonomy node
Source: https://developer.box.com/reference/delete-metadata-taxonomies-id-id-nodes-id

box-openapi.json DELETE /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}
Delete a metadata taxonomy node. This deletion is permanent and cannot be reverted. Only metadata taxonomy nodes without any children can be deleted.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove metadata template
Source: https://developer.box.com/reference/delete-metadata-templates-id-id-schema

box-openapi.json DELETE /metadata_templates/{scope}/{template_key}/schema
Delete a metadata template and its instances. This deletion is permanent and can not be reversed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete retention policy
Source: https://developer.box.com/reference/delete-retention-policies-id

box-openapi.json DELETE /retention_policies/{retention_policy_id}
Permanently deletes a retention policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove retention policy assignment
Source: https://developer.box.com/reference/delete-retention-policy-assignments-id

box-openapi.json DELETE /retention_policy_assignments/{retention_policy_assignment_id}
Removes a retention policy assignment applied to content.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Metadata instances (Files) resources
Source: https://developer.box.com/reference/file-metadata-resources



A metadata instance describes the relation between a template and a file, including the values that are assigned for every field.

## Metadata instance

An instance of a metadata template, which has been applied to a file or folder.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `$parent` | `string` | No | The identifier of the item that this metadata instance has been attached to. This combines the `type` and the `id` of the parent in the form `{type}_{id}`. |
  | `$template` | `string` | No | The name of the template. |
  | `$scope` | `string` | No | An ID for the scope in which this template has been applied. This will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box. |
  | `$version` | `integer` | No | The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified. |

  ```json Example theme={null}
  {
    "$parent": "folder_59449484661,",
    "$template": "marketingCollateral",
    "$scope": "enterprise_27335",
    "$version": 1
  }
  ```
</Accordion>

## Metadata instance (Base)

The base representation of a metadata instance.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `$parent` | `string` | No | The identifier of the item that this metadata instance has been attached to. This combines the `type` and the `id` of the parent in the form `{type}_{id}`. |
  | `$template` | `string` | No | The name of the template. |
  | `$scope` | `string` | No | An ID for the scope in which this template has been applied. This will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box. |
  | `$version` | `integer` | No | The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified. |

  ```json Example theme={null}
  {
    "$parent": "folder_59449484661,",
    "$template": "marketingCollateral",
    "$scope": "enterprise_27335",
    "$version": 1
  }
  ```
</Accordion>

## Metadata instance (Full)

An instance of a metadata template, which has been applied to a file or folder.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `$parent` | `string` | No | The identifier of the item that this metadata instance has been attached to. This combines the `type` and the `id` of the parent in the form `{type}_{id}`. |
  | `$template` | `string` | No | The name of the template. |
  | `$scope` | `string` | No | An ID for the scope in which this template has been applied. This will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box. |
  | `$version` | `integer` | No | The version of the metadata instance. This version starts at 0 and increases every time a user-defined property is modified. |
  | `$canEdit` | `boolean` | No | Whether the user can edit this metadata instance. |
  | `$id` | `string` | No | A UUID to identify the metadata instance. |
  | `$type` | `string` | No | A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application. |
  | `$typeVersion` | `integer` | No | The last-known version of the template of the object. This is an internal system property and should not be used by a client application. |

  ```json Example theme={null}
  {
    "$parent": "folder_59449484661,",
    "$template": "marketingCollateral",
    "$scope": "enterprise_27335",
    "$version": 1,
    "$canEdit": true,
    "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
    "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
    "$typeVersion": 2
  }
  ```
</Accordion>

## Metadata instances

A list of metadata instances that have been applied to a file or folder.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Metadata instance](#metadata-instance) | No | A list of metadata instances, as applied to this file or folder. |
  | `limit` | `integer` | No | The limit that was used for this page of results. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "$parent": "folder_59449484661,",
        "$template": "marketingCollateral",
        "$scope": "enterprise_27335",
        "$version": 1
      }
    ],
    "limit": 100
  }
  ```
</Accordion>


# Get shared link for file
Source: https://developer.box.com/reference/get-files-id--get-shared-link

box-openapi.json GET /files/{file_id}#get_shared_link
Gets the information for a shared link on a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List metadata instances on file
Source: https://developer.box.com/reference/get-files-id-metadata

box-openapi.json GET /files/{file_id}/metadata
Retrieves all metadata for a given file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata instance on file
Source: https://developer.box.com/reference/get-files-id-metadata-id-id

box-openapi.json GET /files/{file_id}/metadata/{scope}/{template_key}
Retrieves the instance of a metadata template that has been applied to a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get shared link for folder
Source: https://developer.box.com/reference/get-folders-id--get-shared-link

box-openapi.json GET /folders/{folder_id}#get_shared_link
Gets the information for a shared link on a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List metadata instances on folder
Source: https://developer.box.com/reference/get-folders-id-metadata

box-openapi.json GET /folders/{folder_id}/metadata
Retrieves all metadata for a given folder. This can not be used on the root folder with ID `0`.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata instance on folder
Source: https://developer.box.com/reference/get-folders-id-metadata-id-id

box-openapi.json GET /folders/{folder_id}/metadata/{scope}/{template_key}
Retrieves the instance of a metadata template that has been applied to a folder. This can not be used on the root folder with ID `0`.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get user invite status
Source: https://developer.box.com/reference/get-invites-id

box-openapi.json GET /invites/{invite_id}
Returns the status of a user invite.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all legal hold policies
Source: https://developer.box.com/reference/get-legal-hold-policies

box-openapi.json GET /legal_hold_policies
Retrieves a list of legal hold policies that belong to an enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get legal hold policy
Source: https://developer.box.com/reference/get-legal-hold-policies-id

box-openapi.json GET /legal_hold_policies/{legal_hold_policy_id}
Retrieve a legal hold policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List legal hold policy assignments
Source: https://developer.box.com/reference/get-legal-hold-policy-assignments

box-openapi.json GET /legal_hold_policy_assignments
Retrieves a list of items a legal hold policy has been assigned to.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get legal hold policy assignment
Source: https://developer.box.com/reference/get-legal-hold-policy-assignments-id

box-openapi.json GET /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}
Retrieve a legal hold policy assignment.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List previous file versions for legal hold policy assignment
Source: https://developer.box.com/reference/get-legal-hold-policy-assignments-id-file-versions-on-hold

box-openapi.json GET /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/file_versions_on_hold
Get a list of previous file versions for a legal hold assignment.

In some cases you may only need the latest file versions instead. In these cases, use the `GET  /legal_hold_policy_assignments/:id/files_on_hold` API instead to return any current (latest) versions of a file for this legal hold policy assignment.

Due to ongoing re-architecture efforts this API might not return all files held for this policy ID. Instead, this API will only return past file versions held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture.

This endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub.

The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List files with current file versions for legal hold policy assignment
Source: https://developer.box.com/reference/get-legal-hold-policy-assignments-id-files-on-hold

box-openapi.json GET /legal_hold_policy_assignments/{legal_hold_policy_assignment_id}/files_on_hold
Get a list of files with current file versions for a legal hold assignment.

In some cases you may want to get previous file versions instead. In these cases, use the `GET  /legal_hold_policy_assignments/:id/file_versions_on_hold` API instead to return any previous versions of a file for this legal hold policy assignment.

Due to ongoing re-architecture efforts this API might not return all file versions held for this policy ID. Instead, this API will only return the latest file version held in the newly developed architecture. The `GET /file_version_legal_holds` API can be used to fetch current and past versions of files held within the legacy architecture.

This endpoint does not support returning any content that is on hold due to a Custodian collaborating on a Hub.

The `GET /legal_hold_policy_assignments?policy_id={id}` API can be used to find a list of policy assignments for a given policy ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List metadata cascade policies
Source: https://developer.box.com/reference/get-metadata-cascade-policies

box-openapi.json GET /metadata_cascade_policies
Retrieves a list of all the metadata cascade policies that are applied to a given folder. This can not be used on the root folder with ID `0`.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata cascade policy
Source: https://developer.box.com/reference/get-metadata-cascade-policies-id

box-openapi.json GET /metadata_cascade_policies/{metadata_cascade_policy_id}
Retrieve a specific metadata cascade policy assigned to a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata taxonomies for namespace
Source: https://developer.box.com/reference/get-metadata-taxonomies-id

box-openapi.json GET /metadata_taxonomies/{namespace}
Used to retrieve all metadata taxonomies in a namespace.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata taxonomy by taxonomy key
Source: https://developer.box.com/reference/get-metadata-taxonomies-id-id

box-openapi.json GET /metadata_taxonomies/{namespace}/{taxonomy_key}
Used to retrieve a metadata taxonomy by taxonomy key.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List metadata taxonomy nodes
Source: https://developer.box.com/reference/get-metadata-taxonomies-id-id-nodes

box-openapi.json GET /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes
Used to retrieve metadata taxonomy nodes based on the parameters specified. Results are sorted in lexicographic order unless a `query` parameter is passed. With a `query` parameter specified, results are sorted in order of relevance.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata taxonomy node by ID
Source: https://developer.box.com/reference/get-metadata-taxonomies-id-id-nodes-id

box-openapi.json GET /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}
Retrieves a metadata taxonomy node by its identifier.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Find metadata template by instance ID
Source: https://developer.box.com/reference/get-metadata-templates

box-openapi.json GET /metadata_templates
Finds a metadata template by searching for the ID of an instance of the template.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all metadata templates for enterprise
Source: https://developer.box.com/reference/get-metadata-templates-enterprise

box-openapi.json GET /metadata_templates/enterprise
Used to retrieve all metadata templates created to be used specifically within the user's enterprise.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all global metadata templates
Source: https://developer.box.com/reference/get-metadata-templates-global

box-openapi.json GET /metadata_templates/global
Used to retrieve all generic, global metadata templates available to all enterprises using Box.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata template by ID
Source: https://developer.box.com/reference/get-metadata-templates-id

box-openapi.json GET /metadata_templates/{template_id}
Retrieves a metadata template by its ID.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List metadata template's options for taxonomy field
Source: https://developer.box.com/reference/get-metadata-templates-id-id-fields-id-options

box-openapi.json GET /metadata_templates/{namespace}/{template_key}/fields/{field_key}/options
Used to retrieve metadata taxonomy nodes which are available for the taxonomy field based on its configuration and the parameters specified. Results are sorted in lexicographic order unless a `query` parameter is passed. With a `query` parameter specified, results are sorted in order of relevance.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get metadata template by name
Source: https://developer.box.com/reference/get-metadata-templates-id-id-schema

box-openapi.json GET /metadata_templates/{scope}/{template_key}/schema
Retrieves a metadata template by its `scope` and `templateKey` values.

To find the `scope` and `templateKey` for a template, list all templates for an enterprise or globally, or list all templates applied to a file or folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List recently accessed items
Source: https://developer.box.com/reference/get-recent-items

box-openapi.json GET /recent_items
Returns information about the recent items accessed by a user, either in the last 90 days or up to the last 1000 items accessed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List retention policies
Source: https://developer.box.com/reference/get-retention-policies

box-openapi.json GET /retention_policies
Retrieves all of the retention policies for an enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get retention policy
Source: https://developer.box.com/reference/get-retention-policies-id

box-openapi.json GET /retention_policies/{retention_policy_id}
Retrieves a retention policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List retention policy assignments
Source: https://developer.box.com/reference/get-retention-policies-id-assignments

box-openapi.json GET /retention_policies/{retention_policy_id}/assignments
Returns a list of all retention policy assignments associated with a specified retention policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get retention policy assignment
Source: https://developer.box.com/reference/get-retention-policy-assignments-id

box-openapi.json GET /retention_policy_assignments/{retention_policy_assignment_id}
Retrieves a retention policy assignment.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get file versions under retention
Source: https://developer.box.com/reference/get-retention-policy-assignments-id-file-versions-under-retention

box-openapi.json GET /retention_policy_assignments/{retention_policy_assignment_id}/file_versions_under_retention
Returns a list of file versions under retention for a retention policy assignment.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get files under retention
Source: https://developer.box.com/reference/get-retention-policy-assignments-id-files-under-retention

box-openapi.json GET /retention_policy_assignments/{retention_policy_assignment_id}/files_under_retention
Returns a list of files under retention for a retention policy assignment.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Search for content
Source: https://developer.box.com/reference/get-search

box-openapi.json GET /search
Searches for files, folders, web links, and shared files across the users content or across the entire enterprise.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Find file for shared link
Source: https://developer.box.com/reference/get-shared-items

box-openapi.json GET /shared_items
Returns the file represented by a shared link.

A shared file can be represented by a shared link, which can originate within the current enterprise or within another.

This endpoint allows an application to retrieve information about a shared file when only given a shared link.

The `shared_link_permission_options` array field can be returned by requesting it in the `fields` query parameter.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Find app item for shared link
Source: https://developer.box.com/reference/get-shared-items--app-items

box-openapi.json GET /shared_items#app_items
Returns the app item represented by a shared link.

The link can originate from the current enterprise or another.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Find folder for shared link
Source: https://developer.box.com/reference/get-shared-items--folders

box-openapi.json GET /shared_items#folders
Return the folder represented by a shared link.

A shared folder can be represented by a shared link, which can originate within the current enterprise or within another.

This endpoint allows an application to retrieve information about a shared folder when only given a shared link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Find web link for shared link
Source: https://developer.box.com/reference/get-shared-items--web-links

box-openapi.json GET /shared_items#web_links
Returns the web link represented by a shared link.

A shared web link can be represented by a shared link, which can originate within the current enterprise or within another.

This endpoint allows an application to retrieve information about a shared web link when only given a shared link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List shield information barrier reports
Source: https://developer.box.com/reference/get-shield-information-barrier-reports

box-openapi.json GET /shield_information_barrier_reports
Lists shield information barrier reports.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get shield information barrier report by ID
Source: https://developer.box.com/reference/get-shield-information-barrier-reports-id

box-openapi.json GET /shield_information_barrier_reports/{shield_information_barrier_report_id}
Retrieves a shield information barrier report by its ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get shared link for web link
Source: https://developer.box.com/reference/get-web-links-id--get-shared-link

box-openapi.json GET /web_links/{web_link_id}#get_shared_link
Gets the information for a shared link on a web link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Invites resources
Source: https://developer.box.com/reference/invites-resources



Invites are used to invite the user to an enterprise.

## Invite

An invite for a user to an enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this invite. |
  | `type` | `enum<string>` | Yes | The value will always be `invite`. Available options: `invite`. |
  | `invited_to` | `object` | No | A representation of a Box enterprise. |
  | `actionable_by` | [User (Mini)](/reference/users-resources#user-mini) | No | |
  | `invited_by` | [User (Mini)](/reference/users-resources#user-mini) | No | |
  | `status` | `string` | No | The status of the invite. |
  | `created_at` | `string` | No | When the invite was created. |
  | `modified_at` | `string` | No | When the invite was modified. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "invite",
    "invited_to": {
      "id": "11446498",
      "type": "enterprise",
      "name": "Acme Inc."
    },
    "actionable_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "invited_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "status": "pending",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>


# Legal hold policies resources
Source: https://developer.box.com/reference/legal-hold-policies-resources



A legal hold is a process that an enterprise can use to preserve all forms of potentially relevant information when litigation is pending or reasonably anticipated.

## Legal hold policies

A list of legal hold policies.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Legal hold policy](#legal-hold-policy) | No | A list of legal hold policies. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "legal_hold_policy",
        "policy_name": "Policy 4",
        "description": "Postman created policy",
        "status": "active",
        "assignment_counts": {
          "user": 1,
          "folder": 2,
          "file": 3,
          "file_version": 4,
          "ownership": 5,
          "interactions": 6
        },
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "deleted_at": "2012-12-12T10:53:43-08:00",
        "filter_started_at": "2012-12-12T10:53:43-08:00",
        "filter_ended_at": "2012-12-12T10:53:43-08:00",
        "release_notes": "Example"
      }
    ]
  }
  ```
</Accordion>

## Legal hold policy

Legal Hold Policy information describes the basic characteristics of the Policy, such as name, description, and filter dates.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this legal hold policy. |
  | `type` | `enum<string>` | Yes | The value will always be `legal_hold_policy`. Available options: `legal_hold_policy`. |
  | `policy_name` | `string` | No | Name of the legal hold policy. |
  | `description` | `string` | No | Description of the legal hold policy. Optional property with a 500 character limit. |
  | `status` | `enum<string>` | No | Possible values: - 'active' - the policy is not in a transition state. - 'applying' - that the policy is in the process of being applied. - 'releasing' - that the process is in the process of being released. - 'released' - the policy is no longer active. Available options: `active`, `applying`, `releasing`, `released`. |
  | `assignment_counts` | `object` | No | Counts of assignments within a legal hold policy by item type. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created the legal hold policy object. |
  | `created_at` | `string` | No | When the legal hold policy object was created. |
  | `modified_at` | `string` | No | When the legal hold policy object was modified. Does not update when assignments are added or removed. |
  | `deleted_at` | `string` | No | When the policy release request was sent. (Because it can take time for a policy to fully delete, this isn't quite the same time that the policy is fully deleted). If `null`, the policy was not deleted. |
  | `filter_started_at` | `string` | No | User-specified, optional date filter applies to Custodian assignments only. |
  | `filter_ended_at` | `string` | No | User-specified, optional date filter applies to Custodian assignments only. |
  | `release_notes` | `string` | No | Optional notes about why the policy was created. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "legal_hold_policy",
    "policy_name": "Policy 4",
    "description": "Postman created policy",
    "status": "active",
    "assignment_counts": {
      "user": 1,
      "folder": 2,
      "file": 3,
      "file_version": 4,
      "ownership": 5,
      "interactions": 6
    },
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "deleted_at": "2012-12-12T10:53:43-08:00",
    "filter_started_at": "2012-12-12T10:53:43-08:00",
    "filter_ended_at": "2012-12-12T10:53:43-08:00",
    "release_notes": "Example"
  }
  ```
</Accordion>

## Legal hold policy (Mini)

A mini legal hold policy.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this legal hold policy. |
  | `type` | `enum<string>` | Yes | The value will always be `legal_hold_policy`. Available options: `legal_hold_policy`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "legal_hold_policy"
  }
  ```
</Accordion>


# Legal hold policy assignments resources
Source: https://developer.box.com/reference/legal-hold-policy-assignments-resources



A Legal Hold Policy Assignment is a relation between a policy and custodian. In this case, as custodian can be a user, folder, file, or file version.

## File versions on hold

A list of files on hold for legal policy assignment.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of `File version` | No | A list of file versions on hold. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc",
        "name": "tigers.jpeg",
        "size": 629644,
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "trashed_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "restored_at": "2012-12-12T10:53:43-08:00",
        "restored_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "purged_at": "2012-12-12T10:53:43-08:00",
        "uploader_display_name": "Ellis Wiggins"
      }
    ]
  }
  ```
</Accordion>

## Files on hold

A list of files on hold for legal policy assignment.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [File (Mini)](/reference/files-resources#file-mini) | No | A list of files. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      }
    ]
  }
  ```
</Accordion>

## Legal hold policy assignment

Legal Hold Assignments are used to assign Legal Hold Policies to an item type of: Users, Folders, Files, File Versions, Ownership, or Interactions. Creating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this legal hold assignment. |
  | `type` | `enum<string>` | No | The value will always be `legal_hold_policy_assignment`. Available options: `legal_hold_policy_assignment`. |
  | `legal_hold_policy` | [Legal hold policy (Mini)](/reference/legal-hold-policies-resources#legal-hold-policy-mini) | No | The policy that the legal hold policy assignment is part of. |
  | `assigned_to` | `Legal hold policy item` | No | The item that the legal hold policy is assigned to. Includes type and ID. |
  | `assigned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created the legal hold policy assignment. |
  | `assigned_at` | `string` | No | When the legal hold policy assignment object was created. |
  | `deleted_at` | `string` | No | When the assignment release request was sent. (Because it can take time for an assignment to fully delete, this isn't quite the same time that the assignment is fully deleted). If null, Assignment was not deleted. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "legal_hold_policy_assignment",
    "legal_hold_policy": {
      "id": "11446498",
      "type": "legal_hold_policy"
    },
    "assigned_to": {
      "type": "folder",
      "id": "6564564"
    },
    "assigned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "assigned_at": "2012-12-12T10:53:43-08:00",
    "deleted_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Legal hold policy assignment (Base)

Legal Hold Assignments are used to assign Legal Hold Policies to Users, Folders, Files, or File Versions. Creating a Legal Hold Assignment puts a hold on the File-Versions that belong to the Assignment's 'apply-to' entity.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this legal hold assignment. |
  | `type` | `enum<string>` | No | The value will always be `legal_hold_policy_assignment`. Available options: `legal_hold_policy_assignment`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "legal_hold_policy_assignment"
  }
  ```
</Accordion>

## Legal hold policy assignments

A list of legal hold policies assignments.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Legal hold policy assignment](#legal-hold-policy-assignment) | No | A list of legal hold policy assignments. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "legal_hold_policy_assignment",
        "legal_hold_policy": {
          "id": "11446498",
          "type": "legal_hold_policy"
        },
        "assigned_to": {
          "type": "folder",
          "id": "6564564"
        },
        "assigned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "assigned_at": "2012-12-12T10:53:43-08:00",
        "deleted_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# Metadata cascade policies resources
Source: https://developer.box.com/reference/metadata-cascade-policies-resources



A metadata cascade policy describes how metadata instances applied to a folder should be applied to any item within that folder.

## Metadata cascade policies

A list of metadata cascade policies.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Metadata cascade policy](#metadata-cascade-policy) | No | A list of metadata cascade policies. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7",
        "type": "metadata_cascade_policy",
        "owner_enterprise": {
          "type": "enterprise",
          "id": "690678"
        },
        "parent": {
          "type": "folder",
          "id": "1234567"
        },
        "scope": "enterprise_123456",
        "templateKey": "productInfo"
      }
    ]
  }
  ```
</Accordion>

## Metadata cascade policy

A metadata cascade policy automatically applies a metadata template instance to all the files and folders within the targeted folder.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The ID of the metadata cascade policy object. |
  | `type` | `enum<string>` | Yes | The value will always be `metadata_cascade_policy`. Available options: `metadata_cascade_policy`. |
  | `owner_enterprise` | `object` | No | The enterprise that owns this policy. |
  | `parent` | `object` | No | Represent the folder the policy is applied to. |
  | `scope` | `string` | No | The scope of the metadata cascade policy can either be `global` or `enterprise_*`. The `global` scope is used for policies that are available to any Box enterprise. The `enterprise_*` scope represents policies that have been created within a specific enterprise, where `*` will be the ID of that enterprise. |
  | `templateKey` | `string` | No | The key of the template that is cascaded down to the folder's children. In many cases the template key is automatically derived of its display name, for example `Contract Template` would become `contractTemplate`. In some cases the creator of the template will have provided its own template key. Please \[list the templates for an enterprise]\[list], or get all instances on a \[file]\[file] or \[folder]\[folder] to inspect a template's key. \[list]: /reference/get-metadata-templates-enterprise \[file]: /reference/get-files-id-metadata \[folder]: /reference/get-folders-id-metadata |

  ```json Example theme={null}
  {
    "id": "6fd4ff89-8fc1-42cf-8b29-1890dedd26d7",
    "type": "metadata_cascade_policy",
    "owner_enterprise": {
      "type": "enterprise",
      "id": "690678"
    },
    "parent": {
      "type": "folder",
      "id": "1234567"
    },
    "scope": "enterprise_123456",
    "templateKey": "productInfo"
  }
  ```
</Accordion>


# Metadata taxonomies resources
Source: https://developer.box.com/reference/metadata-taxonomies-resources



A metadata taxonomy is a hierarchical classification system that helps organize and manage metadata within an enterprise.

## Metadata taxonomies

A list of metadata taxonomies.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Metadata taxonomy](#metadata-taxonomy) | No | A list of metadata taxonomies. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "822227e0-47a5-921b-88a8-494760b2e6d2",
        "key": "geography",
        "displayName": "Geography",
        "namespace": "enterprise_123456",
        "levels": [
          {
            "displayName": "Continent",
            "description": "Continent",
            "level": 1
          }
        ]
      }
    ]
  }
  ```
</Accordion>

## Metadata taxonomy

A taxonomy object for metadata that can be used in metadata templates.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | A unique identifier of the metadata taxonomy. |
  | `key` | `string` | No | A unique identifier of the metadata taxonomy. The identifier must be unique within the namespace to which it belongs. |
  | `displayName` | `string` | Yes | The display name of the metadata taxonomy. This can be seen in the Box web app. |
  | `namespace` | `string` | Yes | A namespace that the metadata taxonomy is associated with. |
  | `levels` | array of [Metadata taxonomy level](#metadata-taxonomy-level) | No | Levels of the metadata taxonomy. |

  ```json Example theme={null}
  {
    "id": "822227e0-47a5-921b-88a8-494760b2e6d2",
    "key": "geography",
    "displayName": "Geography",
    "namespace": "enterprise_123456",
    "levels": [
      {
        "displayName": "Continent",
        "description": "Continent",
        "level": 1
      }
    ]
  }
  ```
</Accordion>

## Metadata taxonomy level

A level in the metadata taxonomy represents a hierarchical category within the taxonomy structure.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `displayName` | `string` | No | The display name of the level as it is shown to the user. |
  | `description` | `string` | No | A description of the level. |
  | `level` | `integer` | No | An index of the level within the taxonomy. Levels are indexed starting from 1. |

  ```json Example theme={null}
  {
    "displayName": "Continent",
    "description": "Continent",
    "level": 1
  }
  ```
</Accordion>

## Metadata taxonomy levels

Levels in the metadata taxonomy represent hierarchical categories within the taxonomy structure.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Metadata taxonomy level](#metadata-taxonomy-level) | No | An array of all taxonomy levels. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "displayName": "Continent",
        "description": "Continent",
        "level": 1
      }
    ]
  }
  ```
</Accordion>

## Metadata taxonomy node

A node object for metadata taxonomy that can be used in metadata templates.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | A unique identifier of the metadata taxonomy node. |
  | `displayName` | `string` | Yes | The display name of the metadata taxonomy node. |
  | `level` | `integer` | Yes | An index of the level to which the node belongs. |
  | `parentId` | `string` | No | The identifier of the parent node. |
  | `nodePath` | array of `string` | No | An array of identifiers for all ancestor nodes. Not returned for root-level nodes. |
  | `ancestors` | array of `Metadata taxonomy ancestor` | No | An array of objects for all ancestor nodes. Not returned for root-level nodes. |

  ```json Example theme={null}
  {
    "id": "14d3d433-c77f-49c5-b146-9dea370f6e32",
    "displayName": "France",
    "level": 2,
    "parentId": "99df4513-7102-4896-8228-94635ee9d330",
    "nodePath": [
      "99df4513-7102-4896-8228-94635ee9d330"
    ],
    "ancestors": [
      {
        "id": "14d3d433-c77f-49c5-b146-9dea370f6e32",
        "displayName": "France",
        "level": 2
      }
    ]
  }
  ```
</Accordion>

## Metadata taxonomy nodes

A list of metadata taxonomy nodes.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Metadata taxonomy node](#metadata-taxonomy-node) | No | A list of metadata taxonomy nodes. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "14d3d433-c77f-49c5-b146-9dea370f6e32",
        "displayName": "France",
        "level": 2,
        "parentId": "99df4513-7102-4896-8228-94635ee9d330",
        "nodePath": [
          "99df4513-7102-4896-8228-94635ee9d330"
        ],
        "ancestors": [
          {
            "id": "14d3d433-c77f-49c5-b146-9dea370f6e32",
            "displayName": "France",
            "level": 2
          }
        ]
      }
    ]
  }
  ```
</Accordion>


# Metadata templates resources
Source: https://developer.box.com/reference/metadata-templates-resources



A metadata template describes a reusable set of key/value pairs that can be assigned to a file.

## Metadata template

A template for metadata that can be applied to files and folders.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The ID of the metadata template. |
  | `type` | `enum<string>` | Yes | The value will always be `metadata_template`. Available options: `metadata_template`. |
  | `scope` | `string` | No | The scope of the metadata template can either be `global` or `enterprise_*`. The `global` scope is used for templates that are available to any Box enterprise. The `enterprise_*` scope represents templates that have been created within a specific enterprise, where `*` will be the ID of that enterprise. |
  | `templateKey` | `string` | No | A unique identifier for the template. This identifier is unique across the `scope` of the enterprise to which the metadata template is being applied, yet is not necessarily unique across different enterprises. |
  | `displayName` | `string` | No | The display name of the template. This can be seen in the Box web app and mobile apps. |
  | `hidden` | `boolean` | No | Defines if this template is visible in the Box web app UI, or if it is purely intended for usage through the API. |
  | `fields` | array of `object` | No | An ordered list of template fields which are part of the template. Each field can be a regular text field, date field, number field, as well as a single or multi-select list. |
  | `copyInstanceOnItemCopy` | `boolean` | No | Whether or not to include the metadata when a file or folder is copied. |

  ```json Example theme={null}
  {
    "id": "58063d82-4128-7b43-bba9-92f706befcdf",
    "type": "metadata_template",
    "scope": "enterprise_123456",
    "templateKey": "productInfo",
    "displayName": "Product Info",
    "hidden": true,
    "fields": [
      {
        "type": "string",
        "key": "category",
        "displayName": "Category",
        "description": "The category",
        "hidden": true,
        "options": [
          {
            "key": "Category 1",
            "id": "45dc2849-a4a7-40a9-a751-4a699a589190"
          }
        ],
        "taxonomyKey": "locationTaxonomy",
        "taxonomyId": "05ece6d7-fec4-4d3f-bfd2-36fd4dddea97",
        "namespace": "enterprise_123456",
        "optionsRules": {
          "multiSelect": true,
          "selectableLevels": [
            1,
            2
          ]
        },
        "id": "822227e0-47a5-921b-88a8-494760b2e6d2"
      }
    ],
    "copyInstanceOnItemCopy": true
  }
  ```
</Accordion>

## Metadata templates

A list of metadata templates.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Metadata template](#metadata-template) | No | A list of metadata templates. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "58063d82-4128-7b43-bba9-92f706befcdf",
        "type": "metadata_template",
        "scope": "enterprise_123456",
        "templateKey": "productInfo",
        "displayName": "Product Info",
        "hidden": true,
        "fields": [
          {
            "type": "string",
            "key": "category",
            "displayName": "Category",
            "description": "The category",
            "hidden": true,
            "options": [
              {
                "key": "Category 1",
                "id": "45dc2849-a4a7-40a9-a751-4a699a589190"
              }
            ],
            "taxonomyKey": "locationTaxonomy",
            "taxonomyId": "05ece6d7-fec4-4d3f-bfd2-36fd4dddea97",
            "namespace": "enterprise_123456",
            "optionsRules": {
              "multiSelect": true,
              "selectableLevels": [
                1,
                2
              ]
            },
            "id": "822227e0-47a5-921b-88a8-494760b2e6d2"
          }
        ],
        "copyInstanceOnItemCopy": true
      }
    ]
  }
  ```
</Accordion>


# Update metadata taxonomy
Source: https://developer.box.com/reference/patch-metadata-taxonomies-id-id

box-openapi.json PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}
Updates an existing metadata taxonomy.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update metadata taxonomy level
Source: https://developer.box.com/reference/patch-metadata-taxonomies-id-id-levels-id

box-openapi.json PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}/levels/{level_index}
Updates an existing metadata taxonomy level.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update metadata taxonomy node
Source: https://developer.box.com/reference/patch-metadata-taxonomies-id-id-nodes-id

box-openapi.json PATCH /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes/{node_id}
Updates an existing metadata taxonomy node.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create metadata instance on file
Source: https://developer.box.com/reference/post-files-id-metadata-id-id

box-openapi.json POST /files/{file_id}/metadata/{scope}/{template_key}
Applies an instance of a metadata template to a file.

In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create metadata instance on folder
Source: https://developer.box.com/reference/post-folders-id-metadata-id-id

box-openapi.json POST /folders/{folder_id}/metadata/{scope}/{template_key}
Applies an instance of a metadata template to a folder.

In most cases only values that are present in the metadata template will be accepted, except for the `global.properties` template which accepts any key-value pair.

To display the metadata template in the Box web app the enterprise needs to be configured to enable **Cascading Folder Level Metadata** for the user in the admin console.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create jobs to terminate user group session
Source: https://developer.box.com/reference/post-groups-terminate-sessions

box-openapi.json POST /groups/terminate_sessions
Validates the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions. Returns the status for the POST request.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create user invite
Source: https://developer.box.com/reference/post-invites

box-openapi.json POST /invites
Invites an existing external user to join an enterprise.

The existing user can not be part of another enterprise and must already have a Box account. Once invited, the user will receive an email and are prompted to accept the invitation within the Box web application.

This method requires the "Manage An Enterprise" scope enabled for the application, which can be enabled within the developer console.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create legal hold policy
Source: https://developer.box.com/reference/post-legal-hold-policies

box-openapi.json POST /legal_hold_policies
Create a new legal hold policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Assign legal hold policy
Source: https://developer.box.com/reference/post-legal-hold-policy-assignments

box-openapi.json POST /legal_hold_policy_assignments
Assign a legal hold to an item type of: file, file version, folder, user, ownership, or interactions.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create metadata cascade policy
Source: https://developer.box.com/reference/post-metadata-cascade-policies

box-openapi.json POST /metadata_cascade_policies
Creates a new metadata cascade policy that applies a given metadata template to a given folder and automatically cascades it down to any files within that folder.

In order for the policy to be applied a metadata instance must first be applied to the folder the policy is to be applied to.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Force-apply metadata cascade policy to folder
Source: https://developer.box.com/reference/post-metadata-cascade-policies-id-apply

box-openapi.json POST /metadata_cascade_policies/{metadata_cascade_policy_id}/apply
Force the metadata on a folder with a metadata cascade policy to be applied to all of its children. This can be used after creating a new cascade policy to enforce the metadata to be cascaded down to all existing files within that folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Query files/folders by metadata
Source: https://developer.box.com/reference/post-metadata-queries-execute-read

box-openapi.json POST /metadata_queries/execute_read
Create a search using SQL-like syntax to return items that match specific metadata.

By default, this endpoint returns only the most basic info about the items for which the query matches. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create metadata taxonomy
Source: https://developer.box.com/reference/post-metadata-taxonomies

box-openapi.json POST /metadata_taxonomies
Creates a new metadata taxonomy that can be used in metadata templates.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create metadata taxonomy levels
Source: https://developer.box.com/reference/post-metadata-taxonomies-id-id-levels

box-openapi.json POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels
Creates new metadata taxonomy levels.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add metadata taxonomy level
Source: https://developer.box.com/reference/post-metadata-taxonomies-id-id-levels--append

box-openapi.json POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels:append
Creates a new metadata taxonomy level and appends it to the existing levels. If there are no levels defined yet, this will create the first level.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete metadata taxonomy level
Source: https://developer.box.com/reference/post-metadata-taxonomies-id-id-levels--trim

box-openapi.json POST /metadata_taxonomies/{namespace}/{taxonomy_key}/levels:trim
Deletes the last level of the metadata taxonomy.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create metadata taxonomy node
Source: https://developer.box.com/reference/post-metadata-taxonomies-id-id-nodes

box-openapi.json POST /metadata_taxonomies/{namespace}/{taxonomy_key}/nodes
Creates a new metadata taxonomy node.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create metadata template
Source: https://developer.box.com/reference/post-metadata-templates-schema

box-openapi.json POST /metadata_templates/schema
Creates a new metadata template that can be applied to files and folders.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create retention policy
Source: https://developer.box.com/reference/post-retention-policies

box-openapi.json POST /retention_policies
Creates a retention policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Assign retention policy
Source: https://developer.box.com/reference/post-retention-policy-assignments

box-openapi.json POST /retention_policy_assignments
Assigns a retention policy to an item.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create shield information barrier report
Source: https://developer.box.com/reference/post-shield-information-barrier-reports

box-openapi.json POST /shield_information_barrier_reports
Creates a shield information barrier report for a given barrier.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create jobs to terminate users session
Source: https://developer.box.com/reference/post-users-terminate-sessions

box-openapi.json POST /users/terminate_sessions
Validates the roles and permissions of the user, and creates asynchronous jobs to terminate the user's sessions. Returns the status for the POST request.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add shared link to file
Source: https://developer.box.com/reference/put-files-id--add-shared-link

box-openapi.json PUT /files/{file_id}#add_shared_link
Adds a shared link to a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove shared link from file
Source: https://developer.box.com/reference/put-files-id--remove-shared-link

box-openapi.json PUT /files/{file_id}#remove_shared_link
Removes a shared link from a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update shared link on file
Source: https://developer.box.com/reference/put-files-id--update-shared-link

box-openapi.json PUT /files/{file_id}#update_shared_link
Updates a shared link on a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update metadata instance on file
Source: https://developer.box.com/reference/put-files-id-metadata-id-id

box-openapi.json PUT /files/{file_id}/metadata/{scope}/{template_key}
Updates a piece of metadata on a file.

The metadata instance can only be updated if the template has already been applied to the file before. When editing metadata, only values that match the metadata template schema will be accepted.

The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add shared link to folder
Source: https://developer.box.com/reference/put-folders-id--add-shared-link

box-openapi.json PUT /folders/{folder_id}#add_shared_link
Adds a shared link to a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove shared link from folder
Source: https://developer.box.com/reference/put-folders-id--remove-shared-link

box-openapi.json PUT /folders/{folder_id}#remove_shared_link
Removes a shared link from a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update shared link on folder
Source: https://developer.box.com/reference/put-folders-id--update-shared-link

box-openapi.json PUT /folders/{folder_id}#update_shared_link
Updates a shared link on a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update metadata instance on folder
Source: https://developer.box.com/reference/put-folders-id-metadata-id-id

box-openapi.json PUT /folders/{folder_id}/metadata/{scope}/{template_key}
Updates a piece of metadata on a folder.

The metadata instance can only be updated if the template has already been applied to the folder before. When editing metadata, only values that match the metadata template schema will be accepted.

The update is applied atomically. If any errors occur during the application of the operations, the metadata instance will not be changed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update legal hold policy
Source: https://developer.box.com/reference/put-legal-hold-policies-id

box-openapi.json PUT /legal_hold_policies/{legal_hold_policy_id}
Update legal hold policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update metadata template
Source: https://developer.box.com/reference/put-metadata-templates-id-id-schema

box-openapi.json PUT /metadata_templates/{scope}/{template_key}/schema
Updates a metadata template.

The metadata template can only be updated if the template already exists.

The update is applied atomically. If any errors occur during the application of the operations, the metadata template will not be changed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update retention policy
Source: https://developer.box.com/reference/put-retention-policies-id

box-openapi.json PUT /retention_policies/{retention_policy_id}
Updates a retention policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add shared link to web link
Source: https://developer.box.com/reference/put-web-links-id--add-shared-link

box-openapi.json PUT /web_links/{web_link_id}#add_shared_link
Adds a shared link to a web link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove shared link from web link
Source: https://developer.box.com/reference/put-web-links-id--remove-shared-link

box-openapi.json PUT /web_links/{web_link_id}#remove_shared_link
Removes a shared link from a web link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update shared link on web link
Source: https://developer.box.com/reference/put-web-links-id--update-shared-link

box-openapi.json PUT /web_links/{web_link_id}#update_shared_link
Updates a shared link on a web link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Recent items resources
Source: https://developer.box.com/reference/recent-items-resources



Recent items represent items such as files or folders that the user accessed recently.

## Recent item

A recent item accessed by a user.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `string` | No | The value will always be `recent_item`. |
  | `item` | `Recent item resource` | No | The item that was recently accessed. |
  | `interaction_type` | `enum<string>` | No | The most recent type of access the user performed on the item. Available options: `item_preview`, `item_upload`, `item_comment`, `item_open`, `item_modify`. |
  | `interacted_at` | `string` | No | The time of the most recent interaction. |
  | `interaction_shared_link` | `string` | No | If the item was accessed through a shared link it will appear here, otherwise this will be null. |

  ```json Example theme={null}
  {
    "type": "recent_item",
    "item": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      },
      "description": "Contract for Q1 renewal",
      "size": 629644,
      "path_collection": {
        "total_count": 1,
        "entries": [
          {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          }
        ]
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "trashed_at": "2012-12-12T10:53:43-08:00",
      "purged_at": "2012-12-12T10:53:43-08:00",
      "content_created_at": "2012-12-12T10:53:43-08:00",
      "content_modified_at": "2012-12-12T10:53:43-08:00",
      "created_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "modified_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "owned_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": "https://acme.app.box.com/v/my_url/",
        "vanity_name": "my_url",
        "access": "open",
        "effective_access": "company",
        "effective_permission": "can_download",
        "unshared_at": "2018-04-13T13:53:23-07:00",
        "is_password_enabled": true,
        "permissions": {
          "can_download": true,
          "can_preview": true,
          "can_edit": false
        },
        "download_count": 3,
        "preview_count": 3
      },
      "parent": {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      },
      "item_status": "active",
      "version_number": "1",
      "comment_count": 10,
      "permissions": {
        "can_delete": true,
        "can_download": true,
        "can_invite_collaborator": true,
        "can_rename": true,
        "can_set_share_access": true,
        "can_share": true,
        "can_annotate": true,
        "can_comment": true,
        "can_preview": true,
        "can_upload": true,
        "can_view_annotations_all": true,
        "can_view_annotations_self": true,
        "can_apply_watermark": true
      },
      "tags": [
        "approved"
      ],
      "lock": {
        "id": "11446498",
        "type": "lock",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "expired_at": "2012-12-12T10:53:43-08:00",
        "is_download_prevented": true,
        "app_type": "office_wopiplus"
      },
      "extension": "pdf",
      "is_package": true,
      "expiring_embed_link": {
        "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
        "expires_in": 3600,
        "token_type": "bearer",
        "restricted_to": [
          {
            "scope": "item_download",
            "object": {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          }
        ],
        "url": "https://cloud.app.box.com/preview/expiring_embed/..."
      },
      "watermark_info": {
        "is_watermarked": true,
        "is_watermark_inherited": false,
        "is_watermarked_by_access_policy": false
      },
      "is_accessible_via_shared_link": true,
      "allowed_invitee_roles": [
        "editor"
      ],
      "is_externally_owned": true,
      "has_collaborations": true,
      "metadata": {
        "enterprise_27335": {
          "marketingCollateral": {
            "$canEdit": true,
            "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
            "$parent": "folder_59449484661",
            "$scope": "enterprise_27335",
            "$template": "marketingCollateral",
            "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
            "$typeVersion": 2,
            "$version": 1
          }
        }
      },
      "expires_at": "2012-12-12T10:53:43-08:00",
      "representations": {
        "entries": [
          {
            "content": {
              "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
            },
            "info": {
              "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
            },
            "properties": {
              "dimensions": "2048x2048",
              "paged": "true",
              "thumb": "true"
            },
            "representation": "png",
            "status": {
              "state": "success"
            }
          }
        ]
      },
      "classification": {
        "name": "Top Secret",
        "definition": "Content that should not be shared outside the company.",
        "color": "#FF0000"
      },
      "uploader_display_name": "Ellis Wiggins",
      "disposition_at": "2012-12-12T10:53:43-08:00",
      "shared_link_permission_options": [
        "can_preview"
      ],
      "is_associated_with_app_item": true,
      "collections": [
        {
          "id": "11446498",
          "type": "collection",
          "name": "Favorites",
          "collection_type": "favorites"
        }
      ],
      "is_download_available": true,
      "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
      "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
      "allowed_shared_link_access_levels": [
        "open"
      ]
    },
    "interaction_type": "item_preview",
    "interacted_at": "2018-04-13T13:53:23-07:00",
    "interaction_shared_link": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg"
  }
  ```
</Accordion>


# Retention policies resources
Source: https://developer.box.com/reference/retention-policies-resources



A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then assign them to specific folders or their entire enterprise.

## Retention policies

A list of retention policies.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Retention policy](#retention-policy) | No | A list in which each entry represents a retention policy object. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "retention_policy",
        "policy_name": "Some Policy Name",
        "retention_length": "365",
        "disposition_action": "permanently_delete",
        "max_extension_length": "365",
        "description": "Policy to retain all reports for at least one month",
        "policy_type": "finite",
        "retention_type": "non_modifiable",
        "status": "active",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "can_owner_extend_retention": false,
        "are_owners_notified": false,
        "custom_notification_recipients": [
          {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          }
        ],
        "assignment_counts": {
          "enterprise": 1,
          "folder": 1,
          "metadata_template": 1
        }
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>

## Retention policy

A retention policy blocks permanent deletion of content for a specified amount of time. Admins can create retention policies and then later assign them to specific folders, metadata templates, or their entire enterprise. To use this feature, you must have the manage retention policies scope enabled for your API key via your application management console.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represents a retention policy. |
  | `type` | `enum<string>` | Yes | The value will always be `retention_policy`. Available options: `retention_policy`. |
  | `policy_name` | `string` | No | The name given to the retention policy. |
  | `retention_length` | `string` | No | The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. |
  | `disposition_action` | `enum<string>` | No | The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. Available options: `permanently_delete`, `remove_retention`. |
  | `max_extension_length` | `Retention policy max extension length (response)` | No | Available options: `none`. |
  | `description` | `string` | No | The additional text description of the retention policy. |
  | `policy_type` | `enum<string>` | No | The type of the retention policy. A retention policy type can either be `finite`, where a specific amount of time to retain the content is known upfront, or `indefinite`, where the amount of time to retain the content is still unknown. Available options: `finite`, `indefinite`. |
  | `retention_type` | `enum<string>` | No | Specifies the retention type: - `modifiable`: You can modify the retention policy. For example, you can add or remove folders, shorten or lengthen the policy duration, or delete the assignment. Use this type if your retention policy is not related to any regulatory purposes. - `non-modifiable`: You can modify the retention policy only in a limited way: add a folder, lengthen the duration, retire the policy, change the disposition action or notification settings. You cannot perform other actions, such as deleting the assignment or shortening the policy duration. Use this type to ensure compliance with regulatory retention policies. Available options: `modifiable`, `non_modifiable`. |
  | `status` | `enum<string>` | No | The status of the retention policy. The status of a policy will be `active`, unless explicitly retired by an administrator, in which case the status will be `retired`. Once a policy has been retired, it cannot become active again. Available options: `active`, `retired`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | A mini user object representing the user that created the retention policy. |
  | `created_at` | `string` | No | When the retention policy object was created. |
  | `modified_at` | `string` | No | When the retention policy object was last modified. |
  | `can_owner_extend_retention` | `boolean` | No | Determines if the owner of items under the policy can extend the retention when the original retention duration is about to end. |
  | `are_owners_notified` | `boolean` | No | Determines if owners and co-owners of items under the policy are notified when the retention duration is about to end. |
  | `custom_notification_recipients` | array of [User (Mini)](/reference/users-resources#user-mini) | No | A list of users notified when the retention policy duration is about to end. |
  | `assignment_counts` | `object` | No | Counts the retention policy assignments for each item type. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "retention_policy",
    "policy_name": "Some Policy Name",
    "retention_length": "365",
    "disposition_action": "permanently_delete",
    "max_extension_length": "365",
    "description": "Policy to retain all reports for at least one month",
    "policy_type": "finite",
    "retention_type": "non_modifiable",
    "status": "active",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "can_owner_extend_retention": false,
    "are_owners_notified": false,
    "custom_notification_recipients": [
      {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      }
    ],
    "assignment_counts": {
      "enterprise": 1,
      "folder": 1,
      "metadata_template": 1
    }
  }
  ```
</Accordion>

## Retention policy (Base)

A base representation of a retention policy.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represents a retention policy. |
  | `type` | `enum<string>` | Yes | The value will always be `retention_policy`. Available options: `retention_policy`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "retention_policy"
  }
  ```
</Accordion>

## Retention policy (Mini)

A mini representation of a retention policy, used when nested within another resource.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represents a retention policy. |
  | `type` | `enum<string>` | Yes | The value will always be `retention_policy`. Available options: `retention_policy`. |
  | `policy_name` | `string` | No | The name given to the retention policy. |
  | `retention_length` | `string` | No | The length of the retention policy. This value specifies the duration in days that the retention policy will be active for after being assigned to content. If the policy has a `policy_type` of `indefinite`, the `retention_length` will also be `indefinite`. |
  | `disposition_action` | `enum<string>` | No | The disposition action of the retention policy. This action can be `permanently_delete`, which will cause the content retained by the policy to be permanently deleted, or `remove_retention`, which will lift the retention policy from the content, allowing it to be deleted by users, once the retention policy has expired. Available options: `permanently_delete`, `remove_retention`. |
  | `max_extension_length` | `Retention policy max extension length (response)` | No | Available options: `none`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "retention_policy",
    "policy_name": "Some Policy Name",
    "retention_length": "365",
    "disposition_action": "permanently_delete",
    "max_extension_length": "365"
  }
  ```
</Accordion>


# Retention policy assignments resources
Source: https://developer.box.com/reference/retention-policy-assignments-resources



A Retention Policy Assignment is a relation between a policy and folder or enterprise. Creating an assignment puts a retention on all the file versions that belong to that folder or enterprise.

## Files under retention

A list of files under retention.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [File (Mini)](/reference/files-resources#file-mini) | No | A list of files. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        }
      }
    ]
  }
  ```
</Accordion>

## Retention policy assignment

A retention assignment represents a rule specifying the files a retention policy retains. Assignments can retain files based on their folder or metadata, or hold all files in the enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for a retention policy assignment. |
  | `type` | `enum<string>` | Yes | The value will always be `retention_policy_assignment`. Available options: `retention_policy_assignment`. |
  | `retention_policy` | [Retention policy (Mini)](/reference/retention-policies-resources#retention-policy-mini) | No | A mini representation of a retention policy object that has been assigned to the content. |
  | `assigned_to` | `object` | No | The `type` and `id` of the content that is under retention. The `type` can either be `folder` `enterprise`, or `metadata_template`. |
  | `filter_fields` | array of `object` | No | An array of field objects. Values are only returned if the `assigned_to` type is `metadata_template`. Otherwise, the array is blank. Can be `null`. |
  | `assigned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | A mini user object representing the user that created the retention policy assignment. |
  | `assigned_at` | `string` | No | When the retention policy assignment object was created. |
  | `start_date_field` | `string` | No | The date the retention policy assignment begins. If the `assigned_to` type is `metadata_template`, this field can be a date field's metadata attribute key id. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "retention_policy_assignment",
    "retention_policy": {
      "id": "12345",
      "type": "retention_policy",
      "policy_name": "Some Policy Name",
      "retention_length": "365",
      "disposition_action": "permanently_delete",
      "max_extension_length": "365"
    },
    "assigned_to": {
      "id": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65",
      "type": "metadata_template"
    },
    "filter_fields": [
      {
        "field": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4",
        "value": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e"
      }
    ],
    "assigned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "assigned_at": "2012-12-12T10:53:43-08:00",
    "start_date_field": "upload_date"
  }
  ```
</Accordion>

## Retention policy assignments

A list of retention policy assignments.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Retention policy assignment](#retention-policy-assignment) | No | A list of retention policy assignments. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "11446498",
        "type": "retention_policy_assignment",
        "retention_policy": {
          "id": "12345",
          "type": "retention_policy",
          "policy_name": "Some Policy Name",
          "retention_length": "365",
          "disposition_action": "permanently_delete",
          "max_extension_length": "365"
        },
        "assigned_to": {
          "id": "a983f69f-e85f-4ph4-9f46-4afdf9c1af65",
          "type": "metadata_template"
        },
        "filter_fields": [
          {
            "field": "a0f4ee4e-1dc1-4h90-a8a9-aef55fc681d4",
            "value": "0c27b756-0p87-4fe0-a43a-59fb661ccc4e"
          }
        ],
        "assigned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "assigned_at": "2012-12-12T10:53:43-08:00",
        "start_date_field": "upload_date"
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Search resources
Source: https://developer.box.com/reference/search-resources



The Box API provides a way to find content in Box using full-text search queries.

## Metadata filter

A metadata template used to filter the search results.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `scope` | `enum<string>` | No | Specifies the scope of the template to filter search results by. This will be `enterprise_{enterprise_id}` for templates defined for use in this enterprise, and `global` for general templates that are available to all enterprises using Box. Available options: `global`, `enterprise`, `enterprise_{enterprise_id}`. |
  | `templateKey` | `string` | No | The key of the template used to filter search results. In many cases the template key is automatically derived of its display name, for example `Contract Template` would become `contractTemplate`. In some cases the creator of the template will have provided its own template key. Please \[list the templates for an enterprise]\[list], or get all instances on a \[file]\[file] or \[folder]\[folder] to inspect a template's key. \[list]: /reference/get-metadata-templates-enterprise \[file]: /reference/get-files-id-metadata \[folder]: /reference/get-folders-id-metadata |
  | `filters` | `object` | No | Specifies which fields on the template to filter the search results by. When more than one field is specified, the query performs a logical `AND` to ensure that the instance of the template matches each of the fields specified. |

  ```json Example theme={null}
  {
    "scope": "enterprise",
    "templateKey": "contract",
    "filters": {
      "category": "online"
    }
  }
  ```
</Accordion>

## Metadata query search results

A page of files and folders that matched the metadata query.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of `Metadata query search result item` | No | The mini representation of the files and folders that match the search terms. By default, this endpoint returns only the most basic info about the items. To get additional fields for each item, including any of the metadata, use the `fields` attribute in the query. |
  | `limit` | `integer` | No | The limit that was used for this search. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "description": "Contract for Q1 renewal",
        "size": 629644,
        "path_collection": {
          "total_count": 1,
          "entries": [
            {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          ]
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "purged_at": "2012-12-12T10:53:43-08:00",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "vanity_url": "https://acme.app.box.com/v/my_url/",
          "vanity_name": "my_url",
          "access": "open",
          "effective_access": "company",
          "effective_permission": "can_download",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_preview": true,
            "can_edit": false
          },
          "download_count": 3,
          "preview_count": 3
        },
        "parent": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "item_status": "active",
        "version_number": "1",
        "comment_count": 10,
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true,
          "can_apply_watermark": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "expired_at": "2012-12-12T10:53:43-08:00",
          "is_download_prevented": true,
          "app_type": "office_wopiplus"
        },
        "extension": "pdf",
        "is_package": true,
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "token_type": "bearer",
          "restricted_to": [
            {
              "scope": "item_download",
              "object": {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            }
          ],
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "watermark_info": {
          "is_watermarked": true,
          "is_watermark_inherited": false,
          "is_watermarked_by_access_policy": false
        },
        "is_accessible_via_shared_link": true,
        "allowed_invitee_roles": [
          "editor"
        ],
        "is_externally_owned": true,
        "has_collaborations": true,
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "expires_at": "2012-12-12T10:53:43-08:00",
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "classification": {
          "name": "Top Secret",
          "definition": "Content that should not be shared outside the company.",
          "color": "#FF0000"
        },
        "uploader_display_name": "Ellis Wiggins",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "shared_link_permission_options": [
          "can_preview"
        ],
        "is_associated_with_app_item": true,
        "collections": [
          {
            "id": "11446498",
            "type": "collection",
            "name": "Favorites",
            "collection_type": "favorites"
          }
        ],
        "is_download_available": true,
        "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
        "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
        "allowed_shared_link_access_levels": [
          "open"
        ]
      }
    ],
    "limit": 100,
    "next_marker": "0!-M7487OpVfBTNBV-XsQjU50gQFlbFFu5nArMWD7Ck61GH_Qo40M1S2xN5zWZPBzEjaQS1SOjJiQoo5BsXEl1bCVLRZ2pTqo4SKp9tyqzWQK2L51KR_nC1EgF5I_TJSFw7uO2Bx4HweGETOjh5_2oPSWw5iMkM-OvGApeR0lGFO48FDKoyzJyLgz5aogxoKd8VE09CesOOnTnmZvrW0puylDc-hFjY5YLmWFBKox3SOWiSDwKFkmZGNHyjEzza1nSwbZg6CYsAdGsDwGJhuCeTNsFzP5Mo5qx9wMloS0lSPuf2CcBInbIJzl2CKlXF3FvqhANttpm2nzdBTQRSoJyJnjVBpf4Q_HjV2eb4KIZBBlLy067UCVdv2AAWQFd5E2i6s1YiGRTtgMEZntOSUYD4IYLMWWm5Ra7ke_SP32SL3GSjbBQYIyCVQ.."
  }
  ```
</Accordion>

## Search Result (including Shared Link)

A single of files, folder or web link that matched the search query, including the additional information about the shared link through which the item has been shared with the user. This response format is only returned when the `include_recent_shared_links` query parameter has been set to `true`.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `accessible_via_shared_link` | `string` | No | The optional shared link through which the user has access to this item. This value is only returned for items for which the user has recently accessed the file through a shared link. For all other items this value will return `null`. |
  | `item` | `Search result item` | No | The file, folder or web link that matched the search query. |
  | `type` | `string` | No | The result type. The value is always `search_result`. |

  ```json Example theme={null}
  {
    "accessible_via_shared_link": "https://www.box.com/s/vspke7y05sb214wjokpk",
    "item": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      },
      "description": "Contract for Q1 renewal",
      "size": 629644,
      "path_collection": {
        "total_count": 1,
        "entries": [
          {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          }
        ]
      },
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00",
      "trashed_at": "2012-12-12T10:53:43-08:00",
      "purged_at": "2012-12-12T10:53:43-08:00",
      "content_created_at": "2012-12-12T10:53:43-08:00",
      "content_modified_at": "2012-12-12T10:53:43-08:00",
      "created_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "modified_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "owned_by": {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com"
      },
      "shared_link": {
        "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
        "vanity_url": "https://acme.app.box.com/v/my_url/",
        "vanity_name": "my_url",
        "access": "open",
        "effective_access": "company",
        "effective_permission": "can_download",
        "unshared_at": "2018-04-13T13:53:23-07:00",
        "is_password_enabled": true,
        "permissions": {
          "can_download": true,
          "can_preview": true,
          "can_edit": false
        },
        "download_count": 3,
        "preview_count": 3
      },
      "parent": {
        "id": "12345",
        "etag": "1",
        "type": "folder",
        "sequence_id": "3",
        "name": "Contracts"
      },
      "item_status": "active",
      "version_number": "1",
      "comment_count": 10,
      "permissions": {
        "can_delete": true,
        "can_download": true,
        "can_invite_collaborator": true,
        "can_rename": true,
        "can_set_share_access": true,
        "can_share": true,
        "can_annotate": true,
        "can_comment": true,
        "can_preview": true,
        "can_upload": true,
        "can_view_annotations_all": true,
        "can_view_annotations_self": true,
        "can_apply_watermark": true
      },
      "tags": [
        "approved"
      ],
      "lock": {
        "id": "11446498",
        "type": "lock",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "expired_at": "2012-12-12T10:53:43-08:00",
        "is_download_prevented": true,
        "app_type": "office_wopiplus"
      },
      "extension": "pdf",
      "is_package": true,
      "expiring_embed_link": {
        "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
        "expires_in": 3600,
        "token_type": "bearer",
        "restricted_to": [
          {
            "scope": "item_download",
            "object": {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          }
        ],
        "url": "https://cloud.app.box.com/preview/expiring_embed/..."
      },
      "watermark_info": {
        "is_watermarked": true,
        "is_watermark_inherited": false,
        "is_watermarked_by_access_policy": false
      },
      "is_accessible_via_shared_link": true,
      "allowed_invitee_roles": [
        "editor"
      ],
      "is_externally_owned": true,
      "has_collaborations": true,
      "metadata": {
        "enterprise_27335": {
          "marketingCollateral": {
            "$canEdit": true,
            "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
            "$parent": "folder_59449484661",
            "$scope": "enterprise_27335",
            "$template": "marketingCollateral",
            "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
            "$typeVersion": 2,
            "$version": 1
          }
        }
      },
      "expires_at": "2012-12-12T10:53:43-08:00",
      "representations": {
        "entries": [
          {
            "content": {
              "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
            },
            "info": {
              "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
            },
            "properties": {
              "dimensions": "2048x2048",
              "paged": "true",
              "thumb": "true"
            },
            "representation": "png",
            "status": {
              "state": "success"
            }
          }
        ]
      },
      "classification": {
        "name": "Top Secret",
        "definition": "Content that should not be shared outside the company.",
        "color": "#FF0000"
      },
      "uploader_display_name": "Ellis Wiggins",
      "disposition_at": "2012-12-12T10:53:43-08:00",
      "shared_link_permission_options": [
        "can_preview"
      ],
      "is_associated_with_app_item": true,
      "collections": [
        {
          "id": "11446498",
          "type": "collection",
          "name": "Favorites",
          "collection_type": "favorites"
        }
      ],
      "is_download_available": true,
      "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
      "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
      "allowed_shared_link_access_levels": [
        "open"
      ]
    },
    "type": "search_result"
  }
  ```
</Accordion>

## Search Results

A list of files, folders and web links that matched the search query.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than `total_count`. |
  | `limit` | `integer` | No | The limit that was used for this search. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter used. |
  | `type` | `enum<string>` | Yes | Specifies the response as search result items without shared links. Available options: `search_results_items`. |
  | `entries` | array of `Search results item` | No | The search results for the query provided. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "type": "search_results_items",
    "entries": [
      {
        "id": "12345",
        "etag": "1",
        "type": "file",
        "sequence_id": "3",
        "name": "Contract.pdf",
        "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
        "file_version": {
          "id": "12345",
          "type": "file_version",
          "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
        },
        "description": "Contract for Q1 renewal",
        "size": 629644,
        "path_collection": {
          "total_count": 1,
          "entries": [
            {
              "id": "12345",
              "etag": "1",
              "type": "folder",
              "sequence_id": "3",
              "name": "Contracts"
            }
          ]
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "trashed_at": "2012-12-12T10:53:43-08:00",
        "purged_at": "2012-12-12T10:53:43-08:00",
        "content_created_at": "2012-12-12T10:53:43-08:00",
        "content_modified_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "modified_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "owned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "shared_link": {
          "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
          "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
          "vanity_url": "https://acme.app.box.com/v/my_url/",
          "vanity_name": "my_url",
          "access": "open",
          "effective_access": "company",
          "effective_permission": "can_download",
          "unshared_at": "2018-04-13T13:53:23-07:00",
          "is_password_enabled": true,
          "permissions": {
            "can_download": true,
            "can_preview": true,
            "can_edit": false
          },
          "download_count": 3,
          "preview_count": 3
        },
        "parent": {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        },
        "item_status": "active",
        "version_number": "1",
        "comment_count": 10,
        "permissions": {
          "can_delete": true,
          "can_download": true,
          "can_invite_collaborator": true,
          "can_rename": true,
          "can_set_share_access": true,
          "can_share": true,
          "can_annotate": true,
          "can_comment": true,
          "can_preview": true,
          "can_upload": true,
          "can_view_annotations_all": true,
          "can_view_annotations_self": true,
          "can_apply_watermark": true
        },
        "tags": [
          "approved"
        ],
        "lock": {
          "id": "11446498",
          "type": "lock",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "expired_at": "2012-12-12T10:53:43-08:00",
          "is_download_prevented": true,
          "app_type": "office_wopiplus"
        },
        "extension": "pdf",
        "is_package": true,
        "expiring_embed_link": {
          "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
          "expires_in": 3600,
          "token_type": "bearer",
          "restricted_to": [
            {
              "scope": "item_download",
              "object": {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            }
          ],
          "url": "https://cloud.app.box.com/preview/expiring_embed/..."
        },
        "watermark_info": {
          "is_watermarked": true,
          "is_watermark_inherited": false,
          "is_watermarked_by_access_policy": false
        },
        "is_accessible_via_shared_link": true,
        "allowed_invitee_roles": [
          "editor"
        ],
        "is_externally_owned": true,
        "has_collaborations": true,
        "metadata": {
          "enterprise_27335": {
            "marketingCollateral": {
              "$canEdit": true,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_59449484661",
              "$scope": "enterprise_27335",
              "$template": "marketingCollateral",
              "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1
            }
          }
        },
        "expires_at": "2012-12-12T10:53:43-08:00",
        "representations": {
          "entries": [
            {
              "content": {
                "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
              },
              "info": {
                "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
              },
              "properties": {
                "dimensions": "2048x2048",
                "paged": "true",
                "thumb": "true"
              },
              "representation": "png",
              "status": {
                "state": "success"
              }
            }
          ]
        },
        "classification": {
          "name": "Top Secret",
          "definition": "Content that should not be shared outside the company.",
          "color": "#FF0000"
        },
        "uploader_display_name": "Ellis Wiggins",
        "disposition_at": "2012-12-12T10:53:43-08:00",
        "shared_link_permission_options": [
          "can_preview"
        ],
        "is_associated_with_app_item": true,
        "collections": [
          {
            "id": "11446498",
            "type": "collection",
            "name": "Favorites",
            "collection_type": "favorites"
          }
        ],
        "is_download_available": true,
        "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
        "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
        "allowed_shared_link_access_levels": [
          "open"
        ]
      }
    ]
  }
  ```
</Accordion>

## Search Results (including Shared Links)

A list of files, folders and web links that matched the search query, including the additional information about any shared links through which the item has been shared with the user. This response format is only returned when the `include_recent_shared_links` query parameter has been set to `true`.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the search results. The total number of entries in the collection may be less than `total_count`. |
  | `limit` | `integer` | No | The limit that was used for this search. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter used. |
  | `type` | `enum<string>` | Yes | Specifies the response as search result items with shared links. Available options: `search_results_with_shared_links`. |
  | `entries` | array of [Search Result (including Shared Link)](#search-result-including-shared-link) | No | The search results for the query provided, including the additional information about any shared links through which the item has been shared with the user. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "type": "search_results_with_shared_links",
    "entries": [
      {
        "accessible_via_shared_link": "https://www.box.com/s/vspke7y05sb214wjokpk",
        "item": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          },
          "description": "Contract for Q1 renewal",
          "size": 629644,
          "path_collection": {
            "total_count": 1,
            "entries": [
              {
                "id": "12345",
                "etag": "1",
                "type": "folder",
                "sequence_id": "3",
                "name": "Contracts"
              }
            ]
          },
          "created_at": "2012-12-12T10:53:43-08:00",
          "modified_at": "2012-12-12T10:53:43-08:00",
          "trashed_at": "2012-12-12T10:53:43-08:00",
          "purged_at": "2012-12-12T10:53:43-08:00",
          "content_created_at": "2012-12-12T10:53:43-08:00",
          "content_modified_at": "2012-12-12T10:53:43-08:00",
          "created_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "modified_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "owned_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "shared_link": {
            "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
            "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
            "vanity_url": "https://acme.app.box.com/v/my_url/",
            "vanity_name": "my_url",
            "access": "open",
            "effective_access": "company",
            "effective_permission": "can_download",
            "unshared_at": "2018-04-13T13:53:23-07:00",
            "is_password_enabled": true,
            "permissions": {
              "can_download": true,
              "can_preview": true,
              "can_edit": false
            },
            "download_count": 3,
            "preview_count": 3
          },
          "parent": {
            "id": "12345",
            "etag": "1",
            "type": "folder",
            "sequence_id": "3",
            "name": "Contracts"
          },
          "item_status": "active",
          "version_number": "1",
          "comment_count": 10,
          "permissions": {
            "can_delete": true,
            "can_download": true,
            "can_invite_collaborator": true,
            "can_rename": true,
            "can_set_share_access": true,
            "can_share": true,
            "can_annotate": true,
            "can_comment": true,
            "can_preview": true,
            "can_upload": true,
            "can_view_annotations_all": true,
            "can_view_annotations_self": true,
            "can_apply_watermark": true
          },
          "tags": [
            "approved"
          ],
          "lock": {
            "id": "11446498",
            "type": "lock",
            "created_by": {
              "id": "11446498",
              "type": "user",
              "name": "Aaron Levie",
              "login": "ceo@example.com"
            },
            "created_at": "2012-12-12T10:53:43-08:00",
            "expired_at": "2012-12-12T10:53:43-08:00",
            "is_download_prevented": true,
            "app_type": "office_wopiplus"
          },
          "extension": "pdf",
          "is_package": true,
          "expiring_embed_link": {
            "access_token": "c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ",
            "expires_in": 3600,
            "token_type": "bearer",
            "restricted_to": [
              {
                "scope": "item_download",
                "object": {
                  "id": "12345",
                  "etag": "1",
                  "type": "folder",
                  "sequence_id": "3",
                  "name": "Contracts"
                }
              }
            ],
            "url": "https://cloud.app.box.com/preview/expiring_embed/..."
          },
          "watermark_info": {
            "is_watermarked": true,
            "is_watermark_inherited": false,
            "is_watermarked_by_access_policy": false
          },
          "is_accessible_via_shared_link": true,
          "allowed_invitee_roles": [
            "editor"
          ],
          "is_externally_owned": true,
          "has_collaborations": true,
          "metadata": {
            "enterprise_27335": {
              "marketingCollateral": {
                "$canEdit": true,
                "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
                "$parent": "folder_59449484661",
                "$scope": "enterprise_27335",
                "$template": "marketingCollateral",
                "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
                "$typeVersion": 2,
                "$version": 1
              }
            }
          },
          "expires_at": "2012-12-12T10:53:43-08:00",
          "representations": {
            "entries": [
              {
                "content": {
                  "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048/content/{+asset_path}?watermark_content=4567"
                },
                "info": {
                  "url": "https://api.box.com/2.0/internal_files/123/versions/345/representations/png_paged_2048x2048"
                },
                "properties": {
                  "dimensions": "2048x2048",
                  "paged": "true",
                  "thumb": "true"
                },
                "representation": "png",
                "status": {
                  "state": "success"
                }
              }
            ]
          },
          "classification": {
            "name": "Top Secret",
            "definition": "Content that should not be shared outside the company.",
            "color": "#FF0000"
          },
          "uploader_display_name": "Ellis Wiggins",
          "disposition_at": "2012-12-12T10:53:43-08:00",
          "shared_link_permission_options": [
            "can_preview"
          ],
          "is_associated_with_app_item": true,
          "collections": [
            {
              "id": "11446498",
              "type": "collection",
              "name": "Favorites",
              "collection_type": "favorites"
            }
          ],
          "is_download_available": true,
          "download_url": "https://dl.boxcloud.com/d/1/example_token/download",
          "authenticated_download_url": "https://api.box.com/2.0/files/12345/content",
          "allowed_shared_link_access_levels": [
            "open"
          ]
        },
        "type": "search_result"
      }
    ]
  }
  ```
</Accordion>


# Session termination resources
Source: https://developer.box.com/reference/session-termination-resources



Session termination API is used to validate the roles and permissions of the group, and creates asynchronous jobs to terminate the group's sessions.

## Session termination message

A message informing about the termination job status.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `message` | `string` | No | The unique identifier for the termination job status. |

  ```json Example theme={null}
  {
    "message": "Request is successful, please check the admin\nevents for the status of the job"
  }
  ```
</Accordion>


# Shield information barrier reports resources
Source: https://developer.box.com/reference/shield-information-barrier-reports-resources



Shield information barrier reports contain information on what existing collaborations will be removed permanently when the information barrier is enabled.

## List of Shield Information Barrier Reports

A list of shield barrier reports.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `entries` | array of [Shield information barrier report](#shield-information-barrier-report) | No | A list of shield information barrier reports. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "entries": [
      {
        "id": "11446498",
        "type": "shield_information_barrier_report",
        "shield_information_barrier": {
          "shield_information_barrier": {
            "id": "11446498",
            "type": "shield_information_barrier"
          }
        },
        "status": "pending",
        "details": {
          "details": {
            "folder_id": "124235"
          }
        },
        "created_at": "2020-06-26T18:44:45.869Z",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "updated_at": "2020-07-26T18:44:45.869Z"
      }
    ]
  }
  ```
</Accordion>

## Shield information barrier reference

A shield information barrier reference for requests and responses.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `shield_information_barrier` | [Shield information barrier (Base)](/reference/shield-information-barriers-resources#shield-information-barrier-base) | No | |

  ```json Example theme={null}
  {
    "shield_information_barrier": {
      "id": "11446498",
      "type": "shield_information_barrier"
    }
  }
  ```
</Accordion>

## Shield information barrier report

A standard representation of a shield information barrier report object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier report. |
  | `type` | `enum<string>` | No | The type of the shield information barrier report. Available options: `shield_information_barrier_report`. |
  | `shield_information_barrier` | [Shield information barrier reference](#shield-information-barrier-reference) | No | |
  | `status` | `enum<string>` | No | Status of the shield information report. Available options: `pending`, `error`, `done`, `cancelled`. |
  | `details` | [Shield information barrier report details](#shield-information-barrier-report-details) | No | |
  | `created_at` | `string` | No | ISO date time string when this shield information barrier report object was created. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who created this shield information barrier report. |
  | `updated_at` | `string` | No | ISO date time string when this shield information barrier report was updated. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier_report",
    "shield_information_barrier": {
      "shield_information_barrier": {
        "id": "11446498",
        "type": "shield_information_barrier"
      }
    },
    "status": "pending",
    "details": {
      "details": {
        "folder_id": "124235"
      }
    },
    "created_at": "2020-06-26T18:44:45.869Z",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "updated_at": "2020-07-26T18:44:45.869Z"
  }
  ```
</Accordion>

## Shield information barrier report (Base)

A base representation of a shield information barrier report object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier report. |
  | `type` | `enum<string>` | No | The type of the shield information barrier report. Available options: `shield_information_barrier_report`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier_report"
  }
  ```
</Accordion>

## Shield information barrier report details

Indicates which folder the report file is located and any errors when generating the report.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `details` | `object` | No | |

  ```json Example theme={null}
  {
    "details": {
      "folder_id": "124235"
    }
  }
  ```
</Accordion>


# Shield information barrier segment members resources
Source: https://developer.box.com/reference/shield-information-barrier-segment-members-resources



Shield information barrier segment member represents a user that is assigned to a specific segment.

## List of Shield Information Barrier Segment Members

List of Shield Information Barrier Member objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `entries` | array of [Shield information barrier segment member](#shield-information-barrier-segment-member) | No | A list of shield information barrier segment members. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "entries": [
      {
        "id": "11446498",
        "type": "shield_information_barrier_segment_member",
        "user": {
          "id": "11446498",
          "type": "user"
        },
        "shield_information_barrier": {
          "id": "11446498",
          "type": "shield_information_barrier"
        },
        "shield_information_barrier_segment": {
          "id": "432554",
          "type": "shield_information_barrier_segment"
        },
        "created_at": "2020-06-26T18:44:45.869Z",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "updated_at": "2020-07-26T18:44:45.869Z",
        "updated_by": {
          "id": "11446498",
          "type": "user"
        }
      }
    ]
  }
  ```
</Accordion>

## Shield information barrier segment member

A standard representation of a shield information barrier segment member object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier segment member. |
  | `type` | `enum<string>` | No | The type of the shield information barrier segment member. Available options: `shield_information_barrier_segment_member`. |
  | `user` | [User (Base)](/reference/users-resources#user-base) | No | The `type` and `id` of the requested shield information barrier segment member. |
  | `shield_information_barrier` | [Shield information barrier (Base)](/reference/shield-information-barriers-resources#shield-information-barrier-base) | No | |
  | `shield_information_barrier_segment` | `object` | No | The `type` and `id` of the requested shield information barrier segment. |
  | `created_at` | `string` | No | ISO date time string when this shield information barrier object was created. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who created this shield information barrier segment member. |
  | `updated_at` | `string` | No | ISO date time string when this shield information barrier segment Member was updated. |
  | `updated_by` | [User (Base)](/reference/users-resources#user-base) | No | The user that updated this shield information barrier segment Member. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier_segment_member",
    "user": {
      "id": "11446498",
      "type": "user"
    },
    "shield_information_barrier": {
      "id": "11446498",
      "type": "shield_information_barrier"
    },
    "shield_information_barrier_segment": {
      "id": "432554",
      "type": "shield_information_barrier_segment"
    },
    "created_at": "2020-06-26T18:44:45.869Z",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "updated_at": "2020-07-26T18:44:45.869Z",
    "updated_by": {
      "id": "11446498",
      "type": "user"
    }
  }
  ```
</Accordion>

## Shield information barrier segment member (Base)

A base representation of a shield information barrier segment member object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier segment member. |
  | `type` | `enum<string>` | No | The type of the shield information barrier segment member. Available options: `shield_information_barrier_segment_member`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier_segment_member"
  }
  ```
</Accordion>

## Shield information barrier segment member (Mini)

A mini representation of a shield information barrier segment member object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier segment member. |
  | `type` | `enum<string>` | No | The type of the shield information barrier segment member. Available options: `shield_information_barrier_segment_member`. |
  | `user` | [User (Base)](/reference/users-resources#user-base) | No | The `type` and `id` of the requested shield information barrier segment member. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier_segment_member",
    "user": {
      "id": "11446498",
      "type": "user"
    }
  }
  ```
</Accordion>


# User avatars resources
Source: https://developer.box.com/reference/avatars-resources



User avatars are JPG or PNG files uploaded to Box to represent the user image. They are then displayed in the user account.

## User avatar

A resource holding URLs to the avatar uploaded to a Box application.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `pic_urls` | `object` | No | Represents an object with user avatar URLs. |

  ```json Example theme={null}
  {
    "pic_urls": {
      "small": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks! pac3kv01!7B6R5cZLmurEV_xB-KkycPk8Oi7oENUX2O_qUtIuO4342CG IldyCto9hqiQP7uxqYU5V2w63Ft4ln4UVVLDtDZu903OqzkflY2O-Lq00 ubA29xU-RJ6b_KzJEWRYgUhX1zEl3dzWo12g8eWRE2rStf123DF7AYahNqM 1BmLmviL_nODc7SDQHedTXPAjxURUAra5BvtLe7B05AizbNXdPlCNp-LNh _S-eZ_RjDXcGO-MkRWd_3BOMHnvjf450t5BfKoJ15WhEfiMlfXH1tmouHXrsC 66cT6-pzF9E40Iir_zThqSlrFxzP_xcmXzHapr_k-0E2qr2TXp4iC396TSlEw\n",
      "large": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks\npac3kv01!lipGQlQQOtCTCoB6zCOArUjVWLFJtLr5tn6aOZMCybhRx0NNuFQbVI36nw\njtEk5YjUUz1KVdVuvU2yDhu_ftK_bvxeKP1Ffrx9vKGVvJ-UJc1z32p6n2CmFzzpc\ngSoX4pnPhFgydAL-u9jDspXUGElr-htDG_HPMiE9DZjqDueOxXHy8xe22wbaPAheC\nao1emv8r_fmufaUgSndeMYmyZj-KqOYsLBrBNgdeiK5tZmPOQggAEUmyQPkrd8W92TQ6sSlIp0r",
      "preview": "https://app.box.com/index.php?rm=pic_storage_auth&pic=euks!\npac3kv01!8UcNPweOOAWj2DtHk_dCQB4wJpzyPkl7mT5nHj5ZdjY92ejYCBBZc95--403b29CW\nk-8hSo_uBjh5h9QG42Ihu-cOZ-816sej1kof3SOm5gjn7qjMAx89cHjUaNK-6XasRqSNboenjZ\n04laZuV9vSH12BZGAYycIZvvQ5R66Go8xG5GTMARf2nBU84c4H_SL5iws-HeBS4oQJWOJh6FBl\nsSJDSTI74LGXqeZb3EY_As34VFC95F10uozoTOSubZmPYylPlaKXoKWk2f9wYQso1ZTN7sh-Gc\n9Kp43zMLhArIWhok0Im6FlRAuWOQ03KYgL-k4L5EZp4Gw6B7uqVRwcBbsTwMIorWq1g"
    }
  }
  ```
</Accordion>


# Uploads (Chunked) resources
Source: https://developer.box.com/reference/chunked-uploads-resources



The chunked upload endpoints support files from 20MB in size and allow an application to upload the file in parts, allowing for more control to catch any errors and retry parts individually.

## Upload part

The representation of an upload session chunk.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `part_id` | `string` | No | The unique ID of the chunk. |
  | `offset` | `integer` | No | The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file. |
  | `size` | `integer` | No | The size of the chunk in bytes. |
  | `sha1` | `string` | No | The SHA1 hash of the chunk. |

  ```json Example theme={null}
  {
    "part_id": "6F2D3486",
    "offset": 16777216,
    "size": 3222784,
    "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
  }
  ```
</Accordion>

## Upload part (Mini)

The basic representation of an upload session chunk.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `part_id` | `string` | No | The unique ID of the chunk. |
  | `offset` | `integer` | No | The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file. |
  | `size` | `integer` | No | The size of the chunk in bytes. |

  ```json Example theme={null}
  {
    "part_id": "6F2D3486",
    "offset": 16777216,
    "size": 3222784
  }
  ```
</Accordion>

## Upload part plan

Represents a planned upload part with `SHA-512` hash for upload session planning.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `offset` | `integer` | Yes | The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file. |
  | `size` | `integer` | Yes | The size of the chunk in bytes. |
  | `sha512` | `string` | Yes | The `SHA-512` hash of the chunk. |

  ```json Example theme={null}
  {
    "offset": 0,
    "size": 8388608,
    "sha512": "1f40fc92da241694750979ee6cf582f2d5d7c8b5d9c7f3b8a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1"
  }
  ```
</Accordion>

## Upload part plan hit

Represents a planned upload part that already exists on the server (cache hit).

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `offset` | `integer` | Yes | The offset of the chunk within the file in bytes. The lower bound of the position of the chunk within the file. |
  | `size` | `integer` | Yes | The size of the chunk in bytes. |
  | `sha512` | `string` | Yes | The `SHA-512` hash of the chunk. |
  | `part_id` | `string` | Yes | The unique ID of the chunk. |

  ```json Example theme={null}
  {
    "offset": 0,
    "size": 8388608,
    "sha512": "1f40fc92da241694750979ee6cf582f2d5d7c8b5d9c7f3b8a6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1",
    "part_id": "BFDF5379"
  }
  ```
</Accordion>

## Upload parts

A list of uploaded chunks for an upload session.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of [Upload part](#upload-part) | No | A list of uploaded chunks for an upload session. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "limit": 1000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "part_id": "6F2D3486",
        "offset": 16777216,
        "size": 3222784,
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    ]
  }
  ```
</Accordion>

## Upload session

An upload session for chunk uploading a file.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this session. |
  | `type` | `enum<string>` | No | The value will always be `upload_session`. Available options: `upload_session`. |
  | `session_expires_at` | `string` | No | The date and time when this session expires. |
  | `part_size` | `integer` | No | The size in bytes that must be used for all parts of of the upload. Only the last part is allowed to be of a smaller size. |
  | `total_parts` | `integer` | No | The total number of parts expected in this upload session, as determined by the file size and part size. |
  | `num_parts_processed` | `integer` | No | The number of parts that have been uploaded and processed by the server. This starts at `0`. When committing a file files, inspecting this property can provide insight if all parts have been uploaded correctly. |
  | `session_endpoints` | `object` | No | A list of endpoints for a chunked upload session. |

  ```json Example theme={null}
  {
    "id": "F971964745A5CD0C001BBE4E58196BFD",
    "type": "upload_session",
    "session_expires_at": "2012-12-12T10:53:43-08:00",
    "part_size": 1024,
    "total_parts": 1000,
    "num_parts_processed": 455,
    "session_endpoints": {
      "plan": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/plan",
      "upload_part": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
      "commit": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/commit",
      "abort": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
      "list_parts": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/parts",
      "status": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD",
      "log_event": "https://{box-upload-server}/api/2.0/files/upload_sessions/F971964745A5CD0C001BBE4E58196BFD/log"
    }
  }
  ```
</Accordion>

## Upload session plan request

Request body for planning an upload session. This allows checking which parts already exist on the server before uploading.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `parts` | array of [Upload part plan](#upload-part-plan) | Yes | The list of parts to check for existence. |

  ```json Example theme={null}
  {
    "parts": [
      {
        "offset": 0,
        "size": 8388608,
        "sha512": "1f40fc92da241694750979ee6cf582f2..."
      },
      {
        "offset": 8388608,
        "size": 8388608,
        "sha512": "b109f3bbbc244eb82441917ed06d618b..."
      }
    ]
  }
  ```
</Accordion>

## Upload session plan response

Response from planning an upload session. Contains information about which parts already exist (hits) and which need to be uploaded (misses).

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `upload_session_id` | `string` | Yes | The unique identifier for this upload session. |
  | `hits` | array of [Upload part plan hit](#upload-part-plan-hit) | Yes | Parts that already exist on the server and do not need to be uploaded again. |
  | `misses` | array of [Upload part plan](#upload-part-plan) | Yes | Parts that do not exist on the server and need to be uploaded. |

  ```json Example theme={null}
  {
    "upload_session_id": "F971964745A5CD0C001BBE4E58196BFD",
    "hits": [
      {
        "offset": 0,
        "size": 8388608,
        "sha512": "1f40fc92da241694750979ee6cf582f2...",
        "part_id": "BFDF5379"
      }
    ],
    "misses": [
      {
        "offset": 8388608,
        "size": 8388608,
        "sha512": "b109f3bbbc244eb82441917ed06d618b..."
      }
    ]
  }
  ```
</Accordion>

## Uploaded part

A chunk of a file uploaded as part of an upload session, as returned by some endpoints.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `part` | [Upload part](#upload-part) | No | |

  ```json Example theme={null}
  {
    "part": {
      "part_id": "6F2D3486",
      "offset": 16777216,
      "size": 3222784,
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    }
  }
  ```
</Accordion>


# Remove Box Skill cards from file
Source: https://developer.box.com/reference/delete-files-id-metadata-global-boxSkillsCards

box-openapi.json DELETE /files/{file_id}/metadata/global/boxSkillsCards
Removes any Box Skills cards metadata from a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Permanently remove file
Source: https://developer.box.com/reference/delete-files-id-trash

box-openapi.json DELETE /files/{file_id}/trash
Permanently deletes a file that is in the trash. This action cannot be undone.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove watermark from file
Source: https://developer.box.com/reference/delete-files-id-watermark

box-openapi.json DELETE /files/{file_id}/watermark
Removes the watermark from a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove upload session
Source: https://developer.box.com/reference/delete-files-upload-sessions-id

box-openapi.json DELETE /files/upload_sessions/{upload_session_id}
Abort an upload session and discard all data uploaded.

This cannot be reversed.

The actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Permanently remove folder
Source: https://developer.box.com/reference/delete-folders-id-trash

box-openapi.json DELETE /folders/{folder_id}/trash
Permanently deletes a folder that is in the trash. This action cannot be undone.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete shield information barrier segment member by ID
Source: https://developer.box.com/reference/delete-shield-information-barrier-segment-members-id

box-openapi.json DELETE /shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}
Deletes a shield information barrier segment member based on provided ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete shield information barrier segment restriction by ID
Source: https://developer.box.com/reference/delete-shield-information-barrier-segment-restrictions-id

box-openapi.json DELETE /shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}
Delete shield information barrier segment restriction based on provided ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete shield information barrier segment
Source: https://developer.box.com/reference/delete-shield-information-barrier-segments-id

box-openapi.json DELETE /shield_information_barrier_segments/{shield_information_barrier_segment_id}
Deletes the shield information barrier segment based on provided ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Unassign storage policy
Source: https://developer.box.com/reference/delete-storage-policy-assignments-id

box-openapi.json DELETE /storage_policy_assignments/{storage_policy_assignment_id}
Delete a storage policy assignment.

Deleting a storage policy assignment on a user will have the user inherit the enterprise's default storage policy.

There is a rate limit for calling this endpoint of only twice per user in a 24 hour time frame.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Unassign task
Source: https://developer.box.com/reference/delete-task-assignments-id

box-openapi.json DELETE /task_assignments/{task_assignment_id}
Deletes a specific task assignment.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove task
Source: https://developer.box.com/reference/delete-tasks-id

box-openapi.json DELETE /tasks/{task_id}
Removes a task from a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete user
Source: https://developer.box.com/reference/delete-users-id

box-openapi.json DELETE /users/{user_id}
Deletes a user. By default, this operation fails if the user still owns any content. To proceed, move their owned content first, or use the `force` parameter to delete the user and their files.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete user avatar
Source: https://developer.box.com/reference/delete-users-id-avatar

box-openapi.json DELETE /users/{user_id}/avatar
Removes an existing user avatar. You cannot reverse this operation.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Permanently remove web link
Source: https://developer.box.com/reference/delete-web-links-id-trash

box-openapi.json DELETE /web_links/{web_link_id}/trash
Permanently deletes a web link that is in the trash. This action cannot be undone.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Watermarks (Files) resources
Source: https://developer.box.com/reference/file-watermarks-resources



A watermark is a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over the file.

## Watermark

A watermark is a semi-transparent overlay on an embedded file preview that displays a viewer's email address or user ID and the time of access over a file's content.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `watermark` | `object` | No | |

  ```json Example theme={null}
  {
    "watermark": {
      "created_at": "2012-12-12T10:53:43-08:00",
      "modified_at": "2012-12-12T10:53:43-08:00"
    }
  }
  ```
</Accordion>


# List Box Skill cards on file
Source: https://developer.box.com/reference/get-files-id-metadata-global-boxSkillsCards

box-openapi.json GET /files/{file_id}/metadata/global/boxSkillsCards
List the Box Skills metadata cards that are attached to a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List tasks on file
Source: https://developer.box.com/reference/get-files-id-tasks

box-openapi.json GET /files/{file_id}/tasks
Retrieves a list of all the tasks for a file. This endpoint does not support pagination.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get trashed file
Source: https://developer.box.com/reference/get-files-id-trash

box-openapi.json GET /files/{file_id}/trash
Retrieves a file that has been moved to the trash.

Please note that only if the file itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](/reference/get-folders-id-trash) API.

To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](/reference/get-folders-trash-items/) API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get watermark on file
Source: https://developer.box.com/reference/get-files-id-watermark

box-openapi.json GET /files/{file_id}/watermark
Retrieve the watermark for a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get upload session
Source: https://developer.box.com/reference/get-files-upload-sessions-id

box-openapi.json GET /files/upload_sessions/{upload_session_id}
Return information about an upload session.

The actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List parts
Source: https://developer.box.com/reference/get-files-upload-sessions-id-parts

box-openapi.json GET /files/upload_sessions/{upload_session_id}/parts
Return a list of the chunks uploaded to the upload session so far.

The actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get trashed folder
Source: https://developer.box.com/reference/get-folders-id-trash

box-openapi.json GET /folders/{folder_id}/trash
Retrieves a folder that has been moved to the trash.

Please note that only if the folder itself has been moved to the trash can it be retrieved with this API call. If instead one of its parent folders was moved to the trash, only that folder can be inspected using the [`GET /folders/:id/trash`](/reference/get-folders-id-trash) API.

To list all items that have been moved to the trash, please use the [`GET /folders/trash/items`](/reference/get-folders-trash-items/) API.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get watermark for folder
Source: https://developer.box.com/reference/get-folders-id-watermark

box-openapi.json GET /folders/{folder_id}/watermark
Retrieve the watermark for a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List trashed items
Source: https://developer.box.com/reference/get-folders-trash-items

box-openapi.json GET /folders/trash/items
Retrieves the files and folders that have been moved to the trash.

Any attribute in the full files or folders objects can be passed in with the `fields` parameter to retrieve those specific attributes that are not returned by default.

This endpoint defaults to use offset-based pagination, yet also supports marker-based pagination using the `marker` parameter.

The number of entries returned may be less than `total_count`. For example, if a user deletes items from a shared folder and is later removed as a collaborator, those deleted items will no longer appear in this endpoint’s results, even though they are still included in `total_count`.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List shield information barrier segment members
Source: https://developer.box.com/reference/get-shield-information-barrier-segment-members

box-openapi.json GET /shield_information_barrier_segment_members
Lists shield information barrier segment members based on provided segment IDs.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get shield information barrier segment member by ID
Source: https://developer.box.com/reference/get-shield-information-barrier-segment-members-id

box-openapi.json GET /shield_information_barrier_segment_members/{shield_information_barrier_segment_member_id}
Retrieves a shield information barrier segment member by its ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List shield information barrier segment restrictions
Source: https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions

box-openapi.json GET /shield_information_barrier_segment_restrictions
Lists shield information barrier segment restrictions based on provided segment ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get shield information barrier segment restriction by ID
Source: https://developer.box.com/reference/get-shield-information-barrier-segment-restrictions-id

box-openapi.json GET /shield_information_barrier_segment_restrictions/{shield_information_barrier_segment_restriction_id}
Retrieves a shield information barrier segment restriction based on provided ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List shield information barrier segments
Source: https://developer.box.com/reference/get-shield-information-barrier-segments

box-openapi.json GET /shield_information_barrier_segments
Retrieves a list of shield information barrier segment objects for the specified Information Barrier ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get shield information barrier segment with specified ID
Source: https://developer.box.com/reference/get-shield-information-barrier-segments-id

box-openapi.json GET /shield_information_barrier_segments/{shield_information_barrier_segment_id}
Retrieves shield information barrier segment based on provided ID..

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List shield information barriers
Source: https://developer.box.com/reference/get-shield-information-barriers

box-openapi.json GET /shield_information_barriers
Retrieves a list of shield information barrier objects for the enterprise of JWT.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get shield information barrier with specified ID
Source: https://developer.box.com/reference/get-shield-information-barriers-id

box-openapi.json GET /shield_information_barriers/{shield_information_barrier_id}
Get shield information barrier based on provided ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List storage policies
Source: https://developer.box.com/reference/get-storage-policies

box-openapi.json GET /storage_policies
Fetches all the storage policies in the enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get storage policy
Source: https://developer.box.com/reference/get-storage-policies-id

box-openapi.json GET /storage_policies/{storage_policy_id}
Fetches a specific storage policy.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List storage policy assignments
Source: https://developer.box.com/reference/get-storage-policy-assignments

box-openapi.json GET /storage_policy_assignments
Fetches all the storage policy assignment for an enterprise or user.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get storage policy assignment
Source: https://developer.box.com/reference/get-storage-policy-assignments-id

box-openapi.json GET /storage_policy_assignments/{storage_policy_assignment_id}
Fetches a specific storage policy assignment.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get task assignment
Source: https://developer.box.com/reference/get-task-assignments-id

box-openapi.json GET /task_assignments/{task_assignment_id}
Retrieves information about a task assignment.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get task
Source: https://developer.box.com/reference/get-tasks-id

box-openapi.json GET /tasks/{task_id}
Retrieves information about a specific task.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List task assignments
Source: https://developer.box.com/reference/get-tasks-id-assignments

box-openapi.json GET /tasks/{task_id}/assignments
Lists all of the assignments for a given task.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List terms of service user statuses
Source: https://developer.box.com/reference/get-terms-of-service-user-statuses

box-openapi.json GET /terms_of_service_user_statuses
Retrieves an overview of users and their status for a terms of service, including Whether they have accepted the terms and when.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List terms of services
Source: https://developer.box.com/reference/get-terms-of-services

box-openapi.json GET /terms_of_services
Returns the current terms of service text and settings for the enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get terms of service
Source: https://developer.box.com/reference/get-terms-of-services-id

box-openapi.json GET /terms_of_services/{terms_of_service_id}
Fetches a specific terms of service.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List enterprise users
Source: https://developer.box.com/reference/get-users

box-openapi.json GET /users
Returns a list of all users for the Enterprise along with their `user_id`, `public_name`, and `login`.

The application and the authenticated user need to have the permission to look up users in the entire enterprise.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get user
Source: https://developer.box.com/reference/get-users-id

box-openapi.json GET /users/{user_id}
Retrieves information about a user in the enterprise.

The application and the authenticated user need to have the permission to look up users in the entire enterprise.

This endpoint also returns a limited set of information for external users who are collaborated on content owned by the enterprise for authenticated users with the right scopes. In this case, disallowed fields will return null instead.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get user avatar
Source: https://developer.box.com/reference/get-users-id-avatar

box-openapi.json GET /users/{user_id}/avatar
Retrieves an image of a the user's avatar.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get current user
Source: https://developer.box.com/reference/get-users-me

box-openapi.json GET /users/me
Retrieves information about the user who is currently authenticated.

In the case of a client-side authenticated OAuth 2.0 application this will be the user who authorized the app.

In the case of a JWT, server-side authenticated application this will be the service account that belongs to the application by default.

Use the `As-User` header to change who this API call is made on behalf of.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get trashed web link
Source: https://developer.box.com/reference/get-web-links-id-trash

box-openapi.json GET /web_links/{web_link_id}/trash
Retrieves a web link that has been moved to the trash.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Preflight check before upload
Source: https://developer.box.com/reference/options-files-content

/box-openapi.json OPTIONS /files/content

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Upload file
Source: https://developer.box.com/reference/post-files-content

box-openapi.json POST /files/content
Uploads a small file to Box. For file sizes over 50MB we recommend using the Chunk Upload APIs.

The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Restore file
Source: https://developer.box.com/reference/post-files-id

box-openapi.json POST /files/{file_id}
Restores a file that has been moved to the trash.

An optional new parent ID can be provided to restore the file to in case the original folder has been deleted.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Upload file version
Source: https://developer.box.com/reference/post-files-id-content

box-openapi.json POST /files/{file_id}/content
Update a file's content. For file sizes over 50MB we recommend using the Chunk Upload APIs.

The `attributes` part of the body must come **before** the `file` part. Requests that do not follow this format when uploading the file will receive a HTTP `400` error with a `metadata_after_file_contents` error code.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create Box Skill cards on file
Source: https://developer.box.com/reference/post-files-id-metadata-global-boxSkillsCards

box-openapi.json POST /files/{file_id}/metadata/global/boxSkillsCards
Applies one or more Box Skills metadata cards to a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create upload session for existing file
Source: https://developer.box.com/reference/post-files-id-upload-sessions

box-openapi.json POST /files/{file_id}/upload_sessions
Creates an upload session for an existing file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create upload session
Source: https://developer.box.com/reference/post-files-upload-sessions

box-openapi.json POST /files/upload_sessions
Creates an upload session for a new file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Commit upload session
Source: https://developer.box.com/reference/post-files-upload-sessions-id-commit

box-openapi.json POST /files/upload_sessions/{upload_session_id}/commit
Close an upload session and create a file from the uploaded chunks.

The actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Plan upload session
Source: https://developer.box.com/reference/post-files-upload-sessions-id-plan

box-openapi.json POST /files/upload_sessions/{upload_session_id}/plan
Plan an upload session by checking which parts already exist on the server. This endpoint allows clients to optimize uploads by skipping parts that have already been uploaded (cache hits) and only uploading missing parts.

The actual endpoint URL is returned by the [`Create upload session`](e://post-files-upload-sessions) and [`Get upload session`](e://get-files-upload-sessions-id) endpoints.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Restore folder
Source: https://developer.box.com/reference/post-folders-id

box-openapi.json POST /folders/{folder_id}
Restores a folder that has been moved to the trash.

An optional new parent ID can be provided to restore the folder to in case the original folder has been deleted.

During this operation, part of the file tree will be locked, mainly the source folder and all of its descendants, as well as the destination folder.

For the duration of the operation, no other move, copy, delete, or restore operation can performed on any of the locked folders.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create shield information barrier segment member
Source: https://developer.box.com/reference/post-shield-information-barrier-segment-members

box-openapi.json POST /shield_information_barrier_segment_members
Creates a new shield information barrier segment member.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create shield information barrier segment restriction
Source: https://developer.box.com/reference/post-shield-information-barrier-segment-restrictions

box-openapi.json POST /shield_information_barrier_segment_restrictions
Creates a shield information barrier segment restriction object.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create shield information barrier segment
Source: https://developer.box.com/reference/post-shield-information-barrier-segments

box-openapi.json POST /shield_information_barrier_segments
Creates a shield information barrier segment.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create shield information barrier
Source: https://developer.box.com/reference/post-shield-information-barriers

box-openapi.json POST /shield_information_barriers
Creates a shield information barrier to separate individuals/groups within the same firm and prevents confidential information passing between them.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add changed status of shield information barrier with specified ID
Source: https://developer.box.com/reference/post-shield-information-barriers-change-status

box-openapi.json POST /shield_information_barriers/change_status
Change status of shield information barrier with the specified ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Assign storage policy
Source: https://developer.box.com/reference/post-storage-policy-assignments

box-openapi.json POST /storage_policy_assignments
Creates a storage policy assignment for an enterprise or user.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Assign task
Source: https://developer.box.com/reference/post-task-assignments

box-openapi.json POST /task_assignments
Assigns a task to a user.

A task can be assigned to more than one user by creating multiple assignments.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create task
Source: https://developer.box.com/reference/post-tasks

box-openapi.json POST /tasks
Creates a single task on a file. This task is not assigned to any user and will need to be assigned separately.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create terms of service status for new user
Source: https://developer.box.com/reference/post-terms-of-service-user-statuses

box-openapi.json POST /terms_of_service_user_statuses
Sets the status for a terms of service for a user.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create terms of service
Source: https://developer.box.com/reference/post-terms-of-services

box-openapi.json POST /terms_of_services
Creates a terms of service for a given enterprise and type of user.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create user
Source: https://developer.box.com/reference/post-users

box-openapi.json POST /users
Creates a new managed user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Add or update user avatar
Source: https://developer.box.com/reference/post-users-id-avatar

box-openapi.json POST /users/{user_id}/avatar
Adds or updates a user avatar.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Restore web link
Source: https://developer.box.com/reference/post-web-links-id

box-openapi.json POST /web_links/{web_link_id}
Restores a web link that has been moved to the trash.

An optional new parent ID can be provided to restore the web link to in case the original folder has been deleted.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update Box Skill cards on file
Source: https://developer.box.com/reference/put-files-id-metadata-global-boxSkillsCards

box-openapi.json PUT /files/{file_id}/metadata/global/boxSkillsCards
Updates one or more Box Skills metadata cards to a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Apply watermark to file
Source: https://developer.box.com/reference/put-files-id-watermark

box-openapi.json PUT /files/{file_id}/watermark
Applies or update a watermark on a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Upload part of file
Source: https://developer.box.com/reference/put-files-upload-sessions-id

box-openapi.json PUT /files/upload_sessions/{upload_session_id}
Uploads a chunk of a file for an upload session.

The actual endpoint URL is returned by the [`Create upload session`](/reference/post-files-upload-sessions) and [`Get upload session`](/reference/get-files-upload-sessions-id) endpoints.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Apply watermark to folder
Source: https://developer.box.com/reference/put-folders-id-watermark

box-openapi.json PUT /folders/{folder_id}/watermark
Applies or update a watermark on a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update shield information barrier segment with specified ID
Source: https://developer.box.com/reference/put-shield-information-barrier-segments-id

box-openapi.json PUT /shield_information_barrier_segments/{shield_information_barrier_segment_id}
Updates the shield information barrier segment based on provided ID..

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update all Box Skill cards on file
Source: https://developer.box.com/reference/put-skill-invocations-id

box-openapi.json PUT /skill_invocations/{skill_id}
An alternative method that can be used to overwrite and update all Box Skill metadata cards on a file.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update storage policy assignment
Source: https://developer.box.com/reference/put-storage-policy-assignments-id

box-openapi.json PUT /storage_policy_assignments/{storage_policy_assignment_id}
Updates a specific storage policy assignment.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update task assignment
Source: https://developer.box.com/reference/put-task-assignments-id

box-openapi.json PUT /task_assignments/{task_assignment_id}
Updates a task assignment. This endpoint can be used to update the state of a task assigned to a user.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update task
Source: https://developer.box.com/reference/put-tasks-id

box-openapi.json PUT /tasks/{task_id}
Updates a task. This can be used to update a task's configuration, or to update its completion state.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update terms of service status for existing user
Source: https://developer.box.com/reference/put-terms-of-service-user-statuses-id

box-openapi.json PUT /terms_of_service_user_statuses/{terms_of_service_user_status_id}
Updates the status for a terms of service for a user.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update terms of service
Source: https://developer.box.com/reference/put-terms-of-services-id

box-openapi.json PUT /terms_of_services/{terms_of_service_id}
Updates a specific terms of service.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update user
Source: https://developer.box.com/reference/put-users-id

box-openapi.json PUT /users/{user_id}
Updates a managed or app user in an enterprise. This endpoint is only available to users and applications with the right admin permissions.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Transfer owned folders
Source: https://developer.box.com/reference/put-users-id-folders-0

box-openapi.json PUT /users/{user_id}/folders/0
Move all of the items (files, folders and workflows) owned by a user into another user's account.

Only the root folder (`0`) can be transferred.

Folders can only be moved across users by users with administrative permissions.

All existing shared links and folder-level collaborations are transferred during the operation. Please note that while collaborations at the individual file-level are transferred during the operation, the collaborations are deleted when the original user is deleted.

If the user has a large number of items across all folders, the call will be run asynchronously. If the operation is not completed within 10 minutes, the user will receive a 200 OK response, and the operation will continue running.

If the destination path has a metadata cascade policy attached to any of the parent folders, a metadata cascade operation will be kicked off asynchronously.

There is currently no way to check for when this operation is finished.

The destination folder's name will be in the format `{User}'s Files and Folders`, where `{User}` is the display name of the user.

To make this API call your application will need to have the "Read and write all files and folders stored in Box" scope enabled.

Please make sure the destination user has access to `Relay` or `Relay Lite`, and has access to the files and folders involved in the workflows being transferred.

Admins will receive an email when the operation is completed.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Shield information barrier segment restrictions resources
Source: https://developer.box.com/reference/shield-information-barrier-segment-restrictions-resources



Shield information barrier segment restriction is an access restriction based on the content (file or folder) owner.

## List of Shield Information Barrier Segment Restrictions

List of shield information barrier segment restriction objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `entries` | array of [Shield information barrier segment restriction](#shield-information-barrier-segment-restriction) | No | A list of shield information barrier segment restriction objects. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "entries": [
      {
        "type": "shield_information_barrier_segment_restriction",
        "id": "11446498",
        "shield_information_barrier_segment": {
          "id": "1910967",
          "type": "shield_information_barrier_segment"
        },
        "restricted_segment": {
          "id": "1910967",
          "type": "shield_information_barrier_segment"
        },
        "shield_information_barrier": {
          "id": "11446498",
          "type": "shield_information_barrier"
        },
        "created_at": "2020-06-26T18:44:45.869Z",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "updated_at": "2020-07-26T18:44:45.869Z",
        "updated_by": {
          "id": "11446498",
          "type": "user"
        }
      }
    ]
  }
  ```
</Accordion>

## Shield information barrier segment restriction

A standard representation of a segment restriction of a shield information barrier object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | No | Shield information barrier segment restriction. Available options: `shield_information_barrier_segment_restriction`. |
  | `id` | `string` | No | The unique identifier for the shield information barrier segment restriction. |
  | `shield_information_barrier_segment` | `object` | Yes | The `type` and `id` of the requested shield information barrier segment. |
  | `restricted_segment` | `object` | Yes | The `type` and `id` of the restricted shield information barrier segment. |
  | `shield_information_barrier` | [Shield information barrier (Base)](/reference/shield-information-barriers-resources#shield-information-barrier-base) | No | |
  | `created_at` | `string` | No | ISO date time string when this shield information barrier Segment Restriction object was created. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who created this shield information barrier segment Restriction. |
  | `updated_at` | `string` | No | ISO date time string when this shield information barrier segment Restriction was updated. |
  | `updated_by` | [User (Base)](/reference/users-resources#user-base) | No | The user that updated this shield information barrier segment Restriction. |

  ```json Example theme={null}
  {
    "type": "shield_information_barrier_segment_restriction",
    "id": "11446498",
    "shield_information_barrier_segment": {
      "id": "1910967",
      "type": "shield_information_barrier_segment"
    },
    "restricted_segment": {
      "id": "1910967",
      "type": "shield_information_barrier_segment"
    },
    "shield_information_barrier": {
      "id": "11446498",
      "type": "shield_information_barrier"
    },
    "created_at": "2020-06-26T18:44:45.869Z",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "updated_at": "2020-07-26T18:44:45.869Z",
    "updated_by": {
      "id": "11446498",
      "type": "user"
    }
  }
  ```
</Accordion>

## Shield information barrier segment restriction (Base)

A base representation of a segment restriction object for the shield information barrier.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | No | Shield information barrier segment restriction. Available options: `shield_information_barrier_segment_restriction`. |
  | `id` | `string` | No | The unique identifier for the shield information barrier segment restriction. |

  ```json Example theme={null}
  {
    "type": "shield_information_barrier_segment_restriction",
    "id": "11446498"
  }
  ```
</Accordion>

## Shield information barrier segment restriction (Mini)

A mini representation of a segment restriction object for the shield information barrier.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | No | Shield information barrier segment restriction. Available options: `shield_information_barrier_segment_restriction`. |
  | `id` | `string` | No | The unique identifier for the shield information barrier segment restriction. |
  | `shield_information_barrier_segment` | `object` | Yes | The `type` and `id` of the requested shield information barrier segment. |
  | `restricted_segment` | `object` | Yes | The `type` and `id` of the restricted shield information barrier segment. |

  ```json Example theme={null}
  {
    "type": "shield_information_barrier_segment_restriction",
    "id": "11446498",
    "shield_information_barrier_segment": {
      "id": "1910967",
      "type": "shield_information_barrier_segment"
    },
    "restricted_segment": {
      "id": "1910967",
      "type": "shield_information_barrier_segment"
    }
  }
  ```
</Accordion>


# Shield information barrier segments resources
Source: https://developer.box.com/reference/shield-information-barrier-segments-resources



Shield information barrier segment represents a defined group of users. A user can be a member of only one segment, which makes segments different from groups.

## List of Shield Information Barrier Segments

List of Shield Information Barrier Segment objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `entries` | array of [Shield information barrier segment](#shield-information-barrier-segment) | No | A list of shield information barrier segments. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "entries": [
      {
        "id": "11446498",
        "type": "shield_information_barrier_segment",
        "shield_information_barrier": {
          "id": "11446498",
          "type": "shield_information_barrier"
        },
        "name": "Investment Banking",
        "description": "'Corporate division that engages in advisory_based financial\n transactions on behalf of individuals, corporations, and governments.'",
        "created_at": "2020-06-26T18:44:45.869Z",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "updated_at": "2020-07-26T18:44:45.869Z",
        "updated_by": {
          "id": "11446498",
          "type": "user"
        }
      }
    ]
  }
  ```
</Accordion>

## Shield information barrier segment

A shield information barrier segment object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier segment. |
  | `type` | `enum<string>` | No | The type of the shield information barrier segment. Available options: `shield_information_barrier_segment`. |
  | `shield_information_barrier` | [Shield information barrier (Base)](/reference/shield-information-barriers-resources#shield-information-barrier-base) | No | |
  | `name` | `string` | No | Name of the shield information barrier segment. |
  | `description` | `string` | No | Description of the shield information barrier segment. |
  | `created_at` | `string` | No | ISO date time string when this shield information barrier object was created. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who created this shield information barrier segment. |
  | `updated_at` | `string` | No | ISO date time string when this shield information barrier segment was updated. |
  | `updated_by` | [User (Base)](/reference/users-resources#user-base) | No | The user that updated this shield information barrier segment. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier_segment",
    "shield_information_barrier": {
      "id": "11446498",
      "type": "shield_information_barrier"
    },
    "name": "Investment Banking",
    "description": "'Corporate division that engages in advisory_based financial\n transactions on behalf of individuals, corporations, and governments.'",
    "created_at": "2020-06-26T18:44:45.869Z",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "updated_at": "2020-07-26T18:44:45.869Z",
    "updated_by": {
      "id": "11446498",
      "type": "user"
    }
  }
  ```
</Accordion>


# Shield information barriers resources
Source: https://developer.box.com/reference/shield-information-barriers-resources



Shield information barrier in Box defines an ethical wall. An ethical wall is a mechanism that prevents exchanges or communication that could lead to conflicts of interest and therefore result in business activities ethically or legally questionable.

## List of Shield Information Barriers

List of Shield Information Barrier objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `entries` | array of [Shield information barrier](#shield-information-barrier) | No | A list of shield information barrier objects. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "entries": [
      {
        "id": "11446498",
        "type": "shield_information_barrier",
        "enterprise": {
          "id": "1910967",
          "type": "enterprise"
        },
        "status": "draft",
        "created_at": "2020-06-26T18:44:45.869Z",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "updated_at": "2020-07-26T18:44:45.869Z",
        "updated_by": {
          "id": "11446498",
          "type": "user"
        },
        "enabled_at": "2020-07-26T18:44:45.869Z",
        "enabled_by": {
          "id": "11446498",
          "type": "user"
        }
      }
    ]
  }
  ```
</Accordion>

## Shield information barrier

A standard representation of a shield information barrier object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier. |
  | `type` | `enum<string>` | No | The type of the shield information barrier. Available options: `shield_information_barrier`. |
  | `enterprise` | `Enterprise` | No | The `type` and `id` of enterprise this barrier is under. |
  | `status` | `enum<string>` | No | Status of the shield information barrier. Available options: `draft`, `pending`, `disabled`, `enabled`, `invalid`. |
  | `created_at` | `string` | No | ISO date time string when this shield information barrier object was created. |
  | `created_by` | [User (Base)](/reference/users-resources#user-base) | No | The user who created this shield information barrier. |
  | `updated_at` | `string` | No | ISO date time string when this shield information barrier was updated. |
  | `updated_by` | [User (Base)](/reference/users-resources#user-base) | No | The user that updated this shield information barrier. |
  | `enabled_at` | `string` | No | ISO date time string when this shield information barrier was enabled. |
  | `enabled_by` | [User (Base)](/reference/users-resources#user-base) | No | The user that enabled this shield information barrier. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier",
    "enterprise": {
      "id": "1910967",
      "type": "enterprise"
    },
    "status": "draft",
    "created_at": "2020-06-26T18:44:45.869Z",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "updated_at": "2020-07-26T18:44:45.869Z",
    "updated_by": {
      "id": "11446498",
      "type": "user"
    },
    "enabled_at": "2020-07-26T18:44:45.869Z",
    "enabled_by": {
      "id": "11446498",
      "type": "user"
    }
  }
  ```
</Accordion>

## Shield information barrier (Base)

A base representation of a shield information barrier object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the shield information barrier. |
  | `type` | `enum<string>` | No | The type of the shield information barrier. Available options: `shield_information_barrier`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "shield_information_barrier"
  }
  ```
</Accordion>


# Skills resources
Source: https://developer.box.com/reference/skills-resources



Box Skills are designed to allow custom processing of files uploaded to Box, with the intent of enhancing the underlying metadata of the file.

## Keyword Skill Card

A skill card that contains a set of keywords.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `created_at` | `string` | No | The optional date and time this card was created at. |
  | `type` | `enum<string>` | Yes | The value will always be `skill_card`. Available options: `skill_card`. |
  | `skill_card_type` | `enum<string>` | Yes | The value will always be `keyword`. Available options: `keyword`. |
  | `skill_card_title` | `object` | No | The title of the card. |
  | `skill` | `object` | Yes | The service that applied this metadata. |
  | `invocation` | `object` | Yes | The invocation of this service, used to track which instance of a service applied the metadata. |
  | `entries` | array of `object` | Yes | An list of entries in the metadata card. |

  ```json Example theme={null}
  {
    "created_at": "2018-04-13T13:53:23-07:00",
    "type": "skill_card",
    "skill_card_type": "keyword",
    "skill_card_title": {
      "code": "labels",
      "message": "Labels"
    },
    "skill": {
      "type": "service",
      "id": "image-recognition-service"
    },
    "invocation": {
      "type": "skill_invocation",
      "id": "image-recognition-service-123"
    },
    "entries": [
      {
        "text": "keyword1"
      }
    ]
  }
  ```
</Accordion>

## Skills metadata instance

The metadata assigned to a using for Box skills.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `$canEdit` | `boolean` | No | Whether the user can edit this metadata. |
  | `$id` | `string` | No | A UUID to identify the metadata object. |
  | `$parent` | `string` | No | An ID for the parent folder. |
  | `$scope` | `string` | No | An ID for the scope in which this template has been applied. |
  | `$template` | `string` | No | The name of the template. |
  | `$type` | `string` | No | A unique identifier for the "type" of this instance. This is an internal system property and should not be used by a client application. |
  | `$typeVersion` | `integer` | No | The last-known version of the template of the object. This is an internal system property and should not be used by a client application. |
  | `$version` | `integer` | No | The version of the metadata object. Starts at 0 and increases every time a user-defined property is modified. |
  | `cards` | array of `Box Skill card` | No | A list of Box Skill cards that have been applied to this file. |

  ```json Example theme={null}
  {
    "$canEdit": true,
    "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
    "$parent": "folder_59449484661,",
    "$scope": "enterprise_27335",
    "$template": "properties",
    "$type": "properties-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
    "$typeVersion": 2,
    "$version": 1,
    "cards": [
      {
        "created_at": "2018-04-13T13:53:23-07:00",
        "type": "skill_card",
        "skill_card_type": "keyword",
        "skill_card_title": {
          "code": "labels",
          "message": "Labels"
        },
        "skill": {
          "type": "service",
          "id": "image-recognition-service"
        },
        "invocation": {
          "type": "skill_invocation",
          "id": "image-recognition-service-123"
        },
        "entries": [
          {
            "text": "keyword1"
          }
        ]
      }
    ]
  }
  ```
</Accordion>

## Status Skill Card

A Box Skill metadata card that puts a status message in the metadata sidebar.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `created_at` | `string` | No | The optional date and time this card was created at. |
  | `type` | `enum<string>` | Yes | The value will always be `skill_card`. Available options: `skill_card`. |
  | `skill_card_type` | `enum<string>` | Yes | The value will always be `status`. Available options: `status`. |
  | `skill_card_title` | `object` | No | The title of the card. |
  | `status` | `object` | Yes | Sets the status of the skill. This can be used to show a message to the user while the Skill is processing the data, or if it was not able to process the file. |
  | `skill` | `object` | Yes | The service that applied this metadata. |
  | `invocation` | `object` | Yes | The invocation of this service, used to track which instance of a service applied the metadata. |

  ```json Example theme={null}
  {
    "created_at": "2018-04-13T13:53:23-07:00",
    "type": "skill_card",
    "skill_card_type": "status",
    "skill_card_title": {
      "code": "status",
      "message": "Status"
    },
    "status": {
      "code": "success",
      "message": "We're preparing to process your file. Please hold on!"
    },
    "skill": {
      "type": "service",
      "id": "image-recognition-service"
    },
    "invocation": {
      "type": "skill_invocation",
      "id": "image-recognition-service-123"
    }
  }
  ```
</Accordion>

## Timeline Skill Card

A Box Skill metadata card that places a list of images on a timeline.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `created_at` | `string` | No | The optional date and time this card was created at. |
  | `type` | `enum<string>` | Yes | The value will always be `skill_card`. Available options: `skill_card`. |
  | `skill_card_type` | `enum<string>` | Yes | The value will always be `timeline`. Available options: `timeline`. |
  | `skill_card_title` | `object` | No | The title of the card. |
  | `skill` | `object` | Yes | The service that applied this metadata. |
  | `invocation` | `object` | Yes | The invocation of this service, used to track which instance of a service applied the metadata. |
  | `duration` | `integer` | No | An total duration in seconds of the timeline. |
  | `entries` | array of `object` | Yes | A list of entries on the timeline. |

  ```json Example theme={null}
  {
    "created_at": "2018-04-13T13:53:23-07:00",
    "type": "skill_card",
    "skill_card_type": "timeline",
    "skill_card_title": {
      "code": "Faces",
      "message": "Faces"
    },
    "skill": {
      "type": "service",
      "id": "image-recognition-service"
    },
    "invocation": {
      "type": "skill_invocation",
      "id": "image-recognition-service-123"
    },
    "duration": 1000,
    "entries": [
      {
        "text": "John",
        "appears": [
          {
            "start": 1,
            "end": 20
          }
        ],
        "image_url": "https://example.com/image1.jpg"
      }
    ]
  }
  ```
</Accordion>

## Transcript Skill Card.

A Box Skill metadata card that adds a transcript to a file.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `created_at` | `string` | No | The optional date and time this card was created at. |
  | `type` | `enum<string>` | Yes | The value will always be `skill_card`. Available options: `skill_card`. |
  | `skill_card_type` | `enum<string>` | Yes | The value will always be `transcript`. Available options: `transcript`. |
  | `skill_card_title` | `object` | No | The title of the card. |
  | `skill` | `object` | Yes | The service that applied this metadata. |
  | `invocation` | `object` | Yes | The invocation of this service, used to track which instance of a service applied the metadata. |
  | `duration` | `integer` | No | An optional total duration in seconds. Used with a `skill_card_type` of `transcript` or `timeline`. |
  | `entries` | array of `object` | Yes | An list of entries for the card. This represents the individual entries of the transcription. |

  ```json Example theme={null}
  {
    "created_at": "2018-04-13T13:53:23-07:00",
    "type": "skill_card",
    "skill_card_type": "transcript",
    "skill_card_title": {
      "code": "my_transcripts",
      "message": "My Transcripts"
    },
    "skill": {
      "type": "service",
      "id": "transciption-service"
    },
    "invocation": {
      "type": "skill_invocation",
      "id": "transciption-service-123"
    },
    "duration": 1000,
    "entries": [
      {
        "text": "Hi, and welcome to this video...",
        "appears": [
          {
            "start": 1
          }
        ]
      }
    ]
  }
  ```
</Accordion>


# Standard and Zones Storage Policies resources
Source: https://developer.box.com/reference/storage-policies-resources



Storage policy assignment represents the storage zone for items in a given enterprise.

## Storage policies

A list of storage policies.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Storage policy](#storage-policy) | No | A list of storage policies. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "storage_policy",
        "name": "Montreal / Dublin"
      }
    ]
  }
  ```
</Accordion>

## Storage policy

The Storage Policy object describes the storage zone.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this storage policy. |
  | `type` | `enum<string>` | Yes | The value will always be `storage_policy`. Available options: `storage_policy`. |
  | `name` | `string` | No | A descriptive name of the region. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "storage_policy",
    "name": "Montreal / Dublin"
  }
  ```
</Accordion>

## Storage policy (Mini)

A mini description of a Storage Policy object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this storage policy. |
  | `type` | `enum<string>` | Yes | The value will always be `storage_policy`. Available options: `storage_policy`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "storage_policy"
  }
  ```
</Accordion>


# Standard and Zones Storage Policy Assignments resources
Source: https://developer.box.com/reference/storage-policy-assignments-resources



Storage policy assignment represents the relation between storage zone and the assigned item (for example a file stored in a specific zone).

## Storage policy assignment

The assignment of a storage policy to a user or enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for a storage policy assignment. |
  | `type` | `enum<string>` | Yes | The value will always be `storage_policy_assignment`. Available options: `storage_policy_assignment`. |
  | `storage_policy` | [Storage policy (Mini)](/reference/storage-policies-resources#storage-policy-mini) | No | The assigned storage policy. |
  | `assigned_to` | `object` | No | The bare basic reference for an object. |

  ```json Example theme={null}
  {
    "id": "ZW50ZXJwcmlzZV8xMjM0NTY3ODkw",
    "type": "storage_policy_assignment",
    "storage_policy": {
      "id": "11446498",
      "type": "storage_policy"
    },
    "assigned_to": {
      "id": "11446498",
      "type": "file"
    }
  }
  ```
</Accordion>

## Storage policy assignments

A list of storage policy assignments.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Storage policy assignment](#storage-policy-assignment) | No | A list of storage policy assignments. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "ZW50ZXJwcmlzZV8xMjM0NTY3ODkw",
        "type": "storage_policy_assignment",
        "storage_policy": {
          "id": "11446498",
          "type": "storage_policy"
        },
        "assigned_to": {
          "id": "11446498",
          "type": "file"
        }
      }
    ]
  }
  ```
</Accordion>


# Task assignments resources
Source: https://developer.box.com/reference/task-assignments-resources



A task assignment defines which task is assigned to which user to complete.

## Task assignment

A task assignment defines which task is assigned to which user to complete.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this task assignment. |
  | `type` | `enum<string>` | No | The value will always be `task_assignment`. Available options: `task_assignment`. |
  | `item` | [File (Mini)](/reference/files-resources#file-mini) | No | The file that the task has been assigned to. |
  | `assigned_to` | [User (Mini)](/reference/users-resources#user-mini) | No | The user that the task has been assigned to. |
  | `message` | `string` | No | A message that will is included with the task assignment. This is visible to the assigned user in the web and mobile UI. |
  | `completed_at` | `string` | No | The date at which this task assignment was completed. This will be `null` if the task is not completed yet. |
  | `assigned_at` | `string` | No | The date at which this task was assigned to the user. |
  | `reminded_at` | `string` | No | The date at which the assigned user was reminded of this task assignment. |
  | `resolution_state` | `enum<string>` | No | The current state of the assignment. The available states depend on the `action` value of the task object. Available options: `completed`, `incomplete`, `approved`, `rejected`. |
  | `assigned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who assigned this task. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "task_assignment",
    "item": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    },
    "assigned_to": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "message": "Please review",
    "completed_at": "2012-12-12T10:53:43-08:00",
    "assigned_at": "2012-12-12T10:53:43-08:00",
    "reminded_at": "2012-12-12T10:53:43-08:00",
    "resolution_state": "incomplete",
    "assigned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    }
  }
  ```
</Accordion>

## Task assignments

A list of task assignments.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | The total number of items in this collection. |
  | `entries` | array of [Task assignment](#task-assignment) | No | A list of task assignments. |

  ```json Example theme={null}
  {
    "total_count": 100,
    "entries": [
      {
        "id": "11446498",
        "type": "task_assignment",
        "item": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "assigned_to": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "message": "Please review",
        "completed_at": "2012-12-12T10:53:43-08:00",
        "assigned_at": "2012-12-12T10:53:43-08:00",
        "reminded_at": "2012-12-12T10:53:43-08:00",
        "resolution_state": "incomplete",
        "assigned_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        }
      }
    ]
  }
  ```
</Accordion>


# Tasks resources
Source: https://developer.box.com/reference/tasks-resources



Tasks allow users to request collaborators on a file to review a file or complete a piece of work. Tasks can be used by developers to create file-centric workflows.

## Task

A task allows for file-centric workflows within Box. Users can create tasks on files and assign them to other users for them to complete the tasks.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this task. |
  | `type` | `enum<string>` | No | The value will always be `task`. Available options: `task`. |
  | `item` | [File (Mini)](/reference/files-resources#file-mini) | No | The file associated with the task. |
  | `due_at` | `string` | No | When the task is due. |
  | `action` | `enum<string>` | No | The type of task the task assignee will be prompted to perform. Available options: `review`, `complete`. |
  | `message` | `string` | No | A message that will be included with the task. |
  | `task_assignment_collection` | [Task assignments](/reference/task-assignments-resources#task-assignments) | No | A collection of task assignment objects associated with the task. |
  | `is_completed` | `boolean` | No | Whether the task has been completed. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created the task. |
  | `created_at` | `string` | No | When the task object was created. |
  | `completion_rule` | `enum<string>` | No | Defines which assignees need to complete this task before the task is considered completed. - `all_assignees` requires all assignees to review or approve the task in order for it to be considered completed. - `any_assignee` accepts any one assignee to review or approve the task in order for it to be considered completed. Available options: `all_assignees`, `any_assignee`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "task",
    "item": {
      "id": "12345",
      "etag": "1",
      "type": "file",
      "sequence_id": "3",
      "name": "Contract.pdf",
      "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
      "file_version": {
        "id": "12345",
        "type": "file_version",
        "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
      }
    },
    "due_at": "2012-12-12T10:53:43-08:00",
    "action": "review",
    "message": "Legal review",
    "task_assignment_collection": {
      "total_count": 100,
      "entries": [
        {
          "id": "11446498",
          "type": "task_assignment",
          "item": {
            "id": "12345",
            "etag": "1",
            "type": "file",
            "sequence_id": "3",
            "name": "Contract.pdf",
            "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
            "file_version": {
              "id": "12345",
              "type": "file_version",
              "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
            }
          },
          "assigned_to": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          },
          "message": "Please review",
          "completed_at": "2012-12-12T10:53:43-08:00",
          "assigned_at": "2012-12-12T10:53:43-08:00",
          "reminded_at": "2012-12-12T10:53:43-08:00",
          "resolution_state": "incomplete",
          "assigned_by": {
            "id": "11446498",
            "type": "user",
            "name": "Aaron Levie",
            "login": "ceo@example.com"
          }
        }
      ]
    },
    "is_completed": true,
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "completion_rule": "all_assignees"
  }
  ```
</Accordion>

## Tasks

A list of tasks.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. |
  | `entries` | array of [Task](#task) | No | A list of tasks. |

  ```json Example theme={null}
  {
    "total_count": 5000,
    "entries": [
      {
        "id": "11446498",
        "type": "task",
        "item": {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        },
        "due_at": "2012-12-12T10:53:43-08:00",
        "action": "review",
        "message": "Legal review",
        "task_assignment_collection": {
          "total_count": 100,
          "entries": [
            {
              "id": "11446498",
              "type": "task_assignment",
              "item": {
                "id": "12345",
                "etag": "1",
                "type": "file",
                "sequence_id": "3",
                "name": "Contract.pdf",
                "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
                "file_version": {
                  "id": "12345",
                  "type": "file_version",
                  "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
                }
              },
              "assigned_to": {
                "id": "11446498",
                "type": "user",
                "name": "Aaron Levie",
                "login": "ceo@example.com"
              },
              "message": "Please review",
              "completed_at": "2012-12-12T10:53:43-08:00",
              "assigned_at": "2012-12-12T10:53:43-08:00",
              "reminded_at": "2012-12-12T10:53:43-08:00",
              "resolution_state": "incomplete",
              "assigned_by": {
                "id": "11446498",
                "type": "user",
                "name": "Aaron Levie",
                "login": "ceo@example.com"
              }
            }
          ]
        },
        "is_completed": true,
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "created_at": "2012-12-12T10:53:43-08:00",
        "completion_rule": "all_assignees"
      }
    ]
  }
  ```
</Accordion>


# Terms of service user statuses resources
Source: https://developer.box.com/reference/terms-of-service-user-statuses-resources



A set of endpoints used to manage the status of terms of service for a particular user.

## Terms of service user status

The association between a Terms of Service and a user.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this terms of service user status. |
  | `type` | `enum<string>` | Yes | The value will always be `terms_of_service_user_status`. Available options: `terms_of_service_user_status`. |
  | `tos` | [Terms of service (Base)](/reference/terms-of-services-resources#terms-of-service-base) | No | The terms of service. |
  | `user` | [User (Mini)](/reference/users-resources#user-mini) | No | The user. |
  | `is_accepted` | `boolean` | No | If the user has accepted the terms of services. |
  | `created_at` | `string` | No | When the legal item was created. |
  | `modified_at` | `string` | No | When the legal item was modified. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "terms_of_service_user_status",
    "tos": {
      "id": "11446498",
      "type": "terms_of_service"
    },
    "user": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "is_accepted": true,
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Terms of service user statuses

A list of terms of service user statuses.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | The total number of objects. |
  | `entries` | array of [Terms of service user status](#terms-of-service-user-status) | No | A list of terms of service user statuses. |

  ```json Example theme={null}
  {
    "total_count": 2,
    "entries": [
      {
        "id": "11446498",
        "type": "terms_of_service_user_status",
        "tos": {
          "id": "11446498",
          "type": "terms_of_service"
        },
        "user": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "is_accepted": true,
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# Terms of service resources
Source: https://developer.box.com/reference/terms-of-services-resources



A set of endpoints used to manage terms of service agreements.

## Terms of service

The root-level record that is supposed to represent a single Terms of Service.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this terms of service. |
  | `type` | `enum<string>` | Yes | The value will always be `terms_of_service`. Available options: `terms_of_service`. |
  | `status` | `enum<string>` | No | Whether these terms are enabled or not. Available options: `enabled`, `disabled`. |
  | `enterprise` | `object` | No | A representation of a Box enterprise. |
  | `tos_type` | `enum<string>` | No | Whether to apply these terms to managed users or external users. Available options: `managed`, `external`. |
  | `text` | `string` | No | The text for your terms and conditions. This text could be empty if the `status` is set to `disabled`. |
  | `created_at` | `string` | No | When the legal item was created. |
  | `modified_at` | `string` | No | When the legal item was modified. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "terms_of_service",
    "status": "enabled",
    "enterprise": {
      "id": "11446498",
      "type": "enterprise",
      "name": "Acme Inc."
    },
    "tos_type": "managed",
    "text": "By using this service, you agree to ...",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Accordion>

## Terms of service (Base)

The root-level record that is supposed to represent a single Terms of Service.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this terms of service. |
  | `type` | `enum<string>` | Yes | The value will always be `terms_of_service`. Available options: `terms_of_service`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "terms_of_service"
  }
  ```
</Accordion>

## Terms of services

A list of terms of services.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_count` | `integer` | No | The total number of objects. |
  | `entries` | array of [Terms of service](#terms-of-service) | No | A list of terms of service objects. |

  ```json Example theme={null}
  {
    "total_count": 2,
    "entries": [
      {
        "id": "11446498",
        "type": "terms_of_service",
        "status": "enabled",
        "enterprise": {
          "id": "11446498",
          "type": "enterprise",
          "name": "Acme Inc."
        },
        "tos_type": "managed",
        "text": "By using this service, you agree to ...",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>


# Trashed files resources
Source: https://developer.box.com/reference/trashed-files-resources



Files that were deleted and are in trash.

## Trashed File

Represents a trashed file.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent 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/123` the `file_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `file`. Available options: `file`. |
  | `sequence_id` | `string` | Yes | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the file. |
  | `sha1` | `string` | Yes | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
  | `file_version` | `File version (Mini)` | No | The information about the current version of the file. |
  | `description` | `string` | Yes | The optional description of this file. |
  | `size` | `integer` | Yes | The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. |
  | `path_collection` | `object` | Yes | A list of parent folders for an item in the trash. |
  | `created_at` | `string` | Yes | The date and time when the file was created on Box. |
  | `modified_at` | `string` | Yes | The date and time when the file was last updated on Box. |
  | `trashed_at` | `string` | No | The time at which this file was put in the trash. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this file is expected to be purged from the trash. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this file was originally created, which might be before it was uploaded to Box. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this file was last updated, which might be before it was uploaded to Box. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this file. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | Yes | The user who last modified this file. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | Yes | The user who owns this file. |
  | `shared_link` | `string` | No | The shared link for this file. This will be `null` if a file has been trashed, since the link will no longer be active. Can be `null`. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The folder that this file is located within. Can be `null`. |
  | `item_status` | `enum<string>` | Yes | Defines if this item has been deleted or not. - `active` when the item has is not in the trash - `trashed` when the item has been moved to the trash but not deleted - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |

  ```json Example theme={null}
  {
    "id": "123456789",
    "etag": "1",
    "type": "file",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "description": "Contract for Q1 renewal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "type": "folder",
          "id": "123456789",
          "sequence_id": null,
          "etag": null,
          "name": "Trash"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": null,
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "trashed"
  }
  ```
</Accordion>

## Trashed File (Restored)

Represents a file restored from the trash.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent 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/123` the `file_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this file. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the file if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `file`. Available options: `file`. |
  | `sequence_id` | `string` | Yes | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the file. |
  | `sha1` | `string` | Yes | The SHA1 hash of the file. This can be used to compare the contents of a file on Box with a local file. |
  | `file_version` | `File version (Mini)` | No | The information about the current version of the file. |
  | `description` | `string` | Yes | The optional description of this file. |
  | `size` | `integer` | Yes | The file size in bytes. Be careful parsing this integer as it can get very large and cause an integer overflow. |
  | `path_collection` | `object` | Yes | A list of parent folders for an item. |
  | `created_at` | `string` | Yes | The date and time when the file was created on Box. |
  | `modified_at` | `string` | Yes | The date and time when the file was last updated on Box. |
  | `trashed_at` | `string` | No | The time at which this file was put in the trash - becomes `null` after restore. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this file is expected to be purged from the trash - becomes `null` after restore. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this file was originally created, which might be before it was uploaded to Box. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this file was last updated, which might be before it was uploaded to Box. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this file. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | Yes | The user who last modified this file. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | Yes | The user who owns this file. |
  | `shared_link` | `string` | No | The shared link for this file. This will be `null` if a file had been trashed, even though the original shared link does become active again. Can be `null`. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The folder that this file is located within. Can be `null`. |
  | `item_status` | `enum<string>` | Yes | Defines if this item has been deleted or not. - `active` when the item has is not in the trash - `trashed` when the item has been moved to the trash but not deleted - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |

  ```json Example theme={null}
  {
    "id": "123456789",
    "etag": "1",
    "type": "file",
    "sequence_id": "3",
    "name": "Contract.pdf",
    "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
    "file_version": {
      "id": "12345",
      "type": "file_version",
      "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
    },
    "description": "Contract for Q1 renewal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": null,
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "active"
  }
  ```
</Accordion>


# Trashed folders resources
Source: https://developer.box.com/reference/trashed-folders-resources



Folders that were deleted and are in trash.

## Trashed Folder

Represents a trashed folder.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | Yes | The value will always be `folder`. Available options: `folder`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | Yes | The name of the folder. |
  | `created_at` | `string` | No | The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `modified_at` | `string` | No | The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `description` | `string` | Yes | The optional description of this folder. |
  | `size` | `integer` | Yes | The folder size in bytes. Be careful parsing this integer as its value can get very large. |
  | `path_collection` | `object` | Yes | A list of parent folders for an item in the trash. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | Yes | The user who created this folder. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | Yes | The user who last modified this folder. |
  | `trashed_at` | `string` | No | The time at which this folder was put in the trash. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this folder is expected to be purged from the trash. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this folder was originally created. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this folder was last updated. Can be `null`. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | Yes | The user who owns this folder. |
  | `shared_link` | `string` | No | The shared link for this folder. This will be `null` if a folder has been trashed, since the link will no longer be active. Can be `null`. |
  | `folder_upload_email` | `string` | No | The folder upload email for this folder. This will be `null` if a folder has been trashed, since the upload will no longer work. Can be `null`. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The optional folder that this folder is located within. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `item_status` | `enum<string>` | Yes | Defines if this item has been deleted or not. - `active` when the item has is not in the trash - `trashed` when the item has been moved to the trash but not deleted - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |

  ```json Example theme={null}
  {
    "id": "123456789",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "description": "Legal contracts for the new ACME deal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "type": "folder",
          "id": "123456789",
          "sequence_id": null,
          "etag": null,
          "name": "Trash"
        }
      ]
    },
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "trashed"
  }
  ```
</Accordion>

## Trashed Folder (Restored)

Represents a folder restored from the trash.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier that represent a folder. The ID for any folder can be determined by visiting a folder in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/folders/123` the `folder_id` is `123`. |
  | `etag` | `string` | No | The HTTP `etag` of this folder. This can be used within some API endpoints in the `If-Match` and `If-None-Match` headers to only perform changes on the folder if (no) changes have happened. Can be `null`. |
  | `type` | `enum<string>` | No | The value will always be `folder`. Available options: `folder`. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the folder. |
  | `created_at` | `string` | No | The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `modified_at` | `string` | No | The date and time when the folder was last updated. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `description` | `string` | No | The optional description of this folder. |
  | `size` | `integer` | No | The folder size in bytes. Be careful parsing this integer as its value can get very large. |
  | `path_collection` | `object` | No | A list of parent folders for an item. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this folder. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this folder. |
  | `trashed_at` | `string` | No | The time at which this folder was put in the trash - becomes `null` after restore. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this folder is expected to be purged from the trash - becomes `null` after restore. Can be `null`. |
  | `content_created_at` | `string` | No | The date and time at which this folder was originally created. Can be `null`. |
  | `content_modified_at` | `string` | No | The date and time at which this folder was last updated. Can be `null`. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this folder. |
  | `shared_link` | `string` | No | The shared link for this file. This will be `null` if a folder had been trashed, even though the original shared link does become active again. Can be `null`. |
  | `folder_upload_email` | `string` | No | The folder upload email for this folder. This will be `null` if a folder has been trashed, even though the original upload email does become active again. Can be `null`. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The optional folder that this folder is located within. This value may be `null` for some folders such as the root folder or the trash folder. Can be `null`. |
  | `item_status` | `enum<string>` | No | Defines if this item has been deleted or not. - `active` when the item has is not in the trash, - `trashed` when the item has been moved to the trash but not deleted, - `deleted` when the item has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |

  ```json Example theme={null}
  {
    "id": "123456789",
    "etag": "1",
    "type": "folder",
    "sequence_id": "3",
    "name": "Contracts",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "description": "Legal contracts for the new ACME deal",
    "size": 629644,
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "trashed_at": null,
    "purged_at": null,
    "content_created_at": "2012-12-12T10:53:43-08:00",
    "content_modified_at": "2012-12-12T10:53:43-08:00",
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": null,
    "folder_upload_email": null,
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "item_status": "active"
  }
  ```
</Accordion>


# Trashed web links resources
Source: https://developer.box.com/reference/trashed-web-links-resources



Web links that were deleted and are in trash.

## Trashed Web Link

Represents a trashed web link.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | No | The value will always be `web_link`. Available options: `web_link`. |
  | `id` | `string` | No | The unique identifier for this web link. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `etag` | `string` | No | The entity tag of this web link. Used with `If-Match` headers. |
  | `name` | `string` | No | The name of the web link. |
  | `url` | `string` | No | The URL this web link points to. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The parent object the web link belongs to. |
  | `description` | `string` | No | The description accompanying the web link. This is visible within the Box web application. |
  | `path_collection` | `object` | No | A list of parent folders for an item in the trash. |
  | `created_at` | `string` | No | When this file was created on Box’s servers. |
  | `modified_at` | `string` | No | When this file was last updated on the Box servers. |
  | `trashed_at` | `string` | No | When this file was last moved to the trash. Can be `null`. |
  | `purged_at` | `string` | No | When this file will be permanently deleted. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this web link. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this web link. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this web link. |
  | `shared_link` | `string` | No | The shared link for this bookmark. This will be `null` if a bookmark has been trashed, since the link will no longer be active. Can be `null`. |
  | `item_status` | `enum<string>` | No | Whether this item is deleted or not. Values include `active`, `trashed` if the file has been moved to the trash, and `deleted` if the file has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |

  ```json Example theme={null}
  {
    "type": "web_link",
    "id": "11446498",
    "sequence_id": "3",
    "etag": "1",
    "name": "My Bookmark",
    "url": "https://www.example.com/example/1234",
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "description": "Example page",
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "type": "folder",
          "id": "123456789",
          "sequence_id": null,
          "etag": null,
          "name": "Trash"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": null,
    "item_status": "trashed"
  }
  ```
</Accordion>

## Trashed Web Link (Restored)

Represents a web link restored from the trash.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | No | The value will always be `web_link`. Available options: `web_link`. |
  | `id` | `string` | No | The unique identifier for this web link. |
  | `sequence_id` | `string` | Yes | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `etag` | `string` | No | The entity tag of this web link. Used with `If-Match` headers. |
  | `name` | `string` | No | The name of the web link. |
  | `url` | `string` | No | The URL this web link points to. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The parent object the web link belongs to. |
  | `description` | `string` | No | The description accompanying the web link. This is visible within the Box web application. |
  | `path_collection` | `object` | Yes | A list of parent folders for an item. |
  | `created_at` | `string` | No | When this file was created on Box’s servers. |
  | `modified_at` | `string` | No | When this file was last updated on the Box servers. |
  | `trashed_at` | `string` | No | The time at which this bookmark was put in the trash - becomes `null` after restore. Can be `null`. |
  | `purged_at` | `string` | No | The time at which this bookmark will be permanently deleted - becomes `null` after restore. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this web link. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this web link. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this web link. |
  | `shared_link` | `string` | No | The shared link for this bookmark. This will be `null` if a bookmark had been trashed, even though the original shared link does become active again. Can be `null`. |
  | `item_status` | `enum<string>` | No | Whether this item is deleted or not. Values include `active`, `trashed` if the file has been moved to the trash, and `deleted` if the file has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |

  ```json Example theme={null}
  {
    "type": "web_link",
    "id": "11446498",
    "sequence_id": "3",
    "etag": "1",
    "name": "My Bookmark",
    "url": "https://www.example.com/example/1234",
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "description": "Example page",
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": null,
    "purged_at": null,
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": null,
    "item_status": "trashed"
  }
  ```
</Accordion>


# Uploads resources
Source: https://developer.box.com/reference/uploads-resources



The direct file upload API supports files up to 50MB in size and sends all the binary data to the Box API in 1 API request.

## Conflict error

The error that occurs when a file can not be created due to a conflict.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | No | The value will always be `error`. Available options: `error`. |
  | `status` | `integer` | No | The HTTP status of the response. |
  | `code` | `enum<string>` | No | A Box-specific error code. Available options: `created`, `accepted`, `no_content`, `redirect`, `not_modified`, `bad_request`, `unauthorized`, `forbidden`, `not_found`, `method_not_allowed`, `conflict`, `precondition_failed`, `too_many_requests`, `internal_server_error`, `unavailable`, `item_name_invalid`, `insufficient_scope`. |
  | `message` | `string` | No | A short message describing the error. |
  | `context_info` | `object` | No | |
  | `help_url` | `string` | No | A URL that links to more information about why this error occurred. |
  | `request_id` | `string` | No | A unique identifier for this response, which can be used when contacting Box support. |

  ```json Example theme={null}
  {
    "type": "error",
    "status": 400,
    "code": "item_name_invalid",
    "message": "Method Not Allowed",
    "context_info": {
      "conflicts": [
        {
          "id": "12345",
          "etag": "1",
          "type": "file",
          "sequence_id": "3",
          "name": "Contract.pdf",
          "sha1": "85136C79CBF9FE36BB9D05D0639C70C265C18D37",
          "file_version": {
            "id": "12345",
            "type": "file_version",
            "sha1": "134b65991ed521fcfe4724b7d814ab8ded5185dc"
          }
        }
      ]
    },
    "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
    "request_id": "abcdef123456"
  }
  ```
</Accordion>

## Upload URL

The details for the upload session for the file.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `upload_url` | `string` | No | A URL for an upload session that can be used to upload the file. |
  | `upload_token` | `string` | No | An optional access token to use to upload the file. |

  ```json Example theme={null}
  {
    "upload_url": "https://upload-las.app.box.com/api/2.0/files/content?upload_session_id=1234",
    "upload_token": "Pc3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQP"
  }
  ```
</Accordion>


# Users resources
Source: https://developer.box.com/reference/users-resources



Box API supports a variety of users, ranging from real employees logging in with their Managed User account, to applications using App Users to drive powerful automation workflows.

## User

A standard representation of a user, as returned from any user API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this user. |
  | `type` | `enum<string>` | Yes | The value will always be `user`. Available options: `user`. |
  | `name` | `string` | No | The display name of this user. |
  | `login` | `string` | No | The primary email address of this user. |
  | `created_at` | `string` | No | When the user object was created. |
  | `modified_at` | `string` | No | When the user object was last modified. |
  | `language` | `string` | No | The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. |
  | `timezone` | `string` | No | The user's timezone. |
  | `space_amount` | `integer` | No | The user’s total available space amount in bytes. |
  | `space_used` | `integer` | No | The amount of space in use by the user. |
  | `max_upload_size` | `integer` | No | The maximum individual file size in bytes the user can have. |
  | `status` | `enum<string>` | No | The user's account status. Available options: `active`, `inactive`, `cannot_delete_edit`, `cannot_delete_edit_upload`. |
  | `job_title` | `string` | No | The user’s job title. |
  | `phone` | `string` | No | The user’s phone number. |
  | `address` | `string` | No | The user’s address. |
  | `avatar_url` | `string` | No | URL of the user’s avatar image. |
  | `notification_email` | `object` | No | An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Can be `null`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "language": "en",
    "timezone": "Africa/Bujumbura",
    "space_amount": 11345156112,
    "space_used": 1237009912,
    "max_upload_size": 2147483648,
    "status": "active",
    "job_title": "CEO",
    "phone": "6509241374",
    "address": "900 Jefferson Ave, Redwood City, CA 94063",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "notification_email": {
      "email": "notifications@example.com",
      "is_confirmed": true
    }
  }
  ```
</Accordion>

## User (Base)

A mini representation of a user, used when nested within another resource.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this user. |
  | `type` | `enum<string>` | Yes | The value will always be `user`. Available options: `user`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "user"
  }
  ```
</Accordion>

## User (Collaborations)

A mini representation of a user, can be returned only when the status is `pending`.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this user. |
  | `type` | `enum<string>` | Yes | The value will always be `user`. Available options: `user`. |
  | `name` | `string` | No | The display name of this user. If the collaboration status is `pending`, an empty string is returned. |
  | `login` | `string` | No | The primary email address of this user. If the collaboration status is `pending`, a login value is returned. |
  | `is_active` | `boolean` | No | If set to `false`, the user is either deactivated or deleted. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com",
    "is_active": true
  }
  ```
</Accordion>

## User (Full)

A full representation of a user, as can be returned from any user API endpoint.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this user. |
  | `type` | `enum<string>` | Yes | The value will always be `user`. Available options: `user`. |
  | `name` | `string` | No | The display name of this user. |
  | `login` | `string` | No | The primary email address of this user. |
  | `created_at` | `string` | No | When the user object was created. |
  | `modified_at` | `string` | No | When the user object was last modified. |
  | `language` | `string` | No | The language of the user, formatted in modified version of the [ISO 639-1](/guides/api-calls/language-codes) format. |
  | `timezone` | `string` | No | The user's timezone. |
  | `space_amount` | `integer` | No | The user’s total available space amount in bytes. |
  | `space_used` | `integer` | No | The amount of space in use by the user. |
  | `max_upload_size` | `integer` | No | The maximum individual file size in bytes the user can have. |
  | `status` | `enum<string>` | No | The user's account status. Available options: `active`, `inactive`, `cannot_delete_edit`, `cannot_delete_edit_upload`. |
  | `job_title` | `string` | No | The user’s job title. |
  | `phone` | `string` | No | The user’s phone number. |
  | `address` | `string` | No | The user’s address. |
  | `avatar_url` | `string` | No | URL of the user’s avatar image. |
  | `notification_email` | `object` | No | An alternate notification email address to which email notifications are sent. When it's confirmed, this will be the email address to which notifications are sent instead of to the primary email address. Can be `null`. |
  | `role` | `enum<string>` | No | The user’s enterprise role. Available options: `admin`, `coadmin`, `user`. |
  | `tracking_codes` | array of `Tracking code` | No | Tracking codes allow an admin to generate reports from the admin console and assign an attribute to a specific group of users. This setting must be enabled for an enterprise before it can be used. |
  | `can_see_managed_users` | `boolean` | No | Whether the user can see other enterprise users in their contact list. |
  | `is_sync_enabled` | `boolean` | No | Whether the user can use Box Sync. |
  | `is_external_collab_restricted` | `boolean` | No | Whether the user is allowed to collaborate with users outside their enterprise. |
  | `is_exempt_from_device_limits` | `boolean` | No | Whether to exempt the user from Enterprise device limits. |
  | `is_exempt_from_login_verification` | `boolean` | No | Whether the user must use two-factor authentication. |
  | `is_collaborated_content_available_when_owner_inactive` | `boolean` | No | Whether collaborators can access content owned by the user when the user is inactive. This setting preserves existing collaborator access and does not grant new permissions. |
  | `enterprise` | `object` | No | A representation of a Box enterprise. |
  | `my_tags` | array of `string` | No | Tags for all files and folders owned by the user. Values returned will only contain tags that were set by the requester. |
  | `hostname` | `string` | No | The root (protocol, subdomain, domain) of any links that need to be generated for the user. |
  | `is_platform_access_only` | `boolean` | No | Whether the user is an App User. |
  | `external_app_user_id` | `string` | No | An external identifier for an app user, which can be used to look up the user. This can be used to tie user IDs from external identity providers to Box users. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com",
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "language": "en",
    "timezone": "Africa/Bujumbura",
    "space_amount": 11345156112,
    "space_used": 1237009912,
    "max_upload_size": 2147483648,
    "status": "active",
    "job_title": "CEO",
    "phone": "6509241374",
    "address": "900 Jefferson Ave, Redwood City, CA 94063",
    "avatar_url": "https://www.box.com/api/avatar/large/181216415",
    "notification_email": {
      "email": "notifications@example.com",
      "is_confirmed": true
    },
    "role": "admin",
    "tracking_codes": [
      {
        "type": "tracking_code",
        "name": "department",
        "value": "Sales"
      }
    ],
    "can_see_managed_users": true,
    "is_sync_enabled": true,
    "is_external_collab_restricted": true,
    "is_exempt_from_device_limits": true,
    "is_exempt_from_login_verification": true,
    "is_collaborated_content_available_when_owner_inactive": true,
    "enterprise": {
      "id": "11446498",
      "type": "enterprise",
      "name": "Acme Inc."
    },
    "my_tags": [
      "important"
    ],
    "hostname": "https://example.app.box.com/",
    "is_platform_access_only": true,
    "external_app_user_id": "my-user-1234"
  }
  ```
</Accordion>

## User (Integration Mappings)

A user representation for integration mappings API purposes. Fields name and login are not required.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this user. |
  | `type` | `enum<string>` | Yes | The value will always be `user`. Available options: `user`. |
  | `name` | `string` | No | The display name of this user. |
  | `login` | `string` | No | The primary email address of this user. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  }
  ```
</Accordion>

## User (Mini)

A mini representation of a user, as can be returned when nested within other resources.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this user. |
  | `type` | `enum<string>` | Yes | The value will always be `user`. Available options: `user`. |
  | `name` | `string` | No | The display name of this user. |
  | `login` | `string` | No | The primary email address of this user. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "user",
    "name": "Aaron Levie",
    "login": "ceo@example.com"
  }
  ```
</Accordion>

## Users

A list of users.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `total_count` | `integer` | No | One greater than the offset of the last entry in the entire collection. The total number of entries in the collection may be less than `total_count`. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `offset` | `integer` | No | The 0-based offset of the first entry in this set. This will be the same as the `offset` query parameter. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `order` | array of `object` | No | The order by which items are returned. This field is only returned for calls that use offset-based pagination. For marker-based paginated APIs, this field will be omitted. |
  | `entries` | array of [User (Full)](#user-full) | No | A list of users. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "total_count": 5000,
    "offset": 2000,
    "order": [
      {
        "by": "type",
        "direction": "ASC"
      }
    ],
    "entries": [
      {
        "id": "11446498",
        "type": "user",
        "name": "Aaron Levie",
        "login": "ceo@example.com",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00",
        "language": "en",
        "timezone": "Africa/Bujumbura",
        "space_amount": 11345156112,
        "space_used": 1237009912,
        "max_upload_size": 2147483648,
        "status": "active",
        "job_title": "CEO",
        "phone": "6509241374",
        "address": "900 Jefferson Ave, Redwood City, CA 94063",
        "avatar_url": "https://www.box.com/api/avatar/large/181216415",
        "notification_email": {
          "email": "notifications@example.com",
          "is_confirmed": true
        },
        "role": "admin",
        "tracking_codes": [
          {
            "type": "tracking_code",
            "name": "department",
            "value": "Sales"
          }
        ],
        "can_see_managed_users": true,
        "is_sync_enabled": true,
        "is_external_collab_restricted": true,
        "is_exempt_from_device_limits": true,
        "is_exempt_from_login_verification": true,
        "is_collaborated_content_available_when_owner_inactive": true,
        "enterprise": {
          "id": "11446498",
          "type": "enterprise",
          "name": "Acme Inc."
        },
        "my_tags": [
          "important"
        ],
        "hostname": "https://example.app.box.com/",
        "is_platform_access_only": true,
        "external_app_user_id": "my-user-1234"
      }
    ]
  }
  ```
</Accordion>


# Login for Headless Environments
Source: https://developer.box.com/guides/cli/headless-login



Authenticate the Box CLI on machines without a browser using manual code entry.

Use the `--code` flag to authenticate the Box CLI in
headless environments such as remote servers, containers,
or CI/CD pipelines where no browser is available.

## Prerequisites

* The Box CLI is <Link href="/guides/cli">installed</Link>.
* You have access to a browser on a separate machine (for
  example, your laptop) to complete the authorization step.

## How it works

The standard `box login` command opens a browser on the
same machine and starts a local callback server to
receive the authorization response automatically. In
headless environments, neither is possible.

The `--code` flag changes the login flow:

* The CLI prints an authorization URL instead of opening a
  browser.
* No local callback server is started.
* After you authorize in a browser on another machine,
  you manually copy the resulting code and state back into
  the CLI.

## Authenticate

### Step 1: Start login with the `--code` flag

On the headless machine, run:

```bash theme={null}
box login --code
```

The CLI prints an authorization URL and waits for input.

<Tip>
  You can combine `--code` with any other `box login`
  options. For example, to authenticate with a custom Box
  platform app, provide your Client ID and Client Secret
  when prompted.
</Tip>

### Step 2: Authorize in a browser on another machine

Copy the authorization URL that the CLI printed, then
open it in a browser on a machine that has one. Sign in
to Box and select **Grant Access to Box**.

### Step 3: Copy the code and state from the redirect URL

After you grant access, the browser redirects to a
`localhost` callback URL. Because no callback server is
running on the headless machine, the page does not load
and the browser displays a connection error.
This is expected.

Look at the URL in the browser's address bar. It
contains the values you need:

```
http://localhost:3000/callback?state=AUTHORIZATION_STATE&code=CODE_VALUE
```

Copy the values of `code` and `state` from this URL.

### Step 4: Enter the codes in the CLI

Return to the terminal on the headless machine and paste
the `code` and `state` values when the CLI prompts for
them.

After the CLI confirms successful authentication, you
are ready to run commands.

### Step 5: Verify the setup

```bash theme={null}
box users:get me
```

If authentication was successful, the CLI returns
information about your Box user account.

## Using `--code` on a machine with a browser

The `--code` flag is intended for headless environments.
If you use it on a machine that has a browser:

* The CLI still prints the authorization URL.
* After you authorize, the browser redirects to the
  callback URL. Because `--code` skips starting the local
  callback server, the redirect page does not load and the
  browser shows a connection error.
* The CLI continues to wait for you to manually enter the
  `code` and `state` values, just as it would in a
  headless environment.

If a browser is available on the same machine, use
`box login` without `--code` for a smoother experience.


# Box CLI
Source: https://developer.box.com/guides/cli/index

Install the Box CLI with npm and use it from your terminal, scripts, and AI agents to manage Box content.

The Box CLI brings Box to your terminal. It works with agentic tools and harnesses, letting you manage content, automate tasks, and integrate Box into scripts, tools, and AI agents.

Scopes are limited to files and folders, AI, and Sign when [logging in as a Box user](#log-in-as-box-user). If you need additional scopes, [use a platform app](#use-a-platform-app) instead.

<SignupCTA>
  Install the Box CLI and connect to your account in minutes. A free developer account is all you need to get started.
</SignupCTA>

## Quickstart

The CLI runs on any platform, including Linux, Windows, and macOS.

### Step 1: Install the CLI

The recommended path is to install using the `box` npm package. You need [Node.js](https://nodejs.org/) 22 or later installed.

```bash theme={null}
npm install --global @box/cli
```

After installation, check that it's working properly:

```bash theme={null}
box --help
```

<Tip>
  **Alternative native binaries:** If you prefer to install the Box CLI for Windows or macOS you can find the downloads [here](https://github.com/box/boxcli/releases).
</Tip>

### Step 2: Authenticate the CLI

In your terminal, run:

```bash theme={null}
box login
```

##### 1. Log in as a Box user (OAuth)

The fastest way to get started. Uses a preconfigured Box application that only supports file and folder operations, AI, and Sign.

Select the **Grant Access to Box** button which appears in the browser.

After authentication completes successfully, you are ready to run commands.

##### 2. Use a platform app

This option requires additional setup but allows you to configure scopes and permissions.

1. Go to your
   [Developer Console][devconsole]
   and select or create an application.
2. In the application’s **Configuration** section:
   * Make sure it uses **Standard OAuth 2.0**.
   * Set the **Redirect URI** to `http://localhost:3000/callback`.
   * Select your desired <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link>.
   * Copy your **Client ID** and **Client Secret**.
3. At the top of the page, click **Save Changes**.
4. Return to the terminal window and enter the **Client ID** and **Client Secret** when prompted.
5. Select the **Grant Access to Box** button which appears in the browser.

After authentication completes successfully, you are ready to run commands.

<Info>
  Use `box login --platform-app` to skip the prompt for the Client ID and Client Secret.
</Info>

##### 3. Headless environment (no browser)

If you are on a remote server or any machine without a browser, use the `--code` flag for manual code entry. See <Link href="/guides/cli/headless-login">Headless Login</Link> for step-by-step instructions.

```bash theme={null}
box login --code
```

### Step 3: Run your first command

To confirm the configuration was successful, enter:

```bash theme={null}
box users:get me
```

If authentication was successful, the CLI returns information about your Box user account.

```json theme={null}
Type: user
ID: '0123456789'
Name: Aaron Levie
Login: example@box.com
Created At: '2020-01-01T09:45:01-07:00'
Modified At: '2021-03-01T09:30:05-07:00'
Language: en
Timezone: America/Los_Angeles
Space Amount: 999999999999999
Space Used: 6291500
Max Upload Size: 16106127360
Status: active
Job Title: ''
Phone: ''
Address: example+user@box.com
Avatar URL: ''
Notification Email: []
```

<Tip>
  The CLI supports <Link href="/guides/hubs-api">Box Hubs</Link> commands. Manage hubs and hub items directly from your terminal. Run `box hubs --help` to see all available operations.
</Tip>

## Getting help

Every CLI command begins with `box`. Add `--help` to any command for assistance. Run `box --help` to display all available top-level commands.

A full list of commands and usage information is available in the [GitHub repository][github].

Supported callback ports are: `3000`, `3001`, `4000`, `5000`, and `8080`. Change with `--port`.

## Alternative methods to interact with the Box API

* To use the
  <Link href="/guides/authentication/jwt">
    server authentication
  </Link>
  method, check our
  <Link href="/guides/cli/cli-with-jwt-authentication/jwt-cli">
    CLI with JWT
  </Link>
  guide.
* To use the
  <Link href="/guides/authentication/client-credentials">
    CCG authentication
  </Link>
  method, check our
  [Box configure][ccg-page]
  guide.

## Additional information

More information about the Box CLI is available in the following pages:

* Review all [commands][commands].
* Review [token cache][cache] settings.
* Review [autocomplete][ac] settings.
* To perform bulk actions using CLI commands, check our [CLI bulk commands][bulk] guide.

[cache]: https://github.com/box/boxcli/blob/master/docs/configure.md#box-configureenvironmentsupdate-name

[ac]: https://github.com/box/boxcli/blob/master/docs/autocomplete.md

[commands]: https://github.com/box/boxcli#command-topics

[github]: https://github.com/box/boxcli#command-topics-1

[devconsole]: https://cloud.app.box.com/developers/console

<Info>
  API requests made through Box first-party applications are not chargeable. Requests made by custom applications using the Box API are chargeable.
</Info>

## Advanced

The GitHub page contains additional guides that might be of interest to an advanced CLI user:

[cli]: https://github.com/box/boxcli

[cli-autocomplete]: https://github.com/box/boxcli/blob/main/docs/autocomplete.md

[cli-switch]: https://github.com/box/boxcli/blob/main/docs/configure.md#box-configureenvironmentsswitch-user-userid

[cli-add-config]: https://github.com/box/boxcli/blob/main/docs/configure.md#box-configureenvironmentsadd-path

[cache]: https://github.com/box/boxcli/blob/main/docs/configure.md#box-configureenvironmentsupdate-name

[scripts]: https://github.com/box/boxcli/tree/main/examples

[ccg-page]: https://github.com/box/boxcli/tree/main/docs/configure.md#box-configureenvironmentsadd-path

[bulk]: https://github.com/box/boxcli/blob/main/docs/Bulk%20actions/README.md


# Building Commands and Help Feature
Source: https://developer.box.com/guides/cli/quick-start/build-commands-help



A full list of CLI commands and usage information can be found in the
[GitHub repository][github].

<Warning>
  Only Service Accounts and Admins are able to use some commands.
  If your user is not authorized with the necessary scopes or you
  configured your CLI to obtain a default token for another user, calls may
  fail. Add `-v` or `--verbose` to your command for verbose error logging.
</Warning>

If you do not see a command for an endpoint you need, you can build a
[custom request][custom].

<Tip>
  Use repository documentation in conjunction with reference documentation to
  see information the help command does not provide. This includes
  restrictions, token permission requirements, fields, etc.
</Tip>

## Using help to create a folder

Every CLI command begins with `box`. Append the `--help` flag to any CLI command to display usage information, available actions, and required arguments.

For example, executing `box --help` shows you
a list of all possible resource commands, such as `folders`, `files`, and `users`. More information is available in
<Link href="/guides/cli/quick-start/using-options">Using Options</Link>.

<Frame>
  <img alt="Help" />
</Frame>

Then, for example, use the folder object and execute the command
`box folders --help`. This provides a list of all eligible actions for this
object.

<Frame>
  <img alt="Help" />
</Frame>

Discover the required arguments for creating a folder: `box folders:create --help`

<Frame>
  <img alt="Help" />
</Frame>

Execute the command `box folders:create 0 "My CLI Folder"` and note the folder
ID returned in the response.

<Tip>
  The root level of the folder tree, the All Files page, is always represented
  by folder ID 0.
</Tip>

Log into **your** Box account and verify that the folder appears.

<Warning>
  If you set up the Box CLI using JWT authentication, you will not see the
  folder in your Box account. The folder will live in the service account
  of the application that was created after application approval.
</Warning>

[github]: https://github.com/box/boxcli#command-topics-1

[custom]: https://github.com/box/boxcli/blob/master/docs/request.md

[sa]: /guides/getting-started/users#service-account


# Using Bulk Commands
Source: https://developer.box.com/guides/cli/quick-start/using-bulk-commands



## Bulk Commands

You can use a CSV file to execute commands in bulk. Each row of the
spreadsheet is treated as an individual API call.

To execute a bulk command, use the option `--bulk-file-path=<PATH_TO_CSV>`, where
`<PATH_TO_CSV>` is the local path of a CSV file containing the
necessary information.

For example, you can create folders using the command `box folders:create --bulk-file-path=path/to/file.csv`

<Tip>
  Drag the CSV file from your finder window/file explorer to the
  terminal/command line window to auto-populate the path.
</Tip>

To specify the column names for your CSV file, go to the [GitHub repository][github] and look at the argument names, or use the `--help` option. In this
case, these are `PARENTID` and `NAME` and are case insensitive.
You can also use a CSV
[template][csv] for this example bulk create folders command.

Executing the command below creates three folders at the root level, 0, of the
Service Account's folder tree.

```bash theme={null}
box folders:create --bulk-file-path=/Users/ExampleUser/Desktop/bulkcreatefolders.csv
```

## Set up and use bulk commands

1. Clone the `boxcli` GitHub repository or download the files from [`Bulk actions`][bulkactions] directory.

   ```bash theme={null}
   git clone https://github.com/box/boxcli.git
   ```

2. Adjust the `.csv` template to your needs. For example, if you want to create several folders, you can use the [`folders-create.csv`][folderstemplate] template as your starting point.

3. Run the command.

   ```bash theme={null}
   box folders:create --bulk-file-path <PATH_TO_CSV>/folders-create.csv
   ```

[console]: https://app.box.com/developers/console

[bulkactions]: https://github.com/box/boxcli/tree/main/docs/Bulk%20actions

[folderstemplate]: https://github.com/box/boxcli/blob/main/docs/Bulk%20actions/folders/folders-create.csv

## Bulk Commands with Options

Any option included in the command is applied to every row in the CSV file. For example,
`box folders:collaborations:create --bulk-file-path=path/to/file.csv --role=editor`
will create collaborations for each user in the csv as an editor.

However, you can also use options in the CSV file. Building on the last example,
instead of using the `--role=editor` option in the command itself, it can be a
column called `role`. The command becomes:
`box folders:collaborations:create --bulk-file-path=pathtocsv`

## CSV templates

Predefined CSV templates help you to structure the data you want to manage in bulk. Templates reside in the [`Bulk actions`][bulkactions] directory, grouped into folders. The table below lists the currently available templates.

| Templates | Description |
| - | - |
| box collaborations | Create, delete, and update collaborations. |
| box files | Download, update, and upload files. |
| box folders | Create and update folders, add metadata to folders. |
| box groups | Create groups and add memberships. |
| box metadata-templates | Create metadata templates and metadata cascade policies on folders. |
| box shared-links | Delete shared links. |
| box users | Create and update users, move one user's content to another user. |
| box webhooks | Delete webhooks. |

[github]: https://github.com/box/boxcli#command-topics

[csv]: https://github.com/box/boxcli/blob/main/docs/Bulk%20actions/folders/folders-create.csv


# Using Options
Source: https://developer.box.com/guides/cli/quick-start/using-options



## Options

Options, also known as flags, provide additional, optional functionality to use with a CLI command.

To see all valid options for a command, run it with `--help` or visit the [GitHub repository][github].

## Getting help

Add `--help` to any command to see its usage, arguments, and available flags.

```bash theme={null}
box folders --help
```

## Controlling output format

### JSON output

Use `--json` to return the full API response as structured JSON. This is useful for scripting or when you need to inspect the complete response.

```bash theme={null}
box files:get 123456 --json
```

### CSV output

Use `--csv` to return results as a CSV. This pairs well with `--save` to produce reports you can open in a spreadsheet.

```bash theme={null}
box folders:items 0 --csv --save
```

### Filtering fields

Use `--fields` to specify only the fields you need in the response. This reduces output noise and can speed up calls that would otherwise return a large number of fields.

```bash theme={null}
box folders:items 0 --fields id,name,login
```

## Saving output

### Save to the default reports folder

Use `--save` to write output to the default reports directory.

```bash theme={null}
box folders:items 0 --csv --save
```

### Save to a custom path

Use `--save-to-file-path` to override the default location and write output to a specific location.

```bash theme={null}
box folders:items 0 --json --save-to-file-path ./exports/users.json
```

## Scripting and automation

### Skip confirmation prompts

Use `--yes` to automatically answer yes to any confirmation prompt. This is useful when running the CLI in scripts or automated pipelines.

```bash theme={null}
box folders:delete 123456 --yes
```

### Disable color

Use `--no-color` to strip ANSI color codes from output. This is recommended when capturing output in log files or CI environments where color codes can corrupt output.

```bash theme={null}
box folders:items 0 --no-color
```

## Debugging

Use `--verbose` to print detailed output including request and response metadata. Add this flag when troubleshooting unexpected errors.

```bash theme={null}
box folders:items 0 --verbose
```

## Using a specific token

Use `--token` to authenticate a single command with a specific access token, overriding the configured default environment. This is useful when testing tokens or running one-off calls without switching environments.

```bash theme={null}
box folders:items 0 --token YOUR_ACCESS_TOKEN
```

## As-User header

Use the <Link href="/guides/authentication/jwt/as-user">`--as-user`</Link> option to perform an action on behalf of another user.

For example, the following command creates a folder called `Example_Folder`
at the root level in user ID 123456's account.

```bash theme={null}
box folders:create 0 Example_Folder --as-user=123456
```

<Warning>
  Only Service Accounts and Admins are able to use the as-user header.
  If your application was not authorized with the necessary scopes or you
  configured your CLI to obtain a default token for another user, this call may
  fail. Add `-v` or `--verbose` to your command for verbose error logging.
</Warning>

[github]: https://github.com/box/boxcli#command-topics

[df]: https://github.com/box/boxcli/blob/master/docs/folders.md#box-foldersdelete-id


# Deprovision users and archive folders
Source: https://developer.box.com/guides/cli/scripts/deprovision-users



This script allows you to deprovision and delete a list of users.
It performs the following steps:

1. Transfers the user content to another user's root folder, specified in the `EmployeeArchiveFolderName` parameter.
2. Deletes the user.

## Prerequisites

### Windows

Install the latest version of [.NET core](https://dotnet.microsoft.com/download).

### macOS & Linux

Install [PowerShell][pwsh]. Run the `pwsh` command to test the installation.

```bash theme={null}
pwsh
```

Depending on the directory you are
running the command in, the output may differ.
For example:

```bash theme={null}
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/user/repos/boxcli/examples>
```

<message>
  If you encounter issues make sure you installed both
  [dotnet core](https://dotnet.microsoft.com/download) and
  [PowerShell][pwsh].
</message>

### Box CLI

To use the script, you need the Box CLI
installed and configured. You can do this by following
our <Link href="/guides/cli">quick start guide</Link>. The user you use to log in with should
be the main Box admin or co-admin.

## Configure the script

1. Clone the `boxcli` GitHub repository and cd into this example's folder or download the files from [`examples`][examples] directory.

   ```bash theme={null}
   git clone https://github.com/box/boxcli.git boxcli
   cd boxcli/examples/User\ Deprovisioning/
   ```

2. Create the list of employees for deletion in `.csv`.

   The header row should look as follows:

   ```bash theme={null}
   name, email
   ```

   where:

   * `name` is the name of the user in Box.
   * `email` is the primary email address of the user in Box.

   For example:

   | `name` | `email` |
   | - | - |
   | Managed User 1 | `ManagedUser1@test.com` |
   | Managed User 2 | `ManagedUser2@test.com` |
   | Managed User 3 | `ManagedUser3@test.com` |

### List of parameters

| `Parameter` | `Description` | `Required` | `Default Value` |
| - | - | - | - |
| `EmployeeList` | Path to Employee List CSV with employees to be deleted. | Yes | - |
| `SkipTransferContent` | Set this flag to skip transfer of user content before deletion when running the script. Otherwise user's content will be transferred. | No | `False` |
| `NewFilesOwnerID` | The ID of the user to transfer files to before deleting the user. If not specified, the script will prompt to input in the interactive mode, or use the current authenticated user ID to receive the content. | No | If not specified, the script will prompt to input in the interactive mode, or use the current authenticated user ID. |
| `EmployeeArchiveFolderName` | The name of a folder, where users' content will be moved to if `SkipTransferContent` is set to `False`. If a folder with this name already exists in the user's `NewFilesOwnerID` root folder, it will be used. Otherwise, a new one will be created. | Yes | `Employee Archive` |
| `DryRun` | A flag that determines the script should be run in a mode, where no delete/create/update calls will be made, only read ones. | No | `False` |

### Define script parameters

You can use the following options to pass parameters.

* Use hardcoded value in script.

  To use this option, update all required parameters listed in the [script parameters section][parameters] before running.

* Run script with parameters.

  You can specify parameters while providing the command. For example:

  ```bash theme={null}
  PS > ./Users_Deprovision.ps1 -EmployeeList ./Employees_to_delete.csv `
  -NewFilesOwnerID  123456789
  -EmployeeArchiveFolderName "Employee Archive"
  ```

  or

  ```bash theme={null}
  PS > ./Users_Deprovision.ps1 -EmployeeList ./Employees_to_delete.csv `
  -SkipTransferContent
  ```

  If you don't specify parameters, the script will prompt you to enter them.

  ```bash theme={null}
  PS > ./Users_Deprovision.ps1
  Please enter the path to the employee list CSV file:
  ./Employees_to_delete.csv
  Please specify the user ID of the user who will own the files of the users being deprovisioned.
  Press Enter if you want to use the current user as the new owner.
  User ID: 1234567689
  Starting User Deprovisioning script...
  ```

## Run the script

Now all you need to do is run the script.

1. Run the Powershell command.

   ```bash theme={null}
   pwsh
   ```

2. Run the script:

   ```bash theme={null}
   ./Users_Deprovision.ps1
   ```

   When all parameters are defined, you will see the following output to confirm the script started:

   ```bash theme={null}
   PS /home/rvb/box-cli/examples/User Deprovisioning> ./Users_Deprovision.ps1
   Starting User Deprovisioning script...
   ```

## Logging

Logs are stored in a `logs` folder located in the main folder.
You have access to these log files:

* `Users_Deprovision_all.txt` that contains all log entries
* `Users_Deprovision_errors.txt` that contains only errors.

[scripts]: https://github.com/box/boxcli/tree/main/examples

[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2

[console]: https://app.box.com/developers/console

[auth]: /guides/authentication/oauth2/oauth2-setup

[examples]: https://github.com/box/boxcli/tree/main/examples/User%20Deprovisioning

[parameters]: https://github.com/box/boxcli/tree/main/examples/User%20Deprovisioning/Users_Deprovision.ps1#L17-L36

[employeelist]: https://github.com/box/boxcli/blob/main/examples/User%20Deprovisioning/Users_Deprovision.ps1#L12

<RelatedLinks title="RELATED GUIDES" />


# CLI sample scripts
Source: https://developer.box.com/guides/cli/scripts/index



Box CLI scripts are designed to help you
automate your tasks. Currently,
the sample scripts library
provides several PowerShell scripts you can use
and customize. In order to run them, you need to install and configure the Box CLI. You can follow the <Link href="/guides/cli">quick start guide</Link> to
get that done.

<Warning>
  Most of the below scripts require the user you run commands with to
  have Box [administrative privileges][7].
</Warning>

## PowerShell scripts

* <Link href="/guides/cli/scripts/powershell-script-templates">PowerShell script templates</Link>
* <Link href="/guides/cli/scripts/deprovision-users">Deprovision users and archive folders</Link>
* <Link href="/guides/cli/scripts/manage-groups-collaborations">Manage groups and collaborations</Link>
* <Link href="/guides/cli/scripts/report-inactive-users">Report inactive users</Link>
* <Link href="/guides/cli/scripts/metadata-extraction">Extract metadata</Link>
* <Link href="/guides/cli/scripts/user-zones-mass-update">Update user zones</Link>
* <Link href="/guides/cli/scripts/slack-integration-mappings">Manage Slack integration folder mappings</Link>

[7]: https://support.box.com/hc/en-us/articles/360043694174-Understanding-Administrator-and-Co-Administrator-Permissions


# Manage groups and collaborations
Source: https://developer.box.com/guides/cli/scripts/manage-groups-collaborations



## Script structure

This script uses the Box CLI to create or update groups, add users to them, and create collaborations between groups and folders.
The script consists of two parts described in detail in the sections below. You can run them both or use the optional flags to decide which part to run.

### Create or update groups

1. The script uses the `.csv` file you specify for the `UserGroupAdditionPath` parameter. The file lists group names and user emails. When creating the file, you can use the same group name for several users, and assign one user to several groups. For example:

   | `GroupName` | `UserEmail` |
   | - | - |
   | Group1 | `ManagedUser1@test.com` |
   | Group1 | `ManagedUser2@test.com` |
   | Group2 | `ManagedUser3@test.com` |
   | Group3 | `ManagedUser1@test.com` |

2. If the group doesn't exist, the script creates it. If it does exist, the script can update the entries based on the provided data.

### Create or update collaborations

1. The script uses the `.csv` file you specify for the `CollaborationsCreationPath` parameter. The file lists group names, folder IDs, and collaboration roles.

2. For each row, the script checks if a group exists and if it's not already added as a collaborator to the corresponding folder. For example:

   | `GroupName` | `FolderId` | `CollaborationRole` |
   | - | - | - |
   | Group1 | 1111111 | editor |
   | Group2 | 1111111 | viewer\_uploader |
   | Group2 | 2222222 | viewer |
   | Group3 | 1111111 | viewer\_uploader |

3. If both of these conditions are met, the script assigns the group to a folder using the role defined in the `CollaborationRole` column. Also, if a group already exists, but the `CollaborationRole` changed, the script will update it if you pass the `-UpdateExistingCollabs` flag when running the script.

## Prerequisites

### Windows

Install the latest version of [.NET core](https://dotnet.microsoft.com/download).

### MacOS & Linux

Install [PowerShell][pwsh]. Run the `pwsh` command to test the installation.

```bash theme={null}
pwsh
```

Depending on the directory you are
running the command in, the output may differ.
For example:

```bash theme={null}
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/user/repos/boxcli/examples>
```

<message>
  If you encounter issues make sure you installed both
  [dotnet core](https://dotnet.microsoft.com/download) and
  [PowerShell][pwsh].
</message>

### Box CLI

To use the script, you need to install and configure the Box CLI. You can do this by following
our <Link href="/guides/cli">quick start guide</Link>. The user you use to log in with should
be the main Box admin or co-admin.

## Configure the script

1. Clone the `boxcli` GitHub repository and cd into this example's folder or download the files from the [`examples`][examples] directory.

   ```bash theme={null}
   git clone https://github.com/box/boxcli.git boxcli
   cd boxcli/examples/Mass\ Groups\ \&\ Collaborations\ Update/
   ```

2. Set the path to the `.csv` file with the list of groups and user emails.

   ```bash theme={null}
   $UserGroupAdditionPath = "./User_Group_Addition.csv"
   ```

   * `UserEmail` is the primary email address for the user in Box.
   * `GroupName` is the name of the group.

3. Set your own path to the `.csv` file with the list of groups and user emails.

   ```bash theme={null}
   $CollaborationsCreationPath = "./Collaborations_Creation.csv"
   ```

   * `GroupName` is the name of the group the script will add as a collaborator to the folder.
   * `FolderId` is the folder ID the collaborator will be added to.
   * `CollaborationRole` is the name of the role used when creating a collaboration.

   You can configure the available roles by setting the `AvailableCollaborationRoles` parameter:

   ```bash theme={null}
   $AvailableCollaborationRoles = @("editor", "viewer", "previewer", "uploader", "previewer_uploader", "viewer_uploader", "co-owner")
   ```

## Run the script

1. Run the Powershell command.

   ```bash theme={null}
   pwsh
   ```

2. Run the script.

   ```bash theme={null}
   ./Mass_Groups_Collabs_Update.ps1
   ```

### Optional flags

You can use flags to run or skip specific parts of the script.

* If a group is already set as a collaborator for a specific folder but with a role other than defined in the `.csv` file, the script informs you about it. It does not make any changes to an existing collaboration. If you want to update an existing collaboration with a role defined in the `.csv` file, set an additional `-UpdateExistingCollabs` flag when running the script.

  ```bash theme={null}
  Mass_Groups_Collabs_Update.ps1 -UpdateExistingCollabs
  ```

* To update groups without creating collaborations, add the `-SkipCollabsCreation` boolean flag when running the script:

  ```bash theme={null}
  Mass_Groups_Collabs_Update.ps1 -SkipCollabsCreation
  ```

* To create collaborations without any group updates, add the `-SkipGroupsUpdate` boolean flag when running the script:

  ```bash theme={null}
  Mass_Groups_Collabs_Update.ps1 -SkipGroupsUpdate
  ```

## Logs

Logs are stored in the `logs` folder located in the main folder.
You have access to these log files:

* `Mass_Groups_Collabs_Update_all.txt` that contains all log entries.
* `Mass_Groups_Collabs_Update_errors.txt` that contains only errors.

[examples]: https://github.com/box/boxcli/tree/main/examples

[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2

[console]: https://app.box.com/developers/console

[auth]: /guides/authentication/oauth2/oauth2-setup

<RelatedLinks title="RELATED GUIDES" />


# Extract metadata
Source: https://developer.box.com/guides/cli/scripts/metadata-extraction



This script extracts metadata details for all the
files and folders in any Box folder and
saves the result in a CSV spreadsheet for
each metadata template.

## Prerequisites

### Windows

Install the latest version of [.NET core](https://dotnet.microsoft.com/download).

### macOS & Linux

Install [PowerShell][pwsh]. Run the `pwsh` command to test the installation.

```bash theme={null}
pwsh
```

Depending on the directory you are
running the command in, the output may differ.
For example:

```bash theme={null}
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/user/repos/boxcli/examples>
```

<Info>
  If you encounter issues make sure you installed both
  [.NET core](https://dotnet.microsoft.com/download) and
  [PowerShell][pwsh].
</Info>

### Box CLI

To use the script, you need the Box CLI
installed and configured. You can do this by following
our <Link href="/guides/cli">quick start guide</Link>.

## Configure the script

1. Clone the `boxcli` GitHub repository and cd into this example's folder or download the files from the [`examples`][examples] directory.

   ```bash theme={null}
   git clone https://github.com/box/boxcli.git
   cd boxcli/examples/Metadata\ Extraction/
   ```

2. Specify the `folderID` and `userID` parameters to tell the script which folder to scan, and who is the user running the script.

   ```bash theme={null}
   [string]$FolderID = "",
   [string]$UserID = "",
   ```

   If you don't want to specify the parameters directly in the script,
   you can either pass them as flags or allow the script
   to prompt you to enter them. A sample command with flags looks as follows:

   ```bash theme={null}
   ./Metadata-extraction.ps1 -folderId 123456789 -userId 123456789
   ```

## Run the script

1. Run the Powershell command.

   ```bash theme={null}
   pwsh
   ```

2. Run the script.

   ```bash theme={null}
   ./Metadata-extraction.ps1 -folderId 123456789 -userId 123456789
   ```

   When the script finishes, you will see the following
   output or a similar one.

   ```bash theme={null}
   Pulling data from Folder ID: 173961139760
   metadata as user ID: 20718545815
   Reading Item ID: 1016853559790
   Metadata saved to: MetadataTemplate_properties.csv
   ```

## Logs

Logs are stored in a `logs` folder located in the main folder.
You have access to these log files:

* `Metadata-extraction_all.txt` that contains all log entries.
* `Metadata-extraction_errors.txt` that contains only errors.

[scripts]: https://github.com/box/boxcli/tree/main/examples

[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2

[console]: https://app.box.com/developers/console

[auth]: /guides/authentication/oauth2/oauth2-setup

[examples]: https://github.com/box/boxcli/tree/main/examples/Metadata%20Extraction

<RelatedLinks title="RELATED GUIDES" />


# Using PowerShell Scripts with the Box CLI
Source: https://developer.box.com/guides/cli/scripts/powershell-script-templates



You can automate repetitive administrative workflows by combining the Box CLI with PowerShell scripts. We created an example
[scripts][scripts] folder within our CLI GitHub repository to help
jump-start your development.

To show you how CLI scripts work, we are going to use the
provision and create users [script][script-1]
template.

This script uses the Box CLI to build and create a
personal folder structure, create managed users in bulk,
and provision new users by adding them to the newly created
folder structure as collaborators with viewer or uploader roles.

<Warning>
  This guide is for service accounts
  and users with administrative privileges only.
  Skip this step if you are not a Box administrator
  or you do not use a service account.
</Warning>

## Use case

To automatically create users and folder structure, the script
performs the following steps:

1. Uses a `.csv` file to load employee data in bulk.
2. Defines folder structure using a JSON file or uploads the structure from the user's local directory.
3. Creates a predetermined personal folder structure for each new managed user.

## Prerequisites

### Windows

Install the latest version of [.NET core](https://dotnet.microsoft.com/download).

### macOS & Linux

Install [PowerShell][pwsh].

### Box CLI

To use the script, you need the Box CLI
installed and configured. If you haven't done so yet, see our <Link href="/guides/cli">quick start guide</Link>.

### Create a personal folder parent folder

This script works by creating a folder structure for each user that is
created. To do this, create a parent
folder for all of the personal folders to live in. By default all folders are created in the root folder of the account used by the CLI. You can name
and place the folder wherever you wish, but the user you set up the CLI with
must have access to the folder.

Here is an example of what the structure looks like after
running the script.

<Frame>
  <img alt="Finished Folder Structure" />
</Frame>

## Download the script

Clone the script to a directory of your choice
and navigate to that directory.

```bash theme={null}
git clone https://github.com/box/boxcli.git box-cli
cd box-cli/examples/User\ Creation\ \&\ Provisioning/
```

## Configure the script settings

Adapt the script to run in your own environment.
In this example, we use the sample data provided
with the script.

### Provide the parameters

There are a few parameters you need to supply before running the script:

* `EmployeeList`: Path to `Employee List` CSV.
* `PersonalFolderParentID`: Destination folder ID for all personal folders to be created in, either when using JSON file as input to create folder structure, or uploading local structure. This folder should be made prior to running the script the first time. It is not advised to make this value `0`, as this creates individual personal folders in the root of the account you set up the CLI with.
* `FolderStructureJSONPath`: Your own folder structure JSON path.
* `PersonalFolderSlug`: Ending name of the folder created as a parent for personal folders. It's set to `Personal Folder` by default, but you can set it to your needs. The username is linked with this value to create each user's personal folder name. For example - `rsmith2's Personal Folder`.
* `LocalUploadPath`: Local directory to upload folder structure directly.

<Info>
  Specify **either** a local upload path or a JSON file with the folder
  structure, but not both.
</Info>

### Update the user list

You can use the following sample files to load users:
`Employees_1.csv`, `Employees_5.csv`, and `Employees_10.csv`.
Each file creates 1, 5, or 10 new users.

Customize these files for a test run. For example, update the
`Employees_1.csv` with the following data:

```bash theme={null}
firstName,lastName,email,username
Isaac,Newton,abc@abc.local,INewton23
```

With the `EmployeeList` parameter, specify which `.csv` file you would like
to load data from.

<Warning>
  Emails must be unique across all of Box, and usernames must be unique across
  your specific Box instance. Otherwise, an error will be thrown when running
  the script.
</Warning>

### Create folder structure

You can either create a folder structure from a JSON
file or upload it from your local drive.

#### Use a JSON file

The `Folder_Structure.json` file contains the folder structure you want to create.
As an example, you will create a `Market Research` and a `Sales Plays`
folder, each with a subfolder `Statistics` and `Big Pharma` respectively.
The script will place this folder structure
under the `Personal Folder` folder for that user inside the parent folder
you designate.

With the `FolderStructureJSONPath` parameter, provide the location of the
`Folder_Structure.json` file.

#### Upload file from local drive

You can also upload a folder structure directly
from the local file system. With the `LocalUploadPath` parameter, provide the
path to your local folder you want to upload. The uploaded folder structure is created in Box using the same naming structure as the JSON method.

### Update the parameters

You can provide parameters in three ways:

* Use static values in the script

  <Info>
    Remember to update all required parameters in the script before running.
  </Info>

  ```bash theme={null}
  # Set Employee List CSV Path
  # firstname, lastname, email, username
  $EmployeeList = ""

  # Personal Folder Structure: Set either path build off JSON or directly upload
  # a local folder
  $FolderStructureJSONPath = ""
  $LocalUploadPath = ""

  # Ending slug of folder that will be used in creating personal folders for new
  # users. Value will get concatenated with username
  # If username is RSMITH, the personal folder name would be
  # RSMITH's Personal Folder
  $PersonalFolderSlug = ""

  # ID of parent folder for created personal folders to be created in
  # This folder should be created before running the script the first time.
  # It is not advised to make this value 0, as this will create individual
  # Personal folders in root of the account you set up the cli with
  $PersonalFolderParentID = ""
  ```

* Run the script with parameters

  You can specify parameters while running the script, for example:

  ```bash theme={null}
  PS > ./Users_Create_Provision.ps1 -EmployeeList ./Employees_1.csv `
      -LocalUploadPath ./PersonalLocalUpload `
      -PersonalFolderSlug "Personal Folder" `
      -PersonalFolderParentID 123456789

  Starting User Creation & Provisioning script...
  ```

* Provide the parameters when prompted

  If some parameters are still missing at runtime, the script will prompt you to provide them:

  ```bash theme={null}
  PS > ./Users_Create_Provision.ps1
  Please enter the path to the employee list CSV file:
  ./Employees_1.csv
  Please enter the path to the folder structure JSON file or the local upload path:
  Folder_Structure.json
  Folder structure JSON path set to: Folder_Structure.json
  Please enter the ID of the folder where you would like to create the personal folders:
  0
  Starting User Creation & Provisioning script...
  ```

## Run the script

1. Change the directory to the folder containing the script. In this example, it is the `User Creation & Provisioning` folder.

   ```bash theme={null}
   pwsh
   ```

2. Run the script:

   ```bash theme={null}
   PS /home/rvb/box-cli/examples/User Creation & Provisioning> ./Users_Create_Provision.ps1
   ```

   The response will be similar to the following:

   ```bash theme={null}
   Starting User Creation & Provisioning script...

   firstName lastName email
   --------- -------- -----
   Isaac     Newton   abc@abc.local
   Extracting folder structure
   Found current User ID: 18622116055

   Created a user owned Onboarding folder with id: 164734146745

   Created subfolder Market Research under Onboarding folder with id: 164735375585

   Created subfolder under Statistics folder with id: 164734956242

   Created subfolder Sales Plays under Onboarding folder with id: 164735683001

   Created subfolder under Big Pharma folder with id: 164736160637
   Creating employee Managed User account with first name:
   Isaac, last name: Newton, email: abc@abc.local, and

   Created Managed user with id: 19605663027

   Type: collaboration
       ID: '37250833128'
   Created By:
       Type: user
       ID: '18622116055'
   Name: Rui Barbosa
   Login: barduinor@gmail.com
   Created At: '2022-06-07T13:58:05-07:00'
   Modified At: '2022-06-07T13:58:05-07:00'
   Expires At: null
   Status: accepted
   Accessible By:
       Type: user
       ID: '19605663027'
       Name: Isaac Newton
       Login: abc@abc.local
   Invite Email: null
   Role: viewer uploader
   Acknowledged At: '2022-06-07T13:58:05-07:00'
   Item:
       Type: folder
       ID: '164734146745'
       Sequence ID: '0'
       ETag: '0'
   Name: Onboarding
   Collaborated Managed User Isaac Newton to current users
   Onboarding folder for provisioning
   ```

## Running the script again for new users

It is common to run this script regularly as your company hires new employees.
You can simply edit the `.csv` file, removing the previous rows of users and
adding the information for the new users. Then run the script again.

## Summary

You explored automation using a PowerShell script with the
Box CLI to provision users
and create an initial folder structure.

Make sure to explore our other <Link href="/guides/cli/scripts">sample scripts</Link> for more use cases.

[scripts]: https://github.com/box/boxcli/tree/main/examples

[script-1]: https://github.com/box/boxcli/tree/main/examples/User%20Creation%20&%20Provisioning

[jwt-cli]: /guides/cli/cli-with-jwt-authentication/jwt-cli

[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2

[console]: https://app.box.com/developers/console


# Report inactive users
Source: https://developer.box.com/guides/cli/scripts/report-inactive-users



This script generates a CSV file with a list of users who have been inactive for a number of days. It performs the following steps:

1. Looks for the users who have the role `user`.

   <Info>
     The script does not consider other roles, such as `AppUser`.
   </Info>

2. Uses <Link href="/reference/resources/event">Box Events</Link> to check if the user performed any actions for a specified number of days. The default list of event types includes: `LOGIN`,`UPLOAD`,`COPY`,`MOVE`,`PREVIEW`,`DOWNLOAD`,`EDIT`,`DELETE`,`UNDELETE`,`LOCK`,`UNLOCK`, `NEW_USER`. You can modify this list in the script settings.

3. Adds users who didn't perform any actions to a `.csv` file with inactive users. You can use this file as input for other scripts, for example to <Link href="/guides/cli/scripts/deprovision-users">deprovision users</Link>.

## Prerequisites

### Windows

Install the latest version of [.NET core](https://dotnet.microsoft.com/download).

### macOS & Linux

Install [PowerShell][pwsh]. Run the `pwsh` command to test the installation.

```bash theme={null}
pwsh
```

Depending on the directory you are
running the command in, the output may differ.
For example:

```bash theme={null}
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/user/repos/boxcli/examples>
```

<message>
  If you encounter issues make sure you installed both
  [.NET core](https://dotnet.microsoft.com/download) and
  [PowerShell][pwsh].
</message>

### Box CLI

To use the script, you need the Box CLI
installed and configured. You can do this by following
our <Link href="/guides/cli">quick start guide</Link>. The user you use to log in with should
be the main Box admin or co-admin.

## Configure the script

1. Clone the `boxcli` GitHub repository and cd into this example's folder or download the files from the [`examples`][examples] directory.

   ```bash theme={null}
   git clone https://github.com/box/boxcli.git
   cd boxcli/examples/Inactive\ Users\ Report/
   ```

2. Set the number of days you want the script to scan for user events. If you don't specify this value or leave the default, the script will prompt you to enter it.

   ```bash theme={null}
   $daysInactive = "10"
   ```

3. (Optional) To change the report output file name, define the `ReportOutputFile` parameter.

   ```bash theme={null}
   $ReportOutputFile = $ReportName + ".csv"
   ```

4. (Optional) To change event types, define the list for `eventType` parameter.

   ```bash theme={null}
   $eventType = "LOGIN,UPLOAD,COPY,MOVE"
   ```

## Run the script

Run the Powershell command.

```bash theme={null}
pwsh
```

Run the script.

```bash theme={null}
./Inactive_Users_Report.ps1
```

When the script run is completed, you will see the following
output or a similar one.

```bash theme={null}
Looking for users inactive for more than 3 days.
Found 6 users.
Found 7 events in last 3 days
Enterprise has: 0 App user, 6 regular users. With 1 admin role, 5 user roles.
Need to check 5 users (regular user, with user role) for inactive.
Found 5 users inactive for more than 3 days.
Report is available at InactiveUsers.csv
```

## Logging

Logs are stored in the `logs` folder located in the main folder.
You have access to these log files:

* `Inactive_Users_Report_all.txt` - contains all log entries
* `Inactive_Users_Report_errors.txt` - contains only errors.

[scripts]: https://github.com/box/boxcli/tree/main/examples

[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2

[console]: https://app.box.com/developers/console

[auth]: /guides/authentication/oauth2/oauth2-setup

[examples]: https://github.com/box/boxcli/tree/main/examples/Inactive%20Users%20Report

<RelatedLinks title="RELATED GUIDES" />


# Manage Slack integration folder mappings
Source: https://developer.box.com/guides/cli/scripts/slack-integration-mappings



This script helps manage the folder mappings between Slack and Box if using Box
as the content store for Slack. It creates a list of current Slack channel and
Box folder mappings and can create or update mappings based on the input csv. This
script maintains all permissions.

For more details, see the [Github repo][1].

## Prerequisites

### Clone script

Clone this GitHub repo or download files from the `/examples` directory.

```bash theme={null}
git clone https://github.com/box/boxcli.git
```

### Windows

Install the latest version of [.NET core](https://dotnet.microsoft.com/download).

### MacOS & Linux

Install [PowerShell][pwsh]. Run the `pwsh` command to test the installation.

```bash theme={null}
pwsh
```

Depending on the directory you are
running the command in, the output may differ.
For example:

```bash theme={null}
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/user/repos/boxcli/examples>
```

<message>
  If you encounter issues make sure you installed both
  [dotnet core](https://dotnet.microsoft.com/download) and
  [PowerShell][pwsh].
</message>

### Box CLI Install

Configure and install the Box CLI using the <Link href="/guides/cli">CLI Quickstart Guide</Link>. Make sure the user you use is an admin or co-admin.

### Enterprise configuration

* Configure and [install Box for Slack][install-slack] in the relevant Slack workspaces and organizations.
* Enable Box as the [content layer for Slack][content-layer].

## Run the script

Change the directory to the folder containing the script. In this example, it is the `Integration Mappings` folder.

```pwsh theme={null}
rvb@lab:~/box-cli/examples/Integration Mappings$ pwsh
PowerShell 7.2.4
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /home/rvb/box-cli/examples/Integration Mappings>
```

Run the script with EXTRACT to extract current mappings:

```pwsh theme={null}
./integration-mappings.ps1 -Action EXTRACT
```

or

Run the script with UPDATE to update current mappings:

```pwsh theme={null}
./integration-mappings.ps1 -Action UPDATE
```

or

Run the script with CREATE to create new mappings:

```pwsh theme={null}
./integration-mappings.ps1 -Action CREATE -MappingPath ./mapping_create_example.csv
```

By default, the csv file will save to and load from ./mappings.csv. If you wish to change this location, you can pass in a new path like so:

```pwsh theme={null}
./integration-mappings.ps1 -Action EXTRACT -MappingPath ./mappings_new_location.csv
```

If you don't specify parameters, the script prompts you to enter them.

When creating a mapping on a new channel, you must input a Box folder ID, Slack channel ID, and Slack org ID. You can use a Slack workspace ID in place of the org ID. In that case, you need to replace the csv column header `SlackOrgId` with `SlackWorkspaceId`.

```pwsh theme={null}
Starting Process
Applying new mappings
Output [...]
All bulk input entries processed successfully.
```

## Logs

Logs are stored in a `logs` folder located in the main folder. You have access to these log files:

* `Integration-mappings_all.txt` that contains all log entries.
* `Integration-mappings_errors.txt` that contains only errors.

## Disclaimer

This project is a collection of open source examples and should not be treated as an officially supported product. Use at your own risk and as a source of examples for how to use the Box CLI.

[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2

[install-slack]: https://support.box.com/hc/en-us/articles/360044195313-Installing-and-Using-the-Box-for-Slack-Integration

[content-layer]: https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack

[1]: https://github.com/box/boxcli/tree/main/examples/Integration%20Mappings

<RelatedLinks title="RELATED GUIDES" />


# Update user zones
Source: https://developer.box.com/guides/cli/scripts/user-zones-mass-update



<RelatedLinks title="REQUIRED GUIDES" />

This [script][script] provisions users to a specific
data residency zone within a Multizone Box tenant.
It performs the following steps:

1. It uses admin or co-admin login email address to find the associated enterprise and the zone policy assigned to this enterprise. An assigned zone policy is inherited by all users unless specified otherwise. It is sometimes called the **default zone**.
2. It performs zone assignment based on an input `.csv` file containing user email addresses and zone mappings.

<message>
  Usually, you use the script once to do the initial provisioning of user zones, but you can also use it for subsequent runs to make zone assignment updates.
</message>

If you would like to use Admin Console for zone assignment, see [this guide][zonesguide].
For more information about Box Zones, see the [official website][zonespage].

## Prerequisites

### Windows

Install the latest version of [.NET core](https://dotnet.microsoft.com/download).

### MacOS & Linux

Install [PowerShell][pwsh]. Run the `pwsh` command to test the installation.

```bash theme={null}
pwsh
```

Depending on the directory you are
running the command in, the output may differ.
For example:

```bash theme={null}
PowerShell 7.2.5
Copyright (c) Microsoft Corporation.

https://aka.ms/powershell
Type 'help' to get help.

PS /Users/user/repos/boxcli/examples>
```

<message>
  If you encounter issues make sure you installed both
  [.NET core](https://dotnet.microsoft.com/download) and
  [PowerShell][pwsh].
</message>

### Set up application with JWT authentication

To use the script, you need to install and configure the <Link href="/guides/cli/cli-with-jwt-authentication/jwt-cli">Box CLI with JWT authentication</Link>.

When creating the app, use the **Configuration** tab
to configure the following settings:

* In **App Access Level**, select `App + Enterprise Access`.
* In **Application Scopes** > **Administrative Actions**, select `Manage Enterprise Properties`, `Manage Users`.
* In **Advanced Features**, select `Generate user access tokens`.

### Adjust admin settings

Make sure the Box Admin or Co-Admin has at least `Manage Users` privileges.
To check this setting:

1. Go to the **Users & Groups** section in the Admin Console.
2. Click the user account you want to verify.
3. Go to the **Edit User Access permissions** section to grant administrative privileges for users and groups.

## Prepare the `.csv` file

The `.csv` file must have two columns with the following headers: **Email** and **Region**.

* **Email** contains the primary email address of a Box user.
* **Region** contains the user-friendly name for the zone to which the script will assign the user. This name is provided by the [ZonesTable][zonestable] that is a hash table used to define zones. The keys are the zone's user-friendly names, and the corresponding value is the global ID of the zone.

  ```bash theme={null}
  $ZonesTable = @{
      US = "100001"             #US
      GermanyIreland = "100002" #Germany/Ireland with in region uploads/downloads/previews
      Australia = "100003"      #Australia
      Japan = "100004"          #Japan with in region uploads/downloads/previews
      Canada = "100005"         #Canada
      JapanSingapore = "100007" #Japan/Singapore with in region uploads/downloads/previews
      UKGermany = "100008"      #UK/Germany
      UK = "100009"             #UK with in region uploads/downloads/previews
      France = "100012"         #France
  }
  ```

<message>
  Consult the Box Consulting or Customer Success manager to get the IDs corresponding to the zones enabled in a specific enterprise.
</message>

A sample input `.csv` file containing emails and zone names is provided with this script. Its content looks as follows:

| Email | Region |
| - | - |
| `betty@company.com` | US |
| `roger@company.com` | France |
| `sally@company.com` | JapanSingapore |

## Configure the script

Set the `UserZonesUpdatePath` to point to your `.csv` file.

```bash theme={null}
$UserZonesUpdatePath = "./your_file_name.csv"
```

Update the `adminEmail` to the admin or `co-admin` login email address of the account the script will use to make zone assignments.
If you don't specify this value, the script will prompt you for it.

```bash theme={null}
$adminEmail = "john@box.com"
```

## Run the script

Run the Powershell command.

```bash theme={null}
pwsh
```

Run the script.

```bash theme={null}
./Mass_Update_User_Zones.ps1
```

### Optional flags

To run the script in simulation mode,
add the `DryRun` boolean flag.
Dry run doesn't mean that API calls won't be made, but that any create/update/delete calls are skipped.

```bash theme={null}
./Mass_Update_User_Zones.ps1 -DryRun
```

## Logging

Logs are stored in a `logs` folder located in the main folder.
You have access to these log files:

* `Mass_Update_User_Zones_all.txt` that contains all log entries.
* `Mass_Update_User_Zones_errors.txt` that contains only errors.

[zonesguide]: https://support.box.com/hc/en-us/articles/360044193533-Assigning-Zones-through-the-Admin-Console

[script]: https://github.com/box/boxcli/tree/main/examples/Mass%20Update%20User%20Zones

[zonespage]: https://www.box.com/zones

[zonestable]: https://github.com/box/boxcli/blob/main/examples/Mass%20Update%20User%20Zones/Mass_Update_User_Zones.ps1#L23

[scripts]: https://github.com/box/boxcli/tree/main/examples

[pwsh]: https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.2

[console]: https://app.box.com/developers/console

<RelatedLinks title="RELATED GUIDES" />


# The `box` npm package
Source: https://developer.box.com/guides/tooling/box-npm-package

What `npm install box` provides, how to use the bundled SDK and CLI, and what existing `box-node-sdk` users need to know.

The `box` package on npm bundles the [Box Node SDK](/guides/tooling/sdks/node) and the [Box CLI](/guides/cli) into a single install. Use it to add Box to a JavaScript or TypeScript project — and to run Box CLI commands — with one command.

## What's included

`npm install box` installs two direct dependencies:

* **Box Node SDK**, exposed at the `box/sdk` subpath.
* **Box CLI**, exposed via `npx box`.

TypeScript types are included.

## Prerequisites

Install [Node.js](https://nodejs.org/) 22 or later.

## Install

```bash theme={null}
npm install box
```

The package works with npm, yarn, pnpm, and bun.

## Use the SDK

Import the SDK from the `box/sdk` subpath:

```javascript theme={null}
import BoxSDK from 'box/sdk';  // ESM
const BoxSDK = require('box/sdk');  // CommonJS
```

For SDK usage and authentication, see [Install the Node SDK](/guides/tooling/sdks/node) and the [authentication guides](/guides/authentication).

<Info>
  **Stable alias.** You can also import the SDK from the package root with `import BoxSDK from 'box'`. This returns the same SDK and is designed to remain stable across future changes to the underlying package.
</Info>

## Use the CLI

Run any CLI command with `npx box`:

```bash theme={null}
npx box --help
npx box login
npx box users:get me
```

No separate CLI install is required. For full CLI documentation, see the [CLI overview](/guides/cli).

## Continuous integration

The package is CI-safe. The post-install message is skipped when any of the following are true:

* The `CI` environment variable is set to `true`.
* The `SUPPRESS_BOX_INSTALL_MESSAGE` environment variable is set.
* The install runs with `--ignore-scripts`.

No network requests are made during or after installation. All Box API traffic happens through the Box SDK and CLI at runtime, using your application's authentication.

## Security

Every release includes cryptographic provenance attestations that are verifiable against the official GitHub repository.

## Not a browser package

The `box` package is for Node.js. To embed Box UI components in a browser application, install [`box-ui-elements`](/guides/embed/ui-elements) separately.

## Existing `box-node-sdk` users

No migration is required. If `box-node-sdk` works for you, leave it. The `box` package is for developers — and their coding agents — starting fresh. Existing code is unaffected.

## Open source

The `box` package is open source under the Apache 2.0 license at [github.com/box/npm-box](https://github.com/box/npm-box). Contributions go through pull requests against that repository.


# Install .NET SDK
Source: https://developer.box.com/guides/tooling/sdks/dotnet



You can use Box .NET SDK to call Box APIs in a .NET
project.

Up to version `5.8.0` the SDK is available for both .NET Framework `4.5` and .NET Core `1.0` or above. Starting from version `10.0.0`, SDK is available for both .NET Framework `4.6.2` and .NET `8.0` or above. The installation of the SDK depends on the framework used.

<Card href="https://github.com/box/box-windows-sdk-v2" title="Learn more about .NET SDK on GitHub" />

## .NET Framework

To install the .NET SDK in the .NET framework, run the following command using
the [Nuget][nuget] package manager.

```shell theme={null}
PM> Install-Package Box.V2.Core
```

## .NET Core

To install the .NET SDK in the .NET Core framework, run the following command
using the [Nuget][nuget] package manager.

```shell theme={null}
PM> Install-Package Box.V2.Core
```

[nuget]: https://www.nuget.org/


# Deprecated Box Next Gen .NET SDK
Source: https://developer.box.com/guides/tooling/sdks/dotnet-gen



<Warning>
  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts.

  Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs, and it is currently available as a separate [branch][sdk-branch].
</Warning>

Check the [migration guide][migration] to learn how to switch from the Box Next Generation SDK to the Box core SDK `v10`.

For more details, see our <Link href="/guides/tooling/sdks/sdk-versioning">SDK versioning strategy document</Link>.

[sdk-branch]: https://github.com/box/box-windows-sdk-v2/tree/main

[migration]: https://github.com/box/box-windows-sdk-v2/blob/main/migration-guides/from-dotnet-sdk-gen-v1-to-box-windows-sdk.md


# Box SDKs
Source: https://developer.box.com/guides/tooling/sdks/index



Box offers a set of SDKs
you can use to build your application.

<Note>
  The tables below list SDKs along with additional information
  telling you if the project is maintained and has API
  parity.

  **Maintained:** Fully maintained projects are actively developed by Box. They
  receive the latest security updates and new features. For support with these
  projects please visit GitHub or [our Platform support forum][forum].

  **API Parity**: Projects with full API parity are actively updated with all
  platform functionality as this becomes available on Box. Projects
  with partial API parity lack some functionality while we work on bringing
  these projects to full parity.
</Note>

The table lists Box SDKs that you can use when building your
applications. For latest API support and features, use the next
generation SDKs.

| Platform | Maintained? | API Parity |
| - | - | - |
| [Java SDK][javasdk] | Yes | Full |
| [iOS Content SDK][iossdk] | Yes | Full |
| [.NET SDK][dotnetsdk] | Yes | Full |
| [Python SDK][pythonsdk] | Yes | Full |
| [Node SDK][nodesdk] | Yes | Full |
| [Android Content SDK][androidsdk] | No | Full |

<Warning>
  As of May 31, 2023 Android SDK is no
  longer supported. You can still
  use your existing Android SDK applications
  with no impact, but you won't receive new features,
  updates, or bug fixes.

  If you would like to continue getting the
  latest and greatest Android features, use Java SDK to
  build apps on Android.
  Refer to [this][android-docs] documentation for more details.
</Warning>

## Next Generation SDKs

<Warning>
  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts.

  Don't worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  In keeping with industry best practices, we are consolidating the Box Next Generation SDKs and Box core SDKs into a single package for each programming language. This makes migration efforts much easier and allows seamless additions of new capabilities to existing applications still powered by Box core SDKs, which were maintained manually.

  **All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs.**

  For more details, see our <Link href="/guides/tooling/sdks/sdk-versioning">SDK versioning strategy document</Link>.
</Warning>

`v10` of Python SDK, Box TypeScript
SDK, Box .NET SDK, Box Java SDK, and Box Swift SDK are designed
to elevate the developer
experience and streamline your integration
with Box Content Cloud.

Here's what you can expect from `v10`:

* **Full API support**: New Box SDKs empower developers with complete coverage of the Box API ecosystem. You can access all the latest features and functionalities offered by Box and build feature-rich applications.
* **Rapid API updates**: The new auto-generation development approach allows you to add Box APIs to SDKs at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
* **Embedded documentation**: All objects and parameters are documented directly in the source code of the SDK so all the necessary information is stored in one place.
* **Enhanced convenience methods**: The newly introduced convenience methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers that help to ensure that you’re using variables correctly, and much more.

[javasdk]: https://github.com/box/box-java-sdk

[dotnetsdk]: https://github.com/box/box-windows-sdk-v2

[pythonsdk]: https://github.com/box/box-python-sdk

[nodesdk]: https://github.com/box/box-node-sdk

[iossdk]: https://github.com/box/box-ios-sdk

[androidsdk]: https://github.com/box/box-android-sdk

[android-docs]: https://github.com/box/box-java-sdk/blob/legacy/doc/android.md

[forum]: https://community.box.com/sdks-and-tools-7


# Box Java SDK
Source: https://developer.box.com/guides/tooling/sdks/java

Install the Box Java SDK with Maven or Gradle and start calling the Box API from a Java application.

You can use Box Java SDK to call Box APIs in a Java
project.

To install Java SDK, add a Gradle dependency or Maven dependency, or
clone the source into a project. Additionally, you can download one of the precompiled JARs from the releases page on GitHub.

<Card href="https://github.com/box/box-java-sdk/tree/main" title="Learn more about Java SDK on GitHub" />

## Gradle

Add the following dependency to the `build.gradle` file.

```shell theme={null}
compile 'com.box:box-java-sdk:2.32.0'
```

<Info>
  For the most up-to-date version number of the Java SDK, please refer to the
  [Java SDK Open Source page][java-os].
</Info>

## Maven

Add the following Maven dependency.

```xml theme={null}
<dependency>
    <groupId>com.box</groupId>
    <artifactId>box-java-sdk</artifactId>
    <version>2.32.0</version>
</dependency>
```

<Info>
  For the most up-to-date version number of the Java SDK, please refer to the
  [Java SDK Open Source page][java-os].
</Info>

## Installation from source

Download the SDK source from the [Java SDK GitHub repository][java-sdk-src] and
add it to a project.

## Precompiled JAR

Download one of the precompiled JARs for the Java SDK from the GitHub [releases
page][java-sdk-releases].

When using one of the precompiled JARs, it is important to also add the
following additional dependencies to the project.

| Dependency |
| - |
| [`minimal-json v0.9.1`][dependency-min-json] |
| [`jose4j v0.4.4`][dependency-jose] |
| [`bouncycastle bcprov-jdk15on v1.52`][dependency-bcprov] |
| [`bouncycastle bcpkix-jdk15on v1.52`][dependency-bcpkix] |
| [`Java Cryptography Extension (JCE)`][dependency-crypto] |

[npm]: https://www.npmjs.com/

[java-os]: http://opensource.box.com/box-java-sdk/

[java-sdk-src]: https://github.com/box/box-java-sdk/tree/main/src/main/java/com/box/sdkgen

[java-sdk-releases]: https://github.com/box/box-java-sdk/releases

[dependency-min-json]: https://github.com/ralfstx/minimal-json

[dependency-jose]: https://bitbucket.org/b_c/jose4j/wiki/Home

[dependency-bcprov]: http://mvnrepository.com/artifact/org.bouncycastle/bcprov-jdk15on

[dependency-bcpkix]: http://mvnrepository.com/artifact/org.bouncycastle/bcpkix-jdk15on

[dependency-crypto]: http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html

<RelatedLinks title="RELATED GUIDES" />


# Deprecated Box Next Gen Java SDK
Source: https://developer.box.com/guides/tooling/sdks/java-gen



<Warning>
  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts.

  Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  **All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs, and it is currently available as a separate [branch][sdk-branch].**
</Warning>

Check the [migration guide][migration] to learn how to switch from the Box Next Generation SDK to the Box core SDK `v10`.

For more details, see our <Link href="/guides/tooling/sdks/sdk-versioning">SDK versioning strategy document</Link>.

[sdk-branch]: https://github.com/box/box-java-sdk/tree/main

[migration]: https://github.com/box/box-java-sdk/blob/main/migration-guides/from-box-java-sdk-gen-v0-to-box-java-sdk.md


# Install Node SDK
Source: https://developer.box.com/guides/tooling/sdks/node



To call Box APIs from a Node project, install the Box Node SDK in one of two ways:

* As part of the [`box`](/guides/tooling/box-npm-package) npm package (recommended for new projects)
* As the standalone `box-node-sdk` package (supported for existing integrations)

<Card href="https://github.com/box/box-node-sdk" title="Learn more about Node SDK on GitHub" />

## Install with `npm install box` (recommended)

The `box` npm package installs the Box Node SDK and the [Box CLI](/guides/cli) as direct dependencies, so you get both tools in a single command.

### Prerequisites

Install [Node.js](https://nodejs.org/) 22 or later.

### Install

```shell theme={null}
npm install box
```

### Import the SDK

```javascript theme={null}
import BoxSDK from 'box/sdk';  // ESM
const BoxSDK = require('box/sdk');  // CommonJS
```

TypeScript types are included. After installation, you can also run any [CLI command](/guides/cli) with `npx box <command>` — no separate install is required.

The `box` package works with npm, yarn, pnpm, and bun.

<Info>
  **Existing `box-node-sdk` users:** If `box-node-sdk` works for you, leave it. The `box` package is for developers — and their coding agents — starting fresh. Existing code is unaffected.
</Info>

## Install `box-node-sdk` directly

Use the standalone package for existing projects.

### NPM installation

To install the Node SDK run the following command from your terminal
window or command prompt using the [Node Package Manager][npm].

```shell theme={null}
npm install box-node-sdk --save
```

### Yarn installation

Similarly, the SDK can be installed using the [Yarn package][yarn] manager.

```shell theme={null}
yarn add box-node-sdk
```

[npm]: https://www.npmjs.com/

[yarn]: https://yarnpkg.com/

[node]: https://github.com/box/box-node-sdk

<RelatedLinks title="RELATED GUIDES" />


# Install Python SDK
Source: https://developer.box.com/guides/tooling/sdks/python



You can use Box Python SDK to call Box APIs in a Python project.

<Card href="https://github.com/box/box-python-sdk" title="Learn more about Python SDK on GitHub" />

## Installation

To install the Python SDK run the following command from your terminal
window or command prompt using [pip][pip].

```shell theme={null}
pip install boxsdk
```

## JWT application

When working with a Box App that uses server-side <Link href="/guides/authentication/jwt">JWT authentication</Link>, install the following additional module:

```shell theme={null}
pip install "boxsdk[jwt]"
```

[pip]: https://pypi.org/project/pip/

[versioning]: /guides/tooling/sdks/sdk-versioning

<RelatedLinks title="RELATED GUIDES" />


# Deprecated Box Next Gen Python SDK
Source: https://developer.box.com/guides/tooling/sdks/python-gen



<Warning>
  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts.

  Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  **All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs, and it is currently available as a separate [branch][sdk-branch].**
</Warning>

Check the [migration guide][migration] to learn how to switch from the Box Next Generation SDK to the Box core SDK `v10`.

For more details, see our <Link href="/guides/tooling/sdks/sdk-versioning">SDK versioning strategy document</Link>.

[migration]: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-box-python-sdk-gen-v1-to-box-python-sdk.md

[sdk-branch]: https://github.com/box/box-python-sdk/tree/main


# Install Salesforce SDK
Source: https://developer.box.com/guides/tooling/sdks/salesforce



The Salesforce SDK can be deployed directly to Sandbox or Developer
organizations by using the [Deploy to Salesforce][deploy_salesforce]
functionality.

<Note>
  "Deploy to Salesforce" functionality is not owned or maintained by Box.
</Note>

The SDK is also distributed as an unmanaged package:

* [Production/Developer Package][salesforce_pkg_prod]
* [Sandbox Package][salesforce_pkg_sandbox]

<Warning>
  Unmanaged packages can't be upgraded once installed in a Salesforce org so
  future upgrades will have to be applied by cloning the repositories locally
  and updating classes from your IDE.
</Warning>

[deploy_salesforce]: https://githubsfdeploy.herokuapp.com/?owner=box&repo=box-salesforce-sdk

[salesforce_pkg_prod]: https://cloud.box.com/Box-Apex-SDK

[salesforce_pkg_sandbox]: https://cloud.box.com/Box-Apex-SDK-Sandbox

<RelatedLinks title="RELATED GUIDES" />


# Box SDK versioning strategy
Source: https://developer.box.com/guides/tooling/sdks/sdk-versioning



The Box core SDKs and the Box Next Generation SDKs were initially created as separate libraries. However, in keeping with industry best practices, **we are consolidating the Box Next Generation SDKs and the Box core SDKs into a single package for each programming language**. This makes migration efforts much easier and allows seamless addition of new capabilities to existing applications still powered by older versions of the Box core SDKs, which were maintained manually.

To facilitate this migration process, there are two actively maintained major Box core SDK versions:

* **A major version that follows sequential versioning for each SDK artifact and includes:** the manually maintained package and the generated one. This SDK version enables leveraging coexisting packages at the same time, and serves as a transition phase. Support for the consolidated version of each Box core SDK will continue in 2027.
* `v10` that includes **only the generated package**.

Here's what you can expect from generated packages of the Box SDK:

* **Full API support**: New Box SDKs empower developers with complete coverage of the Box API ecosystem. You can access all the latest features and functionalities offered by Box and build feature-rich applications.
* **Rapid API updates**: The new auto-generation development approach allows you to add Box APIs to SDKs at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
* **Embedded documentation**: All objects and parameters are documented directly in the source code of the SDK so all the necessary information is stored in one place.
* **Enhanced convenience methods**: The newly introduced convenience methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers that help to ensure that you’re using variables correctly, and much more.

## What it means for your project

<Columns>
  <Card icon="cog" title="1. Existing App - the Box core SDK" href={localizeLink("/guides/tooling/sdks/sdk-versioning/#migration-from-manually-maintained-sdk-version-to-the-consolidated-sdk-version")}>
    If you have an existing application that relies on the Box core SDK and you wish to further develop your project:

    **Action** Use the major version that includes consolidated packages. Start using convenience methods and new features from the generated package, and gradually migrate your codebase. Ultimately, migrate to the Box core SDK package (≥`v10.0.0`).
  </Card>

  <Card icon="code" title="2. Existing App - the Box Next Generation SDK" href={localizeLink("/guides/tooling/sdks/sdk-versioning/#migration-from-the-box-next-generation-sdks-to-the-box-core-sdks")}>
    If you have an existing application that relies only on the Box Next Generation SDK and you wish to further develop your project:

    **Action** Replace the library name in your package manager with the Box core SDK package (≥`v10.0.0`). Check migration guides for detailed instructions.
  </Card>

  <Card icon="code-branch" title="3. Existing App - the Box core SDK and the Box Next Generation SDK" href={localizeLink("/guides/tooling/sdks/sdk-versioning/#migration-from-manually-maintained-sdk-version-to-the-consolidated-sdk-version")}>
    If you have an existing application that relies both on the Box core SDK and the Next Generation SDK:

    **Action** Use the major version that includes consolidated packages. Ultimately, migrate to the Box core SDK package (≥`v10.0.0`).
  </Card>

  <Card icon="square-terminal" title="4. A New Application" href={localizeLink("/guides/tooling/sdks/sdk-versioning/#box-core-sdk-versions-and-artifacts-overview")}>
    If you are creating a new application:

    **Action** Use ≥`v10.0.0` of the Box core SDK.
  </Card>

  <Card icon="circle-info" title="5. No Active Development" href={localizeLink("/guides/tooling/sdks/sdk-versioning/#migration-from-manually-maintained-sdk-version-to-the-consolidated-sdk-version")}>
    If you have an existing application that you don't plan to change:

    **Action** Ensure your package manager includes the specific version to prevent accidental updates. We strongly recommend upgrading to the major version, which includes consolidated packages, to receive ongoing security patches and improvements.
  </Card>
</Columns>

## Versioning overview

### Box core SDK versions and artifacts overview

| Repository name | Artifact name | Includes both packages | Includes generated package only |
| - | - | - | - |
| [`box-python-sdk`][python-repo] | `boxsdk` | [`v4.X.Y`][python-combined] | [`≥v10.0.0`][python-v10] |
| [`box-node-sdk`][node-repo] | `box-node-sdk` | [`v4.X.Y`][node-combined] | [`≥v10.0.0`][node-v10] |
| [`box-java-sdk`][java-repo] | `box-java-sdk` | [`v5.X.Y`][java-combined] | [`≥v10.0.0`][java-v10] |
| [`box-windows-sdk-v2`][windows-repo] | `Box.V2`, `Box.V2.Core` | [`v6.X.Y`][windows-combined] | [`≥v10.0.0`][windows-v10] |
| [`box-ios-sdk`][ios-repo] | `BoxSDK` | [`v6.X.Y`][ios-combined] | [`≥v10.0.0`][ios-v10] |

## Box Next Gen SDKs deprecation

As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts. Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

**All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs.**

| Repository name | Artifact name | Note |
| - | - | - |
| `box-python-sdk-gen` | `box-sdk-gen` | Deprecated, use `boxsdk` [`≥v10.0.0`][python-v10] |
| `box-typescript-sdk-gen` | `box-typescript-sdk-gen` | Deprecated, use `box-node-sdk` [`≥v10.0.0`][node-v10] |
| `box-java-sdk-gen` | `box-java-sdk-gen` | Deprecated, use `box-java-sdk` [`≥v10.0.0`][java-v10] |
| `box-dotnet-sdk-gen` | `Box.Sdk.Gen` | Deprecated, use `Box.V2.Core` [`≥v10.0.0`][windows-v10] |
| `box-swift-sdk-gen` | `BoxSdkGen` | Deprecated, use `BoxSDK` [`≥v10.0.0`][ios-v10] |

## Migration

### Migration from manually maintained SDK version to the consolidated SDK version

Follow detailed migration guides to migrate from the manually maintained SDK version to the consolidated SDK version:

* [Python `v3` to `v4`][python-migration-v4]
* [Node `v3` to `v4`][node-migration-v4]
* [Java `v4` to `v5`][java-migration-v5]
* [.NET `v5` to `v6`][windows-migration-v6]
* [Swift `v5` to `v6`][ios-migration-v6]

Once your project is upgraded, follow the migration guides and migrate to the generated package.

### Migration to the generated package

Follow detailed migration guides to migrate to the generated package within the Box core SDKs.

* [Python: migrate from `boxsdk` to `box_sdk_gen` package][python-migration-gen]
* [Node: migrate from `box-node-sdk` to `sdk-gen`][node-migration-gen]
* [Java: migrate from `com.box.sdk` to `com.box.sdkgen` package][java-migration-gen]
* [.NET: migrate from `Box.V2` module to `Box.Sdk.Gen` module][windows-migration-gen]
* [Swift: migrate from `BoxSDK` module to `BoxSdkGen` module][swift-migration-gen]

### Migration from the Box Next Generation SDKs to the Box core SDKs

Follow detailed migration guides to migrate from the Box Next Generation SDKs to the Box core SDK ≥`v10`:

* [Python][python-migration-next-gen]
* [TypeScript/Node][ts-migration-next-gen]
* [Java][java-migration-next-gen]
* [.NET][dotnet-migration-next-gen]
* [Swift][swift-migration-next-gen]

[node-repo]: https://github.com/box/box-node-sdk

[windows-repo]: https://github.com/box/box-windows-sdk-v2

[java-repo]: https://github.com/box/box-java-sdk

[python-repo]: https://github.com/box/box-python-sdk

[ios-repo]: https://github.com/box/box-ios-sdk

[java-v10]: https://github.com/box/box-java-sdk/tree/main

[ios-v10]: https://github.com/box/box-ios-sdk/tree/main

[node-v10]: https://github.com/box/box-node-sdk/tree/main

[python-v10]: https://github.com/box/box-python-sdk/tree/main

[windows-v10]: https://github.com/box/box-windows-sdk-v2/tree/main

[python-combined]: https://github.com/box/box-python-sdk/tree/combined-sdk

[java-combined]: https://github.com/box/box-java-sdk/tree/combined-sdk

[node-combined]: https://github.com/box/box-node-sdk/tree/combined-sdk

[ios-combined]: https://github.com/box/box-ios-sdk/tree/combined-sdk

[windows-combined]: https://github.com/box/box-windows-sdk-v2/tree/combined-sdk

[python-migration-v4]: https://github.com/box/box-python-sdk/blob/combined-sdk/migration-guides/from-v3-to-v4.md

[node-migration-v4]: https://github.com/box/box-node-sdk/blob/combined-sdk/migration-guides/from-v3-to-v4.md

[ios-migration-v6]: https://github.com/box/box-ios-sdk/blob/combined-sdk/migration-guides/from-v5-to-v6.md

[windows-migration-v6]: https://github.com/box/box-windows-sdk-v2/blob/combined-sdk/migration-guides/from-v5-to-v6.md

[java-migration-v5]: https://github.com/box/box-java-sdk/blob/combined-sdk/migration-guides/from-v4-to-v5.md

[java-migration-next-gen]: https://github.com/box/box-java-sdk/blob/combined-sdk/migration-guides/from-box-java-sdk-gen-v0-to-box-java-sdk.md

[python-migration-next-gen]: https://github.com/box/box-python-sdk/blob/combined-sdk/migration-guides/from-box-python-sdk-gen-v1-to-box-python-sdk.md

[swift-migration-next-gen]: https://github.com/box/box-ios-sdk/blob/combined-sdk/migration-guides/from-box-swift-sdk-gen-v0-to-box-ios-sdk.md

[ts-migration-next-gen]: https://github.com/box/box-node-sdk/blob/combined-sdk/migration-guides/from-box-typescript-sdk-gen-v1-to-box-node-sdk.md

[dotnet-migration-next-gen]: https://github.com/box/box-windows-sdk-v2/blob/combined-sdk/migration-guides/from-dotnet-sdk-gen-v1-to-box-windows-sdk.md

[python-migration-gen]: https://github.com/box/box-python-sdk/blob/combined-sdk/migration-guides/from-boxsdk-to-box_sdk_gen.md

[windows-migration-gen]: https://github.com/box/box-windows-sdk-v2/blob/combined-sdk/migration-guides/from-box-v2-to-box-sdk-gen-namespace.md

[swift-migration-gen]: https://github.com/box/box-ios-sdk/blob/combined-sdk/migration-guides/from-BoxSDK-to-BoxSdkGen.md

[java-migration-gen]: https://github.com/box/box-java-sdk/blob/combined-sdk/migration-guides/from-com-box-sdk-to-com-box-sdkgen.md

[node-migration-gen]: https://github.com/box/box-node-sdk/blob/combined-sdk/migration-guides/from-box-node-sdk-to-sdk-gen.md

<RelatedLinks title="RELATED GUIDES" />


# Deprecated Box Next Gen Swift SDK
Source: https://developer.box.com/guides/tooling/sdks/swift-gen



<Warning>
  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts.

  Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  **All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs, and it is currently available as a separate [branch][sdk-branch].**
</Warning>

Check the [migration guide][migration] to learn how to switch from the Box Next Generation SDK to the Box core SDK `v10`.

For more details, see our <Link href="/guides/tooling/sdks/sdk-versioning">SDK versioning strategy document</Link>.

[migration]: https://github.com/box/box-ios-sdk/blob/main/migration-guides/from-box-swift-sdk-gen-v0-to-box-ios-sdk.md

[sdk-branch]: https://github.com/box/box-ios-sdk/tree/main


# Deprecated Box Next Gen TypeScript SDK
Source: https://developer.box.com/guides/tooling/sdks/typescript-gen



<Warning>
  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts.

  Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  **All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs, and it is currently available as a separate [branch][sdk-branch].**
</Warning>

Check the [migration guide][migration] to learn how to switch from the Box Next Generation SDK to the Box core SDK `v10`.

For more details, see our <Link href="/guides/tooling/sdks/sdk-versioning">SDK versioning strategy document</Link>.

[migration]: https://github.com/box/box-node-sdk/blob/main/migration-guides/from-box-typescript-sdk-gen-v1-to-box-node-sdk.md

[sdk-branch]: https://github.com/box/box-node-sdk/tree/main


# Remove watermark from folder
Source: https://developer.box.com/reference/delete-folders-id-watermark

box-openapi.json DELETE /folders/{folder_id}/watermark
Removes the watermark from a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove web link
Source: https://developer.box.com/reference/delete-web-links-id

box-openapi.json DELETE /web_links/{web_link_id}
Deletes a web link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove webhook
Source: https://developer.box.com/reference/delete-webhooks-id

box-openapi.json DELETE /webhooks/{webhook_id}
Deletes a webhook.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get web link
Source: https://developer.box.com/reference/get-web-links-id

box-openapi.json GET /web_links/{web_link_id}
Retrieve information about a web link.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all webhooks
Source: https://developer.box.com/reference/get-webhooks

box-openapi.json GET /webhooks
Returns all defined webhooks for the requesting application.

This API only returns webhooks that are applied to files or folders that are owned by the authenticated user. This means that an admin can not see webhooks created by a service account unless the admin has access to those folders, and vice versa.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get webhook
Source: https://developer.box.com/reference/get-webhooks-id

box-openapi.json GET /webhooks/{webhook_id}
Retrieves a specific webhook.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List workflows
Source: https://developer.box.com/reference/get-workflows

box-openapi.json GET /workflows
Returns list of workflows that act on a given `folder ID`, and have a flow with a trigger type of `WORKFLOW_MANUAL_START`.

You application must be authorized to use the `Manage Box Relay` application scope within the developer console in to use this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Download zip archive
Source: https://developer.box.com/reference/get-zip-downloads-id-content

box-openapi.json GET /zip_downloads/{zip_download_id}/content
Returns the contents of a `zip` archive in binary format. This URL does not require any form of authentication and could be used in a user's browser to download the archive to a user's device.

By default, this URL is only valid for a few seconds from the creation of the request for this archive. Once a download has started it can not be stopped and resumed, instead a new request for a zip archive would need to be created.

The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](/reference/post-zip-downloads) API to request to create a `zip` archive, and then follow the `download_url` field in the response to this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get zip download status
Source: https://developer.box.com/reference/get-zip-downloads-id-status

box-openapi.json GET /zip_downloads/{zip_download_id}/status
Returns the download status of a `zip` archive, allowing an application to inspect the progress of the download as well as the number of items that might have been skipped.

This endpoint can only be accessed once the download has started. Subsequently this endpoint is valid for 12 hours from the start of the download.

The URL of this endpoint should not be considered as fixed. Instead, use the [Create zip download](/reference/post-zip-downloads) API to request to create a `zip` archive, and then follow the `status_url` field in the response to this endpoint.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create web link
Source: https://developer.box.com/reference/post-web-links

box-openapi.json POST /web_links
Creates a web link object within a folder.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create webhook
Source: https://developer.box.com/reference/post-webhooks

box-openapi.json POST /webhooks
Creates a webhook.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Starts workflow based on request body
Source: https://developer.box.com/reference/post-workflows-id-start

box-openapi.json POST /workflows/{workflow_id}/start
Initiates a flow with a trigger type of `WORKFLOW_MANUAL_START`.

You application must be authorized to use the `Manage Box Relay` application scope within the developer console.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create zip download
Source: https://developer.box.com/reference/post-zip-downloads

box-openapi.json POST /zip_downloads
Creates a request to download multiple files and folders as a single `zip` archive file. This API does not return the archive but instead performs all the checks to ensure that the user has access to all the items, and then returns a `download_url` and a `status_url` that can be used to download the archive.

The limit for an archive is either the Account's upload limit or 10,000 files, whichever is met first.

**Note**: Downloading a large file can be affected by various factors such as distance, network latency, bandwidth, and congestion, as well as packet loss ratio and current server load. For these reasons we recommend that a maximum ZIP archive total size does not exceed 25GB.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update web link
Source: https://developer.box.com/reference/put-web-links-id

box-openapi.json PUT /web_links/{web_link_id}
Updates a web link object.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update webhook
Source: https://developer.box.com/reference/put-webhooks-id

box-openapi.json PUT /webhooks/{webhook_id}
Updates a webhook.

<Note>
  This endpoint is in the version **2024.0**. No changes are required to continue using it. For more details, see **[Box API versioning](/guides/api-calls/api-versioning-strategy)**.

  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Archives resources
Source: https://developer.box.com/reference/v2025.0/archives-resources



A set of endpoints used to manage archives.

## Archive

An archive is a folder dedicated to storing content that is redundant, outdated, or trivial. Content in an archive is not accessible to its owner and collaborators. To use this feature, you must request GCM scope for your Box application.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represents an archive. |
  | `type` | `enum<string>` | Yes | The value is always `archive`. Available options: `archive`. |
  | `name` | `string` | Yes | The name of the archive. The following restrictions to the archive name apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. |
  | `size` | `integer` | Yes | The size of the archive in bytes. |
  | `description` | `string` | No | The description of the archive. Can be `null`. |
  | `owned_by` | `object` | No | The part of an archive API response that describes the user who owns the archive. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "archive",
    "name": "Archive",
    "size": 123456789,
    "description": "This is an archive for important documents.",
    "owned_by": {
      "id": "12345",
      "type": "user"
    }
  }
  ```
</Accordion>

## Archives

A list of archives.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Archive](#archive) | No | A list in which each entry represents an archive object. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "archive",
        "name": "Archive",
        "size": 123456789,
        "description": "This is an archive for important documents.",
        "owned_by": {
          "id": "12345",
          "type": "user"
        }
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Delete archive
Source: https://developer.box.com/reference/v2025.0/delete-archives-id

box-openapi-v2025.0.json DELETE /archives/{archive_id}
Permanently deletes an archive.

To learn more about the archive APIs, see the [Archive API Guide](/guides/archives).

<Danger>
This endpoint is currently unavailable. Please contact support for assistance.
</Danger>

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete Box Doc Gen template
Source: https://developer.box.com/reference/v2025.0/delete-docgen-templates-id

box-openapi-v2025.0.json DELETE /docgen_templates/{template_id}
Unmarks file as Box Doc Gen template.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Remove Box Hub collaboration
Source: https://developer.box.com/reference/v2025.0/delete-hub-collaborations-id

box-openapi-v2025.0.json DELETE /hub_collaborations/{hub_collaboration_id}
Deletes a single Box Hub collaboration.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete Box Hub
Source: https://developer.box.com/reference/v2025.0/delete-hubs-id

box-openapi-v2025.0.json DELETE /hubs/{hub_id}
Deletes a single Box Hub.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Delete single shield list by shield list id
Source: https://developer.box.com/reference/v2025.0/delete-shield-lists-id

box-openapi-v2025.0.json DELETE /shield_lists/{shield_list_id}
Delete a single shield list by its ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Box Doc Gen resources
Source: https://developer.box.com/reference/v2025.0/docgen-resources



Doc Gen is used to automatically generate documents.

## Box Doc Gen batch (Base)

The basic representation of a Box Doc Gen batch object. A Box Doc Gen batch contains one or more Box Doc Gen jobs.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represents a Box Doc Gen batch. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_batch`. Available options: `docgen_batch`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_batch"
  }
  ```
</Accordion>

## Box Doc Gen job

A standard representation of a Box Doc Gen job.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Doc Gen job. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_job`. Available options: `docgen_job`. |
  | `batch` | [Box Doc Gen batch (Base)](#box-doc-gen-batch-base) | Yes | Box Doc Gen batch that the job belongs to. |
  | `template_file` | `File reference` | Yes | Box Doc Gen template used in the job. |
  | `template_file_version` | `File version (Base)` | Yes | File version of a template. |
  | `output_file` | `File reference` | No | The output file of the job. This property is `null` until the job is completed. Can be `null`. |
  | `output_file_version` | `File version (Base)` | No | File version of the output file. This property is `null` until the job is completed. Can be `null`. |
  | `status` | `enum<string>` | Yes | Status of the job. Available options: `submitted`, `completed`, `failed`, `completed_with_error`, `pending`. |
  | `output_type` | `string` | Yes | Type of the generated file. |
  | `failures` | `object` | No | Errors and warnings that occurred during document generation. Can be `null`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_job",
    "batch": {
      "id": "12345",
      "type": "docgen_batch"
    },
    "template_file": {
      "type": "file",
      "id": "42037322"
    },
    "template_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "output_file": {
      "type": "file",
      "id": "42037322"
    },
    "output_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "status": "completed",
    "output_type": "docx",
    "failures": {
      "errors": [
        "The tag 'customer_name' was not provided in the input data."
      ],
      "warnings": [
        "The tag 'optional_field' was provided but not used in the template."
      ]
    }
  }
  ```
</Accordion>

## Box Doc Gen job (Base)

The basic representation of a Box Doc Gen job.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Doc Gen job. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_job`. Available options: `docgen_job`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_job"
  }
  ```
</Accordion>

## Box Doc Gen job (Full)

A full representation of a Box Doc Gen job.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Doc Gen job. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_job`. Available options: `docgen_job`. |
  | `batch` | [Box Doc Gen batch (Base)](#box-doc-gen-batch-base) | Yes | Box Doc Gen batch that the job belongs to. |
  | `template_file` | `File reference` | Yes | Box Doc Gen template used in the job. |
  | `template_file_version` | `File version (Base)` | Yes | File version of a template. |
  | `output_file` | `File reference` | No | The output file of the job. This property is `null` until the job is completed. Can be `null`. |
  | `output_file_version` | `File version (Base)` | No | File version of the output file. This property is `null` until the job is completed. Can be `null`. |
  | `status` | `enum<string>` | Yes | Status of the job. Available options: `submitted`, `completed`, `failed`, `completed_with_error`, `pending`. |
  | `output_type` | `string` | Yes | Type of the generated file. |
  | `failures` | `object` | No | Errors and warnings that occurred during document generation. Can be `null`. |
  | `created_at` | `string` | No | Time of job creation. Read-only. |
  | `created_by` | `User (Base)` | Yes | User who created the job. |
  | `enterprise` | `Enterprise reference` | Yes | ID of the enterprise. |
  | `source` | `string` | Yes | Source of the request. Read-only. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_job",
    "batch": {
      "id": "12345",
      "type": "docgen_batch"
    },
    "template_file": {
      "type": "file",
      "id": "42037322"
    },
    "template_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "output_file": {
      "type": "file",
      "id": "42037322"
    },
    "output_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "status": "completed",
    "output_type": "docx",
    "failures": {
      "errors": [
        "The tag 'customer_name' was not provided in the input data."
      ],
      "warnings": [
        "The tag 'optional_field' was provided but not used in the template."
      ]
    },
    "created_at": "2022-05-11T10:56:11-07:00",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "enterprise": {
      "id": "1910967",
      "type": "enterprise"
    },
    "source": "api"
  }
  ```
</Accordion>

## Box Doc Gen jobs

A list of Box Doc Gen jobs with a standard set of parameters.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen job](#box-doc-gen-job) | No | List of jobs. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345",
        "type": "docgen_job",
        "batch": {
          "id": "12345",
          "type": "docgen_batch"
        },
        "template_file": {
          "type": "file",
          "id": "42037322"
        },
        "template_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "output_file": {
          "type": "file",
          "id": "42037322"
        },
        "output_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "status": "completed",
        "output_type": "docx",
        "failures": {
          "errors": [
            "The tag 'customer_name' was not provided in the input data."
          ],
          "warnings": [
            "The tag 'optional_field' was provided but not used in the template."
          ]
        }
      }
    ]
  }
  ```
</Accordion>

## Box Doc Gen jobs (Full)

A list of Box Doc Gen jobs with a full set of parameters.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen job (Full)](#box-doc-gen-job-full) | No | List of jobs. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345",
        "type": "docgen_job",
        "batch": {
          "id": "12345",
          "type": "docgen_batch"
        },
        "template_file": {
          "type": "file",
          "id": "42037322"
        },
        "template_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "output_file": {
          "type": "file",
          "id": "42037322"
        },
        "output_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "status": "completed",
        "output_type": "docx",
        "failures": {
          "errors": [
            "The tag 'customer_name' was not provided in the input data."
          ],
          "warnings": [
            "The tag 'optional_field' was provided but not used in the template."
          ]
        },
        "created_at": "2022-05-11T10:56:11-07:00",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "enterprise": {
          "id": "1910967",
          "type": "enterprise"
        },
        "source": "api"
      }
    ]
  }
  ```
</Accordion>


# Box Doc Gen templates resources
Source: https://developer.box.com/reference/v2025.0/docgen-template-resources



Doc Gen templates are used as input to generate documents.

## Box Doc Gen tags

A list of Box Doc Gen tags.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen template tag](#box-doc-gen-template-tag) | No | List of tags. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "tag_content": "{{item.name}}",
        "tag_type": "text",
        "json_paths": [
          "products",
          "products.name"
        ]
      }
    ]
  }
  ```
</Accordion>

## Box Doc Gen tags processing message

A message informing the user that document tags are still being processed.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `message` | `string` | Yes | A message informing the user that document tags are still being processed. Read-only. |

  ```json Example theme={null}
  {
    "message": "Processing tags for this file."
  }
  ```
</Accordion>

## Box Doc Gen template

A Box Doc Gen template object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `file` | `File reference` | No | Enable the file to generate a document from. |
  | `file_name` | `string` | No | The name of the template. Can be `null`. |

  ```json Example theme={null}
  {
    "file": {
      "type": "file",
      "id": "42037322"
    },
    "file_name": "Official contract"
  }
  ```
</Accordion>

## Box Doc Gen template tag

A Box Doc Gen template tag object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `tag_content` | `string` | Yes | The content of the tag. Read-only. |
  | `tag_type` | `enum<string>` | Yes | Type of the tag. Available options: `text`, `arithmetic`, `conditional`, `for-loop`, `table-loop`, `image`. Read-only. |
  | `json_paths` | array of `string` | Yes | List of the paths. Read-only. |

  ```json Example theme={null}
  {
    "tag_content": "{{item.name}}",
    "tag_type": "text",
    "json_paths": [
      "products",
      "products.name"
    ]
  }
  ```
</Accordion>

## Box Doc Gen templates

List of Box Doc Gen templates.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen template](#box-doc-gen-template) | No | A list of templates. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "file": {
          "type": "file",
          "id": "42037322"
        },
        "file_name": "Official contract"
      }
    ]
  }
  ```
</Accordion>


# Enterprise Configurations resources
Source: https://developer.box.com/reference/v2025.0/enterprise-configurations-resources



Enterprise configurations admins interact with to drive Box product behavior.

## Enterprise configuration

The enterprise configuration for a given enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The identifier of the enterprise configuration which is the ID of the enterprise. |
  | `type` | `enum<string>` | No | The value will always be `enterprise_configuration`. Available options: `enterprise_configuration`. |
  | `security` | [Enterprise configuration security](#enterprise-configuration-security) | No | The enterprise configurations for the security category. Can be `null`. |
  | `content_and_sharing` | [Enterprise configuration content and sharing](#enterprise-configuration-content-and-sharing) | No | The enterprise configurations for the content and sharing category. Can be `null`. |
  | `user_settings` | [Enterprise configuration user settings](#enterprise-configuration-user-settings) | No | The enterprise configurations for the user settings category. Can be `null`. |
  | `shield` | [Enterprise configuration shield](#enterprise-configuration-shield) | No | The enterprise configurations for the shield category. If shield is turned off for given enterprise, the response will be 404. Can be `null`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "enterprise_configuration",
    "security": {
      "is_managed_user_signup_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_signup_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_signup_corporate_email_enabled": {
        "is_used": true,
        "value": true
      },
      "is_new_user_notification_daily_digest_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_email_change_disabled": {
        "is_used": true,
        "value": true
      },
      "is_multi_factor_auth_required": {
        "is_used": true,
        "value": true
      },
      "is_weak_password_prevention_enabled": {
        "is_used": true,
        "value": true
      },
      "is_password_leak_detection_enabled": {
        "is_used": true,
        "value": true
      },
      "last_password_reset_at": {
        "is_used": true,
        "value": "2012-12-12T10:53:43-08:00"
      },
      "is_password_request_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "is_password_change_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "is_strong_password_for_ext_collab_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_migration_disabled": {
        "is_used": true,
        "value": true
      },
      "join_link": {
        "is_used": true,
        "value": "value of configuration"
      },
      "join_url": {
        "is_used": true,
        "value": "value of configuration"
      },
      "failed_login_attempts_to_trigger_admin_notification": {
        "is_used": true,
        "value": 1234
      },
      "password_min_length": {
        "is_used": true,
        "value": 1234
      },
      "password_min_uppercase_characters": {
        "is_used": true,
        "value": 1234
      },
      "password_min_numeric_characters": {
        "is_used": true,
        "value": 1234
      },
      "password_min_special_characters": {
        "is_used": true,
        "value": 1234
      },
      "password_reset_frequency": {
        "is_used": true,
        "value": "value of configuration"
      },
      "previous_password_reuse_limit": {
        "is_used": true,
        "value": "value of configuration"
      },
      "session_duration": {
        "is_used": true,
        "value": "value of configuration"
      },
      "external_collab_multi_factor_auth_settings": {
        "is_used": true,
        "value": {
          "denylist_domains": [
            "example.com"
          ],
          "denylist_emails": [
            "spam@example.com"
          ],
          "allowlist_domains": [
            "example.com"
          ],
          "allowlist_emails": [
            "mail@example.com"
          ],
          "state": "enabled",
          "scheduled_status": "inprogress",
          "scheduled_at": "2012-12-12T10:53:43-08:00",
          "factor_type_settings": "totp"
        }
      },
      "keysafe": {
        "is_used": true,
        "value": {
          "keysafe_enabled": true,
          "cloud_provider": "",
          "key_id": "1234",
          "account_id": "1234",
          "location_id": "1234",
          "project_id": "1234",
          "keyring_id": "1234"
        }
      },
      "is_custom_session_duration_enabled": {
        "is_used": true,
        "value": true
      },
      "custom_session_duration_value": {
        "is_used": true,
        "value": "value of configuration"
      },
      "custom_session_duration_groups": {
        "is_used": true,
        "value": [
          {
            "id": "1234",
            "name": "Group Name"
          }
        ]
      },
      "multi_factor_auth_type": {
        "is_used": true,
        "value": "value of configuration"
      },
      "enforced_mfa_frequency": {
        "is_used": true,
        "value": {
          "days": 30,
          "hours": 24
        }
      }
    },
    "content_and_sharing": {
      "enterprise_feature_settings": [
        {
          "is_used": true,
          "value": {
            "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
            "feature": {
              "id": "canvas"
            },
            "state": "enabled",
            "can_configure": true,
            "is_configured": true,
            "allowlist": [
              {
                "type": "user",
                "id": "12345"
              }
            ],
            "denylist": [
              {
                "type": "user",
                "id": "12345"
              }
            ]
          }
        }
      ],
      "sharing_item_type": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_company_definition": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_access": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_default_access": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_default_permissions_selected": {
        "is_used": true,
        "value": {
          "shared_links_option": "settings_shared_link_preview",
          "default_shared_link_type": "settings_default_shared_link_preview",
          "notes_shared_link_option": "settings_notes_option_to_edit",
          "default_notes_shared_link_type": "settings_default_notes_shared_link_to_edit"
        }
      },
      "is_open_custom_urls_disabled": {
        "is_used": true,
        "value": true
      },
      "is_custom_domain_hidden_in_shared_link": {
        "is_used": true,
        "value": true
      },
      "collaboration_permissions": {
        "is_used": true,
        "value": {
          "is_co_owner_role_enabled": true,
          "is_editor_role_enabled": true,
          "is_previewer_role_enabled": true,
          "is_previewer_uploader_role_enabled": true,
          "is_uploader_role_enabled": true,
          "is_viewer_role_enabled": true,
          "is_viewer_uploader_role_enabled": true
        }
      },
      "default_collaboration_role": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_invite_privilege_restricted": {
        "is_used": true,
        "value": true
      },
      "collaboration_restrictions": {
        "is_used": true,
        "value": [
          "internal"
        ]
      },
      "is_collaborator_invite_links_disabled": {
        "is_used": true,
        "value": true
      },
      "is_invite_group_collaborator_disabled": {
        "is_used": true,
        "value": true
      },
      "is_ownership_transfer_restricted": {
        "is_used": true,
        "value": true
      },
      "external_collaboration_status": {
        "is_used": true,
        "value": "enable_external_collaboration"
      },
      "external_collaboration_allowlist_users": {
        "is_used": true,
        "value": [
          {
            "id": 1234,
            "name": "John Doe",
            "email": "johndoe@box.com"
          }
        ]
      },
      "is_watermarking_enterprise_feature_enabled": {
        "is_used": true,
        "value": true
      },
      "is_root_content_creation_restricted": {
        "is_used": true,
        "value": true
      },
      "is_tag_creation_restricted": {
        "is_used": true,
        "value": true
      },
      "tag_creation_restriction": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_email_uploads_enabled": {
        "is_used": true,
        "value": true
      },
      "is_custom_settings_enabled": {
        "is_used": true,
        "value": true
      },
      "is_forms_login_required": {
        "is_used": true,
        "value": true
      },
      "is_forms_branding_default_enabled": {
        "is_used": true,
        "value": true
      },
      "is_cc_free_trial_active": {
        "is_used": true,
        "value": true
      },
      "is_file_request_editors_allowed": {
        "is_used": true,
        "value": true
      },
      "is_file_request_branding_default_enabled": {
        "is_used": true,
        "value": true
      },
      "is_file_request_login_required": {
        "is_used": true,
        "value": true
      },
      "is_shared_links_expiration_enabled": {
        "is_used": true,
        "value": true
      },
      "shared_links_expiration_days": {
        "is_used": true,
        "value": 1234
      },
      "is_public_shared_links_expiration_enabled": {
        "is_used": true,
        "value": true
      },
      "public_shared_links_expiration_days": {
        "is_used": true,
        "value": 1234
      },
      "shared_expiration_target": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_shared_links_expiration_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "shared_links_expiration_notification_days": {
        "is_used": true,
        "value": 1234
      },
      "is_shared_links_expiration_notification_prevented": {
        "is_used": true,
        "value": true
      },
      "is_auto_delete_enabled": {
        "is_used": true,
        "value": true
      },
      "auto_delete_days": {
        "is_used": true,
        "value": 1234
      },
      "is_auto_delete_expiration_modification_prevented": {
        "is_used": true,
        "value": true
      },
      "auto_delete_target": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_collaboration_expiration_enabled": {
        "is_used": true,
        "value": true
      },
      "collaboration_expiration_days": {
        "is_used": true,
        "value": 1234
      },
      "is_collaboration_expiration_modification_prevented": {
        "is_used": true,
        "value": true
      },
      "is_collaboration_expiration_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "collaboration_expiration_target": {
        "is_used": true,
        "value": "value of configuration"
      },
      "trash_auto_clear_time": {
        "is_used": true,
        "value": 1234
      },
      "permanent_deletion_access": {
        "is_used": true,
        "value": "value of configuration"
      },
      "permanent_deletion_allowlist_users": {
        "is_used": true,
        "value": [
          {
            "id": 1234,
            "name": "John Doe",
            "email": "johndoe@box.com"
          }
        ]
      }
    },
    "user_settings": {
      "enterprise_feature_settings": [
        {
          "is_used": true,
          "value": {
            "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
            "feature": {
              "id": "canvas"
            },
            "state": "enabled",
            "can_configure": true,
            "is_configured": true,
            "allowlist": [
              {
                "type": "user",
                "id": "12345"
              }
            ],
            "denylist": [
              {
                "type": "user",
                "id": "12345"
              }
            ]
          }
        }
      ],
      "user_invites_expiration_time_frame": {
        "is_used": true,
        "value": "7 days"
      },
      "is_username_change_restricted": {
        "is_used": true,
        "value": true
      },
      "is_box_sync_restricted_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_view_all_users_enabled_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_device_limit_exemption_enabled_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_external_collaboration_restricted_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_unlimited_storage_enabled_for_new_users": {
        "is_used": true,
        "value": true
      },
      "new_user_default_storage_limit": {
        "is_used": true,
        "value": 1234
      },
      "new_user_default_timezone": {
        "is_used": true,
        "value": "GMT-05:00 America\\/Chicago CDT"
      },
      "new_user_default_language": {
        "is_used": true,
        "value": "English (US)"
      },
      "is_enterprise_sso_required": {
        "is_used": true,
        "value": true
      },
      "is_enterprise_sso_in_testing": {
        "is_used": true,
        "value": true
      },
      "is_sso_auto_add_groups_enabled": {
        "is_used": true,
        "value": true
      },
      "is_sso_auto_add_user_to_groups_enabled": {
        "is_used": true,
        "value": true
      },
      "is_sso_auto_remove_user_from_groups_enabled": {
        "is_used": true,
        "value": true
      },
      "user_tracking_codes": {
        "is_used": true,
        "value": [
          {
            "id": 1234,
            "name": "Employee ID"
          }
        ]
      },
      "number_of_user_tracking_codes_remaining": {
        "is_used": true,
        "value": 1234
      },
      "is_instant_login_restricted": {
        "is_used": true,
        "value": true
      }
    },
    "shield": {
      "shield_rules": [
        {
          "id": "1234567890",
          "type": "shield_rule",
          "rule_category": "Malicious Content",
          "name": "Block malicious files",
          "description": "Blocks files identified as malicious content",
          "priority": "high",
          "created_at": "2012-12-12T10:53:43-08:00",
          "modified_at": "2012-12-12T10:53:43-08:00"
        }
      ]
    }
  }
  ```
</Accordion>

## Enterprise configuration content and sharing

The enterprise configuration for the content and sharing category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `enterprise_feature_settings` | array of `Enterprise feature settings item` | No | |
  | `sharing_item_type` | `Enterprise configuration item with string value` | No | The selected option for the type of items that sharing is enable for. |
  | `shared_link_company_definition` | `Enterprise configuration item with string value` | No | The definition of the company for shared links (such as `enterprise_id`, `users_with_email_domain`). |
  | `shared_link_access` | `Enterprise configuration item with string value` | No | The selected option for who has access to shared links. |
  | `shared_link_default_access` | `Enterprise configuration item with string value` | No | The selected option for the access level of shared links. |
  | `shared_link_default_permissions_selected` | `Enterprise configuration item` | No | The permissions selected for shared links for each type. |
  | `is_open_custom_urls_disabled` | `Enterprise configuration item with boolean value` | No | Disables custom shared link URLs for public access. |
  | `is_custom_domain_hidden_in_shared_link` | `Enterprise configuration item with boolean value` | No | Hides the custom domain in shared links. |
  | `collaboration_permissions` | `Enterprise configuration item` | No | |
  | `default_collaboration_role` | `Enterprise configuration item with string value` | No | The current default collaboration role. |
  | `is_invite_privilege_restricted` | `Enterprise configuration item with boolean value` | No | Restrict invites to only admin, folder owners, and co-owners. |
  | `collaboration_restrictions` | `Enterprise configuration item` | No | The collaboration restrictions for the enterprise. |
  | `is_collaborator_invite_links_disabled` | `Enterprise configuration item with boolean value` | No | Disables users to invite collaborators using invite links. |
  | `is_invite_group_collaborator_disabled` | `Enterprise configuration item with boolean value` | No | Disables users to invite group collaborators. |
  | `is_ownership_transfer_restricted` | `Enterprise configuration item with boolean value` | No | Prevents ownership transfer to external users. |
  | `external_collaboration_status` | `Enterprise configuration item` | No | The external collaboration status. Possible values: `enable_external_collaboration`, `limit_collaboration_to_allowlisted_domains`, `limit_collaboration_to_users_within_enterprise`. |
  | `external_collaboration_allowlist_users` | `Enterprise configuration item` | No | The external collaboration allowlist users. |
  | `is_watermarking_enterprise_feature_enabled` | `Enterprise configuration item with boolean value` | No | Enables watermarking enterprise feature. |
  | `is_root_content_creation_restricted` | `Enterprise configuration item with boolean value` | No | Only admins can create and delete first-level folders, files, and bookmarks. |
  | `is_tag_creation_restricted` | `Enterprise configuration item with boolean value` | No | Only selected users can create tags. |
  | `tag_creation_restriction` | `Enterprise configuration item with string value` | No | The selected option for tag creation restriction. |
  | `is_email_uploads_enabled` | `Enterprise configuration item with boolean value` | No | Enables email uploads. |
  | `is_custom_settings_enabled` | `Enterprise configuration item with boolean value` | No | Enables custom settings. |
  | `is_forms_login_required` | `Enterprise configuration item with boolean value` | No | Require uploaders to log in with a Box account for Forms. |
  | `is_forms_branding_default_enabled` | `Enterprise configuration item with boolean value` | No | Company brand color and logo defaults to Logo for use on Brand Color for Forms. |
  | `is_cc_free_trial_active` | `Enterprise configuration item with boolean value` | No | Indicates if the enterprise is on a free trial. |
  | `is_file_request_editors_allowed` | `Enterprise configuration item with boolean value` | No | Indicates if editors are allowed for file requests feature. |
  | `is_file_request_branding_default_enabled` | `Enterprise configuration item with boolean value` | No | Company brand color and logo defaults to Logo for use on Brand Color for File Requests. |
  | `is_file_request_login_required` | `Enterprise configuration item with boolean value` | No | Require uploaders to log in with a Box account for File Requests. |
  | `is_shared_links_expiration_enabled` | `Enterprise configuration item with boolean value` | No | Enables shared links expiration. |
  | `shared_links_expiration_days` | `Enterprise configuration item with integer value` | No | The expiration time for shared links. |
  | `is_public_shared_links_expiration_enabled` | `Enterprise configuration item with boolean value` | No | Enables public shared links expiration. |
  | `public_shared_links_expiration_days` | `Enterprise configuration item with integer value` | No | The expiration time for public shared links. |
  | `shared_expiration_target` | `Enterprise configuration item with string value` | No | The selected option of types for applying shared link expiration. |
  | `is_shared_links_expiration_notification_enabled` | `Enterprise configuration item with boolean value` | No | Enables shared links expiration notification. |
  | `shared_links_expiration_notification_days` | `Enterprise configuration item with integer value` | No | The number of days before expiration to notify users. |
  | `is_shared_links_expiration_notification_prevented` | `Enterprise configuration item with boolean value` | No | Prevents users from disabling shared links expiration notification. |
  | `is_auto_delete_enabled` | `Enterprise configuration item with boolean value` | No | Enables auto delete. |
  | `auto_delete_days` | `Enterprise configuration item with integer value` | No | The number of days before auto delete. |
  | `is_auto_delete_expiration_modification_prevented` | `Enterprise configuration item with boolean value` | No | Prevents users from modifying auto delete expiration. |
  | `auto_delete_target` | `Enterprise configuration item with string value` | No | The selected option of types for applying auto delete. |
  | `is_collaboration_expiration_enabled` | `Enterprise configuration item with boolean value` | No | Enables collaboration expiration. |
  | `collaboration_expiration_days` | `Enterprise configuration item with integer value` | No | The number of days before collaboration expiration. |
  | `is_collaboration_expiration_modification_prevented` | `Enterprise configuration item with boolean value` | No | Prevents users from modifying collaboration expiration. |
  | `is_collaboration_expiration_notification_enabled` | `Enterprise configuration item with boolean value` | No | Enables collaboration expiration notification. |
  | `collaboration_expiration_target` | `Enterprise configuration item with string value` | No | The selected option of types for applying collaboration expiration. |
  | `trash_auto_clear_time` | `Enterprise configuration item with integer value` | No | The time before items are permanently deleted from the trash in seconds. |
  | `permanent_deletion_access` | `Enterprise configuration item with string value` | No | The selected option for who can delete items from the trash. |
  | `permanent_deletion_allowlist_users` | `Enterprise configuration item` | No | The allowlist users for permanently deleting items from the trash. |

  ```json Example theme={null}
  {
    "enterprise_feature_settings": [
      {
        "is_used": true,
        "value": {
          "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
          "feature": {
            "id": "canvas"
          },
          "state": "enabled",
          "can_configure": true,
          "is_configured": true,
          "allowlist": [
            {
              "type": "user",
              "id": "12345"
            }
          ],
          "denylist": [
            {
              "type": "user",
              "id": "12345"
            }
          ]
        }
      }
    ],
    "sharing_item_type": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_company_definition": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_access": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_default_access": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_default_permissions_selected": {
      "is_used": true,
      "value": {
        "shared_links_option": "settings_shared_link_preview",
        "default_shared_link_type": "settings_default_shared_link_preview",
        "notes_shared_link_option": "settings_notes_option_to_edit",
        "default_notes_shared_link_type": "settings_default_notes_shared_link_to_edit"
      }
    },
    "is_open_custom_urls_disabled": {
      "is_used": true,
      "value": true
    },
    "is_custom_domain_hidden_in_shared_link": {
      "is_used": true,
      "value": true
    },
    "collaboration_permissions": {
      "is_used": true,
      "value": {
        "is_co_owner_role_enabled": true,
        "is_editor_role_enabled": true,
        "is_previewer_role_enabled": true,
        "is_previewer_uploader_role_enabled": true,
        "is_uploader_role_enabled": true,
        "is_viewer_role_enabled": true,
        "is_viewer_uploader_role_enabled": true
      }
    },
    "default_collaboration_role": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_invite_privilege_restricted": {
      "is_used": true,
      "value": true
    },
    "collaboration_restrictions": {
      "is_used": true,
      "value": [
        "internal"
      ]
    },
    "is_collaborator_invite_links_disabled": {
      "is_used": true,
      "value": true
    },
    "is_invite_group_collaborator_disabled": {
      "is_used": true,
      "value": true
    },
    "is_ownership_transfer_restricted": {
      "is_used": true,
      "value": true
    },
    "external_collaboration_status": {
      "is_used": true,
      "value": "enable_external_collaboration"
    },
    "external_collaboration_allowlist_users": {
      "is_used": true,
      "value": [
        {
          "id": 1234,
          "name": "John Doe",
          "email": "johndoe@box.com"
        }
      ]
    },
    "is_watermarking_enterprise_feature_enabled": {
      "is_used": true,
      "value": true
    },
    "is_root_content_creation_restricted": {
      "is_used": true,
      "value": true
    },
    "is_tag_creation_restricted": {
      "is_used": true,
      "value": true
    },
    "tag_creation_restriction": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_email_uploads_enabled": {
      "is_used": true,
      "value": true
    },
    "is_custom_settings_enabled": {
      "is_used": true,
      "value": true
    },
    "is_forms_login_required": {
      "is_used": true,
      "value": true
    },
    "is_forms_branding_default_enabled": {
      "is_used": true,
      "value": true
    },
    "is_cc_free_trial_active": {
      "is_used": true,
      "value": true
    },
    "is_file_request_editors_allowed": {
      "is_used": true,
      "value": true
    },
    "is_file_request_branding_default_enabled": {
      "is_used": true,
      "value": true
    },
    "is_file_request_login_required": {
      "is_used": true,
      "value": true
    },
    "is_shared_links_expiration_enabled": {
      "is_used": true,
      "value": true
    },
    "shared_links_expiration_days": {
      "is_used": true,
      "value": 1234
    },
    "is_public_shared_links_expiration_enabled": {
      "is_used": true,
      "value": true
    },
    "public_shared_links_expiration_days": {
      "is_used": true,
      "value": 1234
    },
    "shared_expiration_target": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_shared_links_expiration_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "shared_links_expiration_notification_days": {
      "is_used": true,
      "value": 1234
    },
    "is_shared_links_expiration_notification_prevented": {
      "is_used": true,
      "value": true
    },
    "is_auto_delete_enabled": {
      "is_used": true,
      "value": true
    },
    "auto_delete_days": {
      "is_used": true,
      "value": 1234
    },
    "is_auto_delete_expiration_modification_prevented": {
      "is_used": true,
      "value": true
    },
    "auto_delete_target": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_collaboration_expiration_enabled": {
      "is_used": true,
      "value": true
    },
    "collaboration_expiration_days": {
      "is_used": true,
      "value": 1234
    },
    "is_collaboration_expiration_modification_prevented": {
      "is_used": true,
      "value": true
    },
    "is_collaboration_expiration_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "collaboration_expiration_target": {
      "is_used": true,
      "value": "value of configuration"
    },
    "trash_auto_clear_time": {
      "is_used": true,
      "value": 1234
    },
    "permanent_deletion_access": {
      "is_used": true,
      "value": "value of configuration"
    },
    "permanent_deletion_allowlist_users": {
      "is_used": true,
      "value": [
        {
          "id": 1234,
          "name": "John Doe",
          "email": "johndoe@box.com"
        }
      ]
    }
  }
  ```
</Accordion>

## Enterprise configuration security

The enterprise configuration for the security category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `is_managed_user_signup_enabled` | `Enterprise configuration item with boolean value` | No | Determines if users are allowed to sign up on their own. |
  | `is_managed_user_signup_notification_enabled` | `Enterprise configuration item with boolean value` | No | Determines if users must sign up with your corporate email. |
  | `is_managed_user_signup_corporate_email_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, admin are emailed when new users are added. |
  | `is_new_user_notification_daily_digest_enabled` | `Enterprise configuration item with boolean value` | No | Depends on `is_managed_user_signup_corporate_email_enabled`. A true value represents `In daily summary emails`. A false value represents `Immediately`. |
  | `is_managed_user_email_change_disabled` | `Enterprise configuration item with boolean value` | No | When enabled, prevents users from changing their primary email address. |
  | `is_multi_factor_auth_required` | `Enterprise configuration item with boolean value` | No | Determines if multi-factor authentication is required for all managed users. |
  | `is_weak_password_prevention_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, prevents common words / email address to be used in a password. |
  | `is_password_leak_detection_enabled` | `Enterprise configuration item with boolean value` | No | Enables exposed password detection. |
  | `last_password_reset_at` | `Enterprise configuration item` | No | |
  | `is_password_request_notification_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, admins are notified when users request a forget password email. |
  | `is_password_change_notification_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, admins are notified when users change passwords in Settings. |
  | `is_strong_password_for_ext_collab_enabled` | `Enterprise configuration item with boolean value` | No | Requires strong passwords for External Collaborators. |
  | `is_managed_user_migration_disabled` | `Enterprise configuration item with boolean value` | No | Disables users from being migrated in or out of the enterprise. |
  | `join_link` | `Enterprise configuration item with string value` | No | Join url for self sign up. Depends on `is_managed_user_signup_enabled`. Applies if `join_url` is not used. |
  | `join_url` | `Enterprise configuration item with string value` | No | Join url for self sign up. Depends on `is_managed_user_signup_enabled`. Applies if `join_link` is not used. |
  | `failed_login_attempts_to_trigger_admin_notification` | `Enterprise configuration item with integer value` | No | Number of failed login attempts before the primary admin is notified. |
  | `password_min_length` | `Enterprise configuration item with integer value` | No | Minimum number of characters required for passwords. |
  | `password_min_uppercase_characters` | `Enterprise configuration item with integer value` | No | Minimum number of upper case characters required in passwords. |
  | `password_min_numeric_characters` | `Enterprise configuration item with integer value` | No | Minimum number of numbers required in passwords. |
  | `password_min_special_characters` | `Enterprise configuration item with integer value` | No | Minimum number of symbols required in passwords. |
  | `password_reset_frequency` | `Enterprise configuration item with string value` | No | Determines if users must reset their passwords every specified time period. |
  | `previous_password_reuse_limit` | `Enterprise configuration item with string value` | No | Number of previous passwords users are prevented from using. |
  | `session_duration` | `Enterprise configuration item with string value` | No | Value indicating time from the last activity a user can remain logged in without activity before being logged out. |
  | `external_collab_multi_factor_auth_settings` | `Enterprise configuration item` | No | External Collaborators multi-factor authentication settings. |
  | `keysafe` | `Enterprise configuration item` | No | |
  | `is_custom_session_duration_enabled` | `Enterprise configuration item with boolean value` | No | Enables custom session duration for select users. |
  | `custom_session_duration_value` | `Enterprise configuration item with string value` | No | Value indicating duration users from specified groups can remain logged in without activity before being logged out. |
  | `custom_session_duration_groups` | `Enterprise configuration item` | No | Groups for custom session duration. |
  | `multi_factor_auth_type` | `Enterprise configuration item with string value` | No | Managed Users multi-factor authentication requirement method type. |
  | `enforced_mfa_frequency` | `Enterprise configuration item` | No | Managed Users multi-factor authentication frequency. The default authentication frequency is set to 30 days, with authentication time calculated from the most recent successful MFA login. |

  ```json Example theme={null}
  {
    "is_managed_user_signup_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_signup_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_signup_corporate_email_enabled": {
      "is_used": true,
      "value": true
    },
    "is_new_user_notification_daily_digest_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_email_change_disabled": {
      "is_used": true,
      "value": true
    },
    "is_multi_factor_auth_required": {
      "is_used": true,
      "value": true
    },
    "is_weak_password_prevention_enabled": {
      "is_used": true,
      "value": true
    },
    "is_password_leak_detection_enabled": {
      "is_used": true,
      "value": true
    },
    "last_password_reset_at": {
      "is_used": true,
      "value": "2012-12-12T10:53:43-08:00"
    },
    "is_password_request_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "is_password_change_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "is_strong_password_for_ext_collab_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_migration_disabled": {
      "is_used": true,
      "value": true
    },
    "join_link": {
      "is_used": true,
      "value": "value of configuration"
    },
    "join_url": {
      "is_used": true,
      "value": "value of configuration"
    },
    "failed_login_attempts_to_trigger_admin_notification": {
      "is_used": true,
      "value": 1234
    },
    "password_min_length": {
      "is_used": true,
      "value": 1234
    },
    "password_min_uppercase_characters": {
      "is_used": true,
      "value": 1234
    },
    "password_min_numeric_characters": {
      "is_used": true,
      "value": 1234
    },
    "password_min_special_characters": {
      "is_used": true,
      "value": 1234
    },
    "password_reset_frequency": {
      "is_used": true,
      "value": "value of configuration"
    },
    "previous_password_reuse_limit": {
      "is_used": true,
      "value": "value of configuration"
    },
    "session_duration": {
      "is_used": true,
      "value": "value of configuration"
    },
    "external_collab_multi_factor_auth_settings": {
      "is_used": true,
      "value": {
        "denylist_domains": [
          "example.com"
        ],
        "denylist_emails": [
          "spam@example.com"
        ],
        "allowlist_domains": [
          "example.com"
        ],
        "allowlist_emails": [
          "mail@example.com"
        ],
        "state": "enabled",
        "scheduled_status": "inprogress",
        "scheduled_at": "2012-12-12T10:53:43-08:00",
        "factor_type_settings": "totp"
      }
    },
    "keysafe": {
      "is_used": true,
      "value": {
        "keysafe_enabled": true,
        "cloud_provider": "",
        "key_id": "1234",
        "account_id": "1234",
        "location_id": "1234",
        "project_id": "1234",
        "keyring_id": "1234"
      }
    },
    "is_custom_session_duration_enabled": {
      "is_used": true,
      "value": true
    },
    "custom_session_duration_value": {
      "is_used": true,
      "value": "value of configuration"
    },
    "custom_session_duration_groups": {
      "is_used": true,
      "value": [
        {
          "id": "1234",
          "name": "Group Name"
        }
      ]
    },
    "multi_factor_auth_type": {
      "is_used": true,
      "value": "value of configuration"
    },
    "enforced_mfa_frequency": {
      "is_used": true,
      "value": {
        "days": 30,
        "hours": 24
      }
    }
  }
  ```
</Accordion>

## Enterprise configuration shield

The enterprise configuration for the shield category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `shield_rules` | array of `Shield rule item` | No | The shield rules configuration for the enterprise. |

  ```json Example theme={null}
  {
    "shield_rules": [
      {
        "id": "1234567890",
        "type": "shield_rule",
        "rule_category": "Malicious Content",
        "name": "Block malicious files",
        "description": "Blocks files identified as malicious content",
        "priority": "high",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>

## Enterprise configuration user settings

The enterprise configuration for the user settings category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `enterprise_feature_settings` | array of `Enterprise feature settings item` | No | |
  | `user_invites_expiration_time_frame` | `Enterprise configuration item with string value` | No | Determines the time frame for any unaccepted invitation to your Box enterprise account to expire. |
  | `is_username_change_restricted` | `Enterprise configuration item with boolean value` | No | Determines if users are restricted from changing their username in Account Settings. |
  | `is_box_sync_restricted_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if Box Sync is restricted for new users. |
  | `is_view_all_users_enabled_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users can see all managed users in their contacts when inviting collaborators. |
  | `is_device_limit_exemption_enabled_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users are exempt from the maximum number of devices specified in the Device Protection settings. |
  | `is_external_collaboration_restricted_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users will not be allowed to create folders that can have external collaborators. |
  | `is_unlimited_storage_enabled_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users are given unlimited storage. |
  | `new_user_default_storage_limit` | `Enterprise configuration item with integer value` | No | Determines the default storage limit for new users. Does not apply if `is_unlimited_storage_enabled_for_new_users` is true. |
  | `new_user_default_timezone` | `Enterprise configuration item with string value` | No | Determines the default timezone for new users. |
  | `new_user_default_language` | `Enterprise configuration item with string value` | No | Determines the default language for new users. |
  | `is_enterprise_sso_required` | `Enterprise configuration item with boolean value` | No | Value indicating if SSO is required for all users. |
  | `is_enterprise_sso_in_testing` | `Enterprise configuration item with boolean value` | No | Value indicating if SSO is in testing mode for all users. |
  | `is_sso_auto_add_groups_enabled` | `Enterprise configuration item with boolean value` | No | Determines if any new groups received for a user upon login through SSO but not present in the enterprise will be auto added to the enterprise. |
  | `is_sso_auto_add_user_to_groups_enabled` | `Enterprise configuration item with boolean value` | No | Determines if a user will be added to enterprise groups received upon user login through SSO. |
  | `is_sso_auto_remove_user_from_groups_enabled` | `Enterprise configuration item with boolean value` | No | Determines if a user will be removed from enterprise groups upon user login through SSO. |
  | `user_tracking_codes` | `Enterprise configuration item` | No | Properties that are assigned as additional values to users, like employee ID or region. |
  | `number_of_user_tracking_codes_remaining` | `Enterprise configuration item with integer value` | No | The remaining number of `user_tracking_codes` that can be created. |
  | `is_instant_login_restricted` | `Enterprise configuration item with boolean value` | No | Determines if users are restricted from granting (limited) access for Box Support for troubleshooting. |

  ```json Example theme={null}
  {
    "enterprise_feature_settings": [
      {
        "is_used": true,
        "value": {
          "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
          "feature": {
            "id": "canvas"
          },
          "state": "enabled",
          "can_configure": true,
          "is_configured": true,
          "allowlist": [
            {
              "type": "user",
              "id": "12345"
            }
          ],
          "denylist": [
            {
              "type": "user",
              "id": "12345"
            }
          ]
        }
      }
    ],
    "user_invites_expiration_time_frame": {
      "is_used": true,
      "value": "7 days"
    },
    "is_username_change_restricted": {
      "is_used": true,
      "value": true
    },
    "is_box_sync_restricted_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_view_all_users_enabled_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_device_limit_exemption_enabled_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_external_collaboration_restricted_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_unlimited_storage_enabled_for_new_users": {
      "is_used": true,
      "value": true
    },
    "new_user_default_storage_limit": {
      "is_used": true,
      "value": 1234
    },
    "new_user_default_timezone": {
      "is_used": true,
      "value": "GMT-05:00 America\\/Chicago CDT"
    },
    "new_user_default_language": {
      "is_used": true,
      "value": "English (US)"
    },
    "is_enterprise_sso_required": {
      "is_used": true,
      "value": true
    },
    "is_enterprise_sso_in_testing": {
      "is_used": true,
      "value": true
    },
    "is_sso_auto_add_groups_enabled": {
      "is_used": true,
      "value": true
    },
    "is_sso_auto_add_user_to_groups_enabled": {
      "is_used": true,
      "value": true
    },
    "is_sso_auto_remove_user_from_groups_enabled": {
      "is_used": true,
      "value": true
    },
    "user_tracking_codes": {
      "is_used": true,
      "value": [
        {
          "id": 1234,
          "name": "Employee ID"
        }
      ]
    },
    "number_of_user_tracking_codes_remaining": {
      "is_used": true,
      "value": 1234
    },
    "is_instant_login_restricted": {
      "is_used": true,
      "value": true
    }
  }
  ```
</Accordion>


# External Users resources
Source: https://developer.box.com/reference/v2025.0/external-users-resources



External users are collaborators from outside of your enterprise.

## External Users Submit Delete Job Response

Multi-status response containing the result for each external user deletion request.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of `External User Deletion Result` | Yes | Array of results of each external user deletion request. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "user_id": "12345",
        "status": 202,
        "detail": "string"
      }
    ]
  }
  ```
</Accordion>


# List archives
Source: https://developer.box.com/reference/v2025.0/get-archives

box-openapi-v2025.0.json GET /archives
Retrieves archives for an enterprise.

To learn more about the archive APIs, see the [Archive API Guide](/guides/archives).

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Doc Gen jobs by batch ID
Source: https://developer.box.com/reference/v2025.0/get-docgen-batch-jobs-id

box-openapi-v2025.0.json GET /docgen_batch_jobs/{batch_id}
Lists Box Doc Gen jobs in a batch.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all Box Doc Gen jobs
Source: https://developer.box.com/reference/v2025.0/get-docgen-jobs

box-openapi-v2025.0.json GET /docgen_jobs
Lists all Box Doc Gen jobs for a user.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Doc Gen job by ID
Source: https://developer.box.com/reference/v2025.0/get-docgen-jobs-id

box-openapi-v2025.0.json GET /docgen_jobs/{job_id}
Get details of the Box Doc Gen job.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get list of all Box Doc Gen jobs for template
Source: https://developer.box.com/reference/v2025.0/get-docgen-template-jobs-id

box-openapi-v2025.0.json GET /docgen_template_jobs/{template_id}
Lists the users jobs which use this template.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List Box Doc Gen templates
Source: https://developer.box.com/reference/v2025.0/get-docgen-templates

box-openapi-v2025.0.json GET /docgen_templates
Lists Box Doc Gen templates on which the user is a collaborator.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Doc Gen template by ID
Source: https://developer.box.com/reference/v2025.0/get-docgen-templates-id

box-openapi-v2025.0.json GET /docgen_templates/{template_id}
Lists details of a specific Box Doc Gen template.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all Box Doc Gen template tags in template
Source: https://developer.box.com/reference/v2025.0/get-docgen-templates-id-tags

box-openapi-v2025.0.json GET /docgen_templates/{template_id}/tags
Lists all tags in a Box Doc Gen template.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get enterprise configuration
Source: https://developer.box.com/reference/v2025.0/get-enterprise-configurations-id

box-openapi-v2025.0.json GET /enterprise_configurations/{enterprise_id}
Retrieves the configuration for an enterprise.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all Box Hubs for requesting enterprise
Source: https://developer.box.com/reference/v2025.0/get-enterprise-hubs

box-openapi-v2025.0.json GET /enterprise_hubs
Retrieves all Box Hubs for a given enterprise.

Admins or Hub Co-admins of an enterprise with GCM scope can make this call.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Hub collaborations
Source: https://developer.box.com/reference/v2025.0/get-hub-collaborations

box-openapi-v2025.0.json GET /hub_collaborations
Retrieves all collaborations for a Box Hub.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Hub collaboration by collaboration ID
Source: https://developer.box.com/reference/v2025.0/get-hub-collaborations-id

box-openapi-v2025.0.json GET /hub_collaborations/{hub_collaboration_id}
Retrieves details for a Box Hub collaboration by collaboration ID.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List Hub Document blocks for page
Source: https://developer.box.com/reference/v2025.0/get-hub-document-blocks

box-openapi-v2025.0.json GET /hub_document_blocks
Retrieves a sorted list of all Hub Document Blocks on a specified page in the hub document, excluding items. Blocks are hierarchically organized by their `parent_id`. Blocks are sorted in order based on user specification in the user interface. The response will only include content blocks that belong to the specified page. This will not include sub pages or sub page content blocks.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List Hub Document Pages
Source: https://developer.box.com/reference/v2025.0/get-hub-document-pages

box-openapi-v2025.0.json GET /hub_document_pages
Retrieves a list of Hub Document Pages for the specified hub. Includes both root-level pages and sub pages.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Hub items
Source: https://developer.box.com/reference/v2025.0/get-hub-items

box-openapi-v2025.0.json GET /hub_items
Retrieves all items associated with a Box Hub.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# List all Box Hubs
Source: https://developer.box.com/reference/v2025.0/get-hubs

box-openapi-v2025.0.json GET /hubs
Retrieves all Box Hubs for requesting user.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get Box Hub information by ID
Source: https://developer.box.com/reference/v2025.0/get-hubs-id

box-openapi-v2025.0.json GET /hubs/{hub_id}
Retrieves details for a Box Hub by its ID.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get all shield lists in enterprise
Source: https://developer.box.com/reference/v2025.0/get-shield-lists

box-openapi-v2025.0.json GET /shield_lists
Retrieves all shield lists in the enterprise.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Get single shield list by shield list id
Source: https://developer.box.com/reference/v2025.0/get-shield-lists-id

box-openapi-v2025.0.json GET /shield_lists/{shield_list_id}
Retrieves a single shield list by its ID.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Box Hub Collaborations resources
Source: https://developer.box.com/reference/v2025.0/hub-collaborations-resources



A set of endpoints used to manage collaborations within a Box Hub.

## Box Hub Collaboration

A Box Hub collaboration object grants a user or group access to a Box Hub with permissions defined by a specific role.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this collaboration. |
  | `type` | `enum<string>` | Yes | The value will always be `hub_collaboration`. Available options: `hub_collaboration`. |
  | `hub` | [Box Hub (Base)](/reference/v2025.0/hubs-resources#box-hub-base) | No | |
  | `accessible_by` | `Box Hub Accessible By` | No | |
  | `role` | `string` | No | The level of access granted to a Box Hub. Possible values are `editor`, `viewer`, and `co-owner`. |
  | `status` | `enum<string>` | No | The status of the collaboration invitation. If the status is `pending`, `login` and `name` return an empty string. Available options: `accepted`, `pending`, `rejected`. |
  | `acceptance_requirements_status` | `object` | No | |

  ```json Example theme={null}
  {
    "id": "12345678",
    "type": "hub_collaboration",
    "hub": {
      "id": "12345",
      "type": "hubs"
    },
    "accessible_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "role": "editor",
    "status": "accepted",
    "acceptance_requirements_status": {
      "terms_of_service_requirement": {
        "is_accepted": true,
        "terms_of_service": {
          "id": "11446498",
          "type": "terms_of_service"
        }
      },
      "strong_password_requirement": {
        "enterprise_has_strong_password_required_for_external_users": true,
        "user_has_strong_password": true
      },
      "two_factor_authentication_requirement": {
        "enterprise_has_two_factor_auth_enabled": true,
        "user_has_two_factor_authentication_enabled": true
      }
    }
  }
  ```
</Accordion>

## Box Hub Collaborations

A list of Box Hub collaborations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub Collaboration](#box-hub-collaboration) | No | A list of Box Hub collaborations. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345678",
        "type": "hub_collaboration",
        "hub": {
          "id": "12345",
          "type": "hubs"
        },
        "accessible_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "role": "editor",
        "status": "accepted",
        "acceptance_requirements_status": {
          "terms_of_service_requirement": {
            "is_accepted": true,
            "terms_of_service": {
              "id": "11446498",
              "type": "terms_of_service"
            }
          },
          "strong_password_requirement": {
            "enterprise_has_strong_password_required_for_external_users": true,
            "user_has_strong_password": true
          },
          "two_factor_authentication_requirement": {
            "enterprise_has_two_factor_auth_enabled": true,
            "user_has_two_factor_authentication_enabled": true
          }
        }
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Box Hub Document resources
Source: https://developer.box.com/reference/v2025.0/hub-document-resources



A set of endpoints used to retrieve Box Hub Document elements (pages and content blocks).

## Box Hub Callout Box Text Block

A callout box block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `callout_box`. Available options: `callout_box`. |
  | `fragment` | `string` | Yes | Text content of the block. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "callout_box",
    "fragment": "This is the callout box"
  }
  ```
</Accordion>

## Box Hub Divider Block

A divider block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `divider`. Available options: `divider`. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "divider"
  }
  ```
</Accordion>

## Box Hub Document Blocks

A list of Hub Document blocks.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of `Box Hub Document Block Entry` | Yes | Ordered list of blocks. |
  | `type` | `enum<string>` | Yes | The value will always be `document_blocks`. Available options: `document_blocks`. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
        "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
        "type": "paragraph",
        "fragment": "This is the paragraph"
      }
    ],
    "type": "document_blocks",
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>

## Box Hub Document Page

A Page in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this page. |
  | `type` | `string` | Yes | The type of this resource. The value is always `page`. |
  | `parent_id` | `string` | No | The unique identifier of the parent page. Null for root-level pages. Can be `null`. |
  | `title_fragment` | `string` | Yes | The title text of the page. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "page",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "title_fragment": "This is the home page title"
  }
  ```
</Accordion>

## Box Hub Document Pages

A list of Hub Document Pages.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub Document Page](#box-hub-document-page) | Yes | Ordered list of pages. |
  | `type` | `enum<string>` | Yes | The value will always be `document_pages`. Available options: `document_pages`. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
        "type": "page",
        "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
        "title_fragment": "This is the home page title"
      }
    ],
    "type": "document_pages",
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>

## Box Hub Item List Block

An item list block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `item_list`. Available options: `item_list`. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "item_list"
  }
  ```
</Accordion>

## Box Hub Paragraph Text Block

A paragraph block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `paragraph`. Available options: `paragraph`. |
  | `fragment` | `string` | Yes | Text content of the block. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "paragraph",
    "fragment": "This is the paragraph"
  }
  ```
</Accordion>

## Box Hub Section Title Text Block

A section title block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `section_title`. Available options: `section_title`. |
  | `fragment` | `string` | Yes | Text content of the block. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "section_title",
    "fragment": "This is the section title"
  }
  ```
</Accordion>


# Box Hub Items resources
Source: https://developer.box.com/reference/v2025.0/hub-items-resources



A set of endpoints used to manage items within a Box Hub.

## Box Hub Item

A Box Hub Item is a Box Item that is referenced in a Box Hub.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this item. |
  | `type` | `enum<string>` | Yes | The type of the item. Available options: `file`, `folder`, `web_link`. |
  | `name` | `string` | Yes | The name of the item. |

  ```json Example theme={null}
  {
    "id": "12345678",
    "type": "file",
    "name": "My File"
  }
  ```
</Accordion>

## Box Hub Items

A list of Box Hub items.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub Item](#box-hub-item) | No | A list of Box Hub items. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345678",
        "type": "file",
        "name": "My File"
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>

## Box Hub Items Manage Response

Response schema for the status of Box Hub items management operations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `operations` | array of `Box Hub Item Operation Result` | Yes | List of operations performed on Box Hub items. |

  ```json Example theme={null}
  {
    "operations": [
      {
        "action": "add",
        "item": {
          "type": "file",
          "id": "42037322"
        },
        "parent_id": "721d97d7-ac8a-4e5e-adb6-ef11af4e6d9e",
        "status": 200,
        "error": "Item not found"
      }
    ]
  }
  ```
</Accordion>


# Box Hubs resources
Source: https://developer.box.com/reference/v2025.0/hubs-resources



A set of endpoints used to manage Box Hubs.

## Box Hub

A standard representation of a Box Hub, as returned from any Box Hubs API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Hub. The ID for any Box Hub can be determined by visiting a Box Hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. |
  | `type` | `enum<string>` | Yes | The value will always be `hubs`. Available options: `hubs`. |
  | `title` | `string` | No | The title given to the Box Hub. |
  | `description` | `string` | No | The description of the Box Hub. First 200 characters are returned. |
  | `created_at` | `string` | No | The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder. |
  | `updated_at` | `string` | No | The date and time when the Box Hub was last updated. |
  | `created_by` | `User (Mini)` | No | The user who created this Box Hub. |
  | `updated_by` | `User (Mini)` | No | The user who last modified this Box Hub. |
  | `view_count` | `integer` | No | The number of views for the Box Hub. |
  | `is_ai_enabled` | `boolean` | No | Indicates if AI features are enabled for the Box Hub. |
  | `is_collaboration_restricted_to_enterprise` | `boolean` | No | Indicates if collaboration is restricted to the enterprise. |
  | `can_non_owners_invite` | `boolean` | No | Indicates if non-owners can invite others to the Box Hub. |
  | `can_shared_link_be_created` | `boolean` | No | Indicates if a shared link can be created for the Box Hub. |
  | `can_public_shared_link_be_created` | `boolean` | No | Indicates if a public shared link can be created for the Box Hub. |
  | `copy_hub_access` | `enum<string>` | No | Specifies who is allowed to copy the Box Hub. - `all` - Any user with access to the Hub can copy it. - `company` - Only users within the same enterprise as the Hub can copy it. - `none` - No one can copy the Hub. Available options: `all`, `company`, `none`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "hubs",
    "title": "Contracts",
    "description": "All the contracts for the company.",
    "created_at": "2012-12-12T10:53:43Z",
    "updated_at": "2012-12-12T10:53:43Z",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "updated_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "view_count": 506,
    "is_ai_enabled": true,
    "is_collaboration_restricted_to_enterprise": true,
    "can_non_owners_invite": true,
    "can_shared_link_be_created": true,
    "can_public_shared_link_be_created": true,
    "copy_hub_access": "company"
  }
  ```
</Accordion>

## Box Hub (Base)

The bare basic representation of a Box Hub.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Hub. The ID for any Box Hub can be determined by visiting a Box Hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. |
  | `type` | `enum<string>` | Yes | The value will always be `hubs`. Available options: `hubs`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "hubs"
  }
  ```
</Accordion>

## Box Hubs

A paginated list of hubs.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub](#box-hub) | No | A list of hubs. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "hubs",
        "title": "Contracts",
        "description": "All the contracts for the company.",
        "created_at": "2012-12-12T10:53:43Z",
        "updated_at": "2012-12-12T10:53:43Z",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "updated_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "view_count": 506,
        "is_ai_enabled": true,
        "is_collaboration_restricted_to_enterprise": true,
        "can_non_owners_invite": true,
        "can_shared_link_be_created": true,
        "can_public_shared_link_be_created": true,
        "copy_hub_access": "company"
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Create archive
Source: https://developer.box.com/reference/v2025.0/post-archives

box-openapi-v2025.0.json POST /archives
Creates an archive.

To learn more about the archive APIs, see the [Archive API Guide](/guides/archives).

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Generate document using Box Doc Gen template
Source: https://developer.box.com/reference/v2025.0/post-docgen-batches

box-openapi-v2025.0.json POST /docgen_batches
Generates a document using a Box Doc Gen template.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create Box Doc Gen template
Source: https://developer.box.com/reference/v2025.0/post-docgen-templates

box-openapi-v2025.0.json POST /docgen_templates
Marks a file as a Box Doc Gen template.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Submit job to delete external users
Source: https://developer.box.com/reference/v2025.0/post-external-users-submit-delete-job

box-openapi-v2025.0.json POST /external_users/submit_delete_job
Delete external users from current user enterprise. This will remove each external user from all invited collaborations within the current enterprise.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create Box Hub collaboration
Source: https://developer.box.com/reference/v2025.0/post-hub-collaborations

box-openapi-v2025.0.json POST /hub_collaborations
Adds a collaboration for a single user or a single group to a Box Hub.

Collaborations can be created using email address, user IDs, or group IDs.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create Box Hub
Source: https://developer.box.com/reference/v2025.0/post-hubs

box-openapi-v2025.0.json POST /hubs
Creates a new Box Hub.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Copy Box Hub
Source: https://developer.box.com/reference/v2025.0/post-hubs-id-copy

box-openapi-v2025.0.json POST /hubs/{hub_id}/copy
Creates a copy of a Box Hub.

The original Box Hub will not be modified.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Manage Box Hub items
Source: https://developer.box.com/reference/v2025.0/post-hubs-id-manage-items

box-openapi-v2025.0.json POST /hubs/{hub_id}/manage_items
Adds and/or removes Box Hub items from a Box Hub.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create shield list
Source: https://developer.box.com/reference/v2025.0/post-shield-lists

box-openapi-v2025.0.json POST /shield_lists
Creates a shield list.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update archive
Source: https://developer.box.com/reference/v2025.0/put-archives-id

box-openapi-v2025.0.json PUT /archives/{archive_id}
Updates an archive.

To learn more about the archive APIs, see the [Archive API Guide](/guides/archives).

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update Box Hub collaboration
Source: https://developer.box.com/reference/v2025.0/put-hub-collaborations-id

box-openapi-v2025.0.json PUT /hub_collaborations/{hub_collaboration_id}
Updates a Box Hub collaboration. Can be used to change the Box Hub role.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update Box Hub information by ID
Source: https://developer.box.com/reference/v2025.0/put-hubs-id

box-openapi-v2025.0.json PUT /hubs/{hub_id}
Updates a Box Hub. Can be used to change title, description, or Box Hub settings.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Update shield list
Source: https://developer.box.com/reference/v2025.0/put-shield-lists-id

box-openapi-v2025.0.json PUT /shield_lists/{shield_list_id}
Updates a shield list.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Shield lists resources
Source: https://developer.box.com/reference/v2025.0/shield-lists-resources



Shield List allow an administrator to create a list which will be shared between different Shield Smart Access and Threat Detection rules.

## List of Shield Lists

List of Shield List objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Shield List (Mini)](#shield-list-mini) | No | A list of shield list objects. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345678-1234-1234-1234-123456789012",
        "type": "shield_list",
        "name": "My Shield List",
        "content": {
          "type": "country_code"
        }
      }
    ]
  }
  ```
</Accordion>

## Shield List

A standard representation of a Shield List.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | Unique identifier for the shield list. |
  | `type` | `string` | Yes | Type of the object. |
  | `name` | `string` | Yes | Name of the shield list. |
  | `enterprise` | `Enterprise reference` | Yes | Enterprise for which this list belongs to. |
  | `description` | `string` | No | Description of Shield List. |
  | `created_at` | `string` | Yes | ISO date time string when this shield list object was created. |
  | `updated_at` | `string` | Yes | ISO date time string when this shield list object was updated. |
  | `content` | `Shield List Content` | Yes | Specifies the type of elements in this Shield List and includes the elements themselves. |

  ```json Example theme={null}
  {
    "id": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24",
    "type": "shield_list",
    "name": "Shield List Name",
    "enterprise": {
      "id": "1910967",
      "type": "enterprise"
    },
    "description": "A list of things that are shielded",
    "created_at": "2025-01-13T15:31:01.896Z",
    "updated_at": "2025-01-13T15:31:01.896Z",
    "content": {
      "type": "country",
      "country_codes": [
        "US",
        "PL"
      ]
    }
  }
  ```
</Accordion>

## Shield List (Mini)

A mini representation of a Shield List.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | Unique global identifier for this list. |
  | `type` | `enum<string>` | Yes | The type of object. Available options: `shield_list`. |
  | `name` | `string` | Yes | Name of Shield List. |
  | `content` | `object` | Yes | |

  ```json Example theme={null}
  {
    "id": "12345678-1234-1234-1234-123456789012",
    "type": "shield_list",
    "name": "My Shield List",
    "content": {
      "type": "country_code"
    }
  }
  ```
</Accordion>

## Shield List Content (Country)

Representation of content of a Shield List that contains countries data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `country`. |
  | `country_codes` | array of `string` | Yes | List of country codes values. |

  ```json Example theme={null}
  {
    "type": "country",
    "country_codes": [
      "US",
      "PL"
    ]
  }
  ```
</Accordion>

## Shield List Content (Domain)

Representation of content of a Shield List that contains domains data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `domain`. |
  | `domains` | array of `string` | Yes | List of domain. |

  ```json Example theme={null}
  {
    "type": "domain",
    "domains": [
      "box.com",
      "example.com"
    ]
  }
  ```
</Accordion>

## Shield List Content (Email)

Representation of content of a Shield List that contains email addresses data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `email`. |
  | `email_addresses` | array of `string` | Yes | List of emails. |

  ```json Example theme={null}
  {
    "type": "email",
    "email_addresses": [
      "example1@box.com",
      "example2@gmail.com"
    ]
  }
  ```
</Accordion>

## Shield List Content (Integration)

Representation of content of a Shield List that contains integrations data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `integration`. |
  | `integrations` | array of `object` | Yes | List of integration. |

  ```json Example theme={null}
  {
    "type": "integration",
    "integrations": [
      {
        "id": "505e40b5-5d04-446a-9268-72a0ccc13669"
      }
    ]
  }
  ```
</Accordion>

## Shield List Content (IP)

Representation of content of a Shield List that contains ip addresses data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `ip`. |
  | `ip_addresses` | array of `string` | Yes | List of ip addresses and CIDRs. |

  ```json Example theme={null}
  {
    "type": "ip",
    "ip_addresses": [
      "127.0.0.1",
      "80.12.12.12/24"
    ]
  }
  ```
</Accordion>


# List Automate workflows defined as callable actions
Source: https://developer.box.com/reference/v2026.0/get-automate-workflows

box-openapi-v2026.0.json GET /automate_workflows
Returns workflow actions from Automate for a folder, using the `WORKFLOW` action category.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Convert to Box note resources
Source: https://developer.box.com/reference/v2026.0/notes-resources



Create Box Notes from supported source content (for example Markdown).

## Notes convert response

Identifies the created Box Note file.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The Box resource type; always `file` for a Box file. Available options: `file`. |
  | `id` | `string` | Yes | Box file ID of the created `.boxnote` file. |

  ```json Example theme={null}
  {
    "type": "file",
    "id": "1234567890"
  }
  ```
</Accordion>


# Start Automate workflow
Source: https://developer.box.com/reference/v2026.0/post-automate-workflows-id-start

box-openapi-v2026.0.json POST /automate_workflows/{workflow_id}/start
Starts an Automate workflow manually by using a workflow action ID and file IDs.

<Warning>
  This endpoint is not available on the [Free Developer Plan](/platform/free-developer-plan). [Upgrade here](https://app.box.com/upgrade/up).
</Warning>

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Convert content to Box Note
Source: https://developer.box.com/reference/v2026.0/post-notes-convert

box-openapi-v2026.0.json POST /notes/convert
Creates a Box Note (`.boxnote` file) from supported source content. See the `content_format` field for supported formats.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Query for Box items
Source: https://developer.box.com/reference/v2026.0/post-query

box-openapi-v2026.0.json POST /query
Runs a query to discover Box items using a logical predicate that can filter across item fields and metadata templates. Results can be sorted, paginated, and shaped to include additional item or metadata fields.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Create insights for Box items
Source: https://developer.box.com/reference/v2026.0/post-query-insights

box-openapi-v2026.0.json POST /query_insights
Computes aggregated metrics over Box items matching a query predicate. Filters are applied first, followed by optional grouping, after which the requested metrics (such as `sum`, `avg`, `min`, `max`, and `count`) are computed for each resulting group or over the entire filtered dataset.

<Note>
  Learn more about [Box SDK versioning strategy](/guides/tooling/sdks/sdk-versioning/).
</Note>


# Query resources
Source: https://developer.box.com/reference/v2026.0/query-resources



Query for your items.

## Query insight entry

A single computed insight entry, containing its grouping keys (if applicable) and the computed metrics.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `key` | array of `string` | Yes | The grouping key values associated with the entry. Contains one value per `group_by` field for `group` entries, and is empty for `overall` and `other` entries. |
  | `type` | `enum<string>` | Yes | The type of insight entry, indicating how the associated metrics are aggregated. Available options: `group`, `overall`, `other`. |
  | `metrics` | `object` | Yes | A map of metric aliases to their computed results. For `other` entries, the count is reported under the `totalCountBeyondTopGroups` key. |

  ```json Example theme={null}
  {
    "key": [
      "ContractType1"
    ],
    "type": "group",
    "metrics": {
      "totalContractValue": {
        "type": "sum",
        "values": {
          "sum": 180000
        }
      },
      "countContractType": {
        "type": "count",
        "values": {
          "count": 245
        }
      }
    }
  }
  ```
</Accordion>

## Query insights

The computed results of an insights request, as a list of insight entries.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `insights` | array of [Query insight entry](#query-insight-entry) | Yes | The list of computed insight entries. Each entry corresponds to a group, the overall dataset, or the aggregate of groups outside the top results. |

  ```json Example theme={null}
  {
    "insights": [
      {
        "key": [
          "ContractType1"
        ],
        "type": "group",
        "metrics": {
          "totalContractValue": {
            "type": "sum",
            "values": {
              "sum": 180000
            }
          },
          "countContractType": {
            "type": "count",
            "values": {
              "count": 245
            }
          }
        }
      },
      {
        "key": [
          "ContractType4"
        ],
        "type": "group",
        "metrics": {
          "totalContractValue": {
            "type": "sum",
            "values": {
              "sum": 100000
            }
          },
          "countContractType": {
            "type": "count",
            "values": {
              "count": 185
            }
          }
        }
      },
      {
        "key": [
          "ContractType2"
        ],
        "type": "group",
        "metrics": {
          "totalContractValue": {
            "type": "sum",
            "values": {
              "sum": 200000
            }
          },
          "countContractType": {
            "type": "count",
            "values": {
              "count": 150
            }
          }
        }
      },
      {
        "key": [],
        "type": "other",
        "metrics": {
          "totalCountBeyondTopGroups": {
            "type": "count",
            "values": {
              "count": 165
            }
          }
        }
      }
    ]
  }
  ```
</Accordion>

## Query result entry

A single item matching the query. Always includes the item `type` and `id`. If a `fields` parameter was specified in the request, then additional item and/or metadata fields will be provided.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier of the matching item. |
  | `type` | `string` | Yes | The type of the matching item. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "file"
  }
  ```
</Accordion>

## Query results

A paginated list of items matching the query, using milestone-based marker pagination.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Query result entry](#query-result-entry) | Yes | The list of items matching the query predicate. |
  | `next_marker` | `string` | Yes | The marker for the start of the next page of results. When `null`, there are no further results available. Can be `null`. |
  | `limit` | `integer` | Yes | The limit that was used for this request. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "file",
        "box": {
          "item": {
            "name": "My Form"
          }
        },
        "enterprise_12345678": {
          "book": {
            "$parent": "file_12345",
            "$scope": "enterprise_12345678",
            "$template": "book",
            "$version": 4,
            "isbn": "1871263670",
            "purchasePrice": 234.57,
            "publicationYear": "1937"
          }
        }
      }
    ],
    "next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=",
    "limit": 1
  }
  ```
</Accordion>


# Web links resources
Source: https://developer.box.com/reference/web-links-resources



Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application.

## Web link

Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this web link. |
  | `type` | `enum<string>` | Yes | The value will always be `web_link`. Available options: `web_link`. |
  | `etag` | `string` | No | The entity tag of this web link. Used with `If-Match` headers. |
  | `url` | `string` | No | The URL this web link points to. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the web link. |
  | `parent` | [Folder (Mini)](/reference/folders-resources#folder-mini) | No | The parent object the web link belongs to. |
  | `description` | `string` | No | The description accompanying the web link. This is visible within the Box web application. |
  | `path_collection` | `object` | No | A list of parent folders for an item. |
  | `created_at` | `string` | No | When this file was created on Box’s servers. |
  | `modified_at` | `string` | No | When this file was last updated on the Box servers. |
  | `trashed_at` | `string` | No | When this file was moved to the trash. Can be `null`. |
  | `purged_at` | `string` | No | When this file will be permanently deleted. Can be `null`. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created this web link. |
  | `modified_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who last modified this web link. |
  | `owned_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who owns this web link. |
  | `shared_link` | `object` | No | Shared links provide direct, read-only access to files or folder on Box. Shared links with open access level allow anyone with the URL to access the item, while shared links with company or collaborators access levels can only be accessed by appropriately authenticated Box users. Can be `null`. |
  | `item_status` | `enum<string>` | No | Whether this item is deleted or not. Values include `active`, `trashed` if the file has been moved to the trash, and `deleted` if the file has been permanently deleted. Available options: `active`, `trashed`, `deleted`. |
  | `collections` | array of [Collection](/reference/collections-resources#collection) | No | The collections that this web link belongs to. For more information, see the [collections guide](/guides/collections). |
  | `allowed_shared_link_access_levels` | array of `enum<string>` | No | The shared link access levels the authenticated user is allowed to use when creating or updating a shared link for this web link. The list depends on item policy and user authorization, so it may be narrower than the levels available to the owner. An empty array means no access level is available to this user. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "web_link",
    "etag": "1",
    "url": "https://www.example.com/example/1234",
    "sequence_id": "3",
    "name": "My Bookmark",
    "parent": {
      "id": "12345",
      "etag": "1",
      "type": "folder",
      "sequence_id": "3",
      "name": "Contracts"
    },
    "description": "Example page",
    "path_collection": {
      "total_count": 1,
      "entries": [
        {
          "id": "12345",
          "etag": "1",
          "type": "folder",
          "sequence_id": "3",
          "name": "Contracts"
        }
      ]
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "modified_at": "2012-12-12T10:53:43-08:00",
    "trashed_at": "2012-12-12T10:53:43-08:00",
    "purged_at": "2012-12-12T10:53:43-08:00",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "modified_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "owned_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "shared_link": {
      "url": "https://www.box.com/s/vspke7y05sb214wjokpk",
      "download_url": "https://www.box.com/shared/static/rh935iit6ewrmw0unyul.jpeg",
      "vanity_url": "https://acme.app.box.com/v/my_url/",
      "vanity_name": "my_url",
      "access": "open",
      "effective_access": "company",
      "effective_permission": "can_download",
      "unshared_at": "2018-04-13T13:53:23-07:00",
      "is_password_enabled": true,
      "permissions": {
        "can_download": true,
        "can_preview": true,
        "can_edit": false
      },
      "download_count": 3,
      "preview_count": 3
    },
    "item_status": "active",
    "collections": [
      {
        "id": "11446498",
        "type": "collection",
        "name": "Favorites",
        "collection_type": "favorites"
      }
    ],
    "allowed_shared_link_access_levels": [
      "open"
    ]
  }
  ```
</Accordion>

## Web link (Base)

Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this web link. |
  | `type` | `enum<string>` | Yes | The value will always be `web_link`. Available options: `web_link`. |
  | `etag` | `string` | No | The entity tag of this web link. Used with `If-Match` headers. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "web_link",
    "etag": "1"
  }
  ```
</Accordion>

## Web link (Mini)

Web links are objects that point to URLs. These objects are also known as bookmarks within the Box web application. Web link objects are treated similarly to file objects, they will also support most actions that apply to regular files.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this web link. |
  | `type` | `enum<string>` | Yes | The value will always be `web_link`. Available options: `web_link`. |
  | `etag` | `string` | No | The entity tag of this web link. Used with `If-Match` headers. |
  | `url` | `string` | No | The URL this web link points to. |
  | `sequence_id` | `string` | No | A numeric identifier that represents the most recent user event that has been applied to this item. This can be used in combination with the `GET /events`-endpoint to filter out user events that would have occurred before this identifier was read. An example would be where a Box Drive-like application would fetch an item via the API, and then listen to incoming user events for changes to the item. The application would ignore any user events where the `sequence_id` in the event is smaller than or equal to the `sequence_id` in the originally fetched resource. Can be `null`. |
  | `name` | `string` | No | The name of the web link. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "web_link",
    "etag": "1",
    "url": "https://www.example.com/example/1234",
    "sequence_id": "3",
    "name": "My Bookmark"
  }
  ```
</Accordion>


# Webhooks resources
Source: https://developer.box.com/reference/webhooks-resources



Webhooks allow you to monitor Box content for events, and receive notifications to a URL of your choice when they occur. For example, a workflow may include waiting for a file to be downloaded to delete a shared link.

## Webhook

Represents a configured webhook.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this webhook. |
  | `type` | `enum<string>` | No | The value will always be `webhook`. Available options: `webhook`. |
  | `target` | `object` | No | The item that will trigger the webhook. |
  | `created_by` | [User (Mini)](/reference/users-resources#user-mini) | No | The user who created the webhook. |
  | `created_at` | `string` | No | A timestamp identifying the time that the webhook was created. |
  | `address` | `string` | No | The URL that is notified by this webhook. |
  | `triggers` | array of `enum<string>` | No | An array of event names that this webhook is to be triggered for. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "webhook",
    "target": {
      "id": "1231232",
      "type": "file"
    },
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "created_at": "2012-12-12T10:53:43-08:00",
    "address": "https://example.com/webhooks",
    "triggers": [
      "FILE.UPLOADED"
    ]
  }
  ```
</Accordion>

## Webhook (Mini)

Represents a configured webhook.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for this webhook. |
  | `type` | `enum<string>` | No | The value will always be `webhook`. Available options: `webhook`. |
  | `target` | `object` | No | The item that will trigger the webhook. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "webhook",
    "target": {
      "id": "1231232",
      "type": "file"
    }
  }
  ```
</Accordion>

## Webhooks

A list of webhooks.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Webhook (Mini)](#webhook-mini) | No | A list of webhooks. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "webhook",
        "target": {
          "id": "1231232",
          "type": "file"
        }
      }
    ]
  }
  ```
</Accordion>


# Workflows resources
Source: https://developer.box.com/reference/workflows-resources



Box Relay Workflows are objects that represent a named collection of flows.

## Workflow

Box Relay Workflows are objects that represent a named collection of flows. Your application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the workflow. |
  | `type` | `enum<string>` | No | The value will always be `workflow`. Available options: `workflow`. |
  | `name` | `string` | No | The name of the workflow. |
  | `description` | `string` | No | The description for a workflow. |
  | `is_enabled` | `boolean` | No | Specifies if this workflow is enabled. |
  | `flows` | array of `object` | No | A list of flows assigned to a workflow. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "workflow",
    "name": "New Hire Workflow",
    "description": "This workflow sets off a new hire approval flow",
    "is_enabled": true,
    "flows": [
      {
        "id": "12345",
        "type": "flow",
        "trigger": {
          "type": "trigger",
          "trigger_type": "WORKFLOW_MANUAL_START",
          "scope": [
            {
              "type": "trigger_scope",
              "ref": "/event/source/parameters/folder",
              "object": {
                "type": "folder",
                "id": "12345"
              }
            }
          ]
        },
        "outcomes": [
          {
            "id": "12345",
            "type": "outcome",
            "name": "Task Approval Outcome",
            "action_type": "assign_task",
            "if_rejected": [
              {
                "id": "12345",
                "type": "outcome",
                "name": "Approval Rejection Outcome",
                "action_type": "assign_task"
              }
            ]
          }
        ],
        "created_at": "2012-12-12T10:53:43-08:00",
        "created_by": {
          "id": "11446498",
          "type": "user"
        }
      }
    ]
  }
  ```
</Accordion>

## Workflow (Mini)

Box Relay Workflows are objects that represent a named collection of flows. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The unique identifier for the workflow. |
  | `type` | `enum<string>` | No | The value will always be `workflow`. Available options: `workflow`. |
  | `name` | `string` | No | The name of the workflow. |
  | `description` | `string` | No | The description for a workflow. |
  | `is_enabled` | `boolean` | No | Specifies if this workflow is enabled. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "workflow",
    "name": "New Hire Workflow",
    "description": "This workflow sets off a new hire approval flow",
    "is_enabled": true
  }
  ```
</Accordion>

## Workflows

A list of workflows. You application must be authorized to use the `Manage Box Relay` application scope within the developer console in order to use this resource.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Workflow](#workflow) | No | A list of workflows. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "11446498",
        "type": "workflow",
        "name": "New Hire Workflow",
        "description": "This workflow sets off a new hire approval flow",
        "is_enabled": true,
        "flows": [
          {
            "id": "12345",
            "type": "flow",
            "trigger": {
              "type": "trigger",
              "trigger_type": "WORKFLOW_MANUAL_START",
              "scope": [
                {
                  "type": "trigger_scope",
                  "ref": "/event/source/parameters/folder",
                  "object": {
                    "type": "folder",
                    "id": "12345"
                  }
                }
              ]
            },
            "outcomes": [
              {
                "id": "12345",
                "type": "outcome",
                "name": "Task Approval Outcome",
                "action_type": "assign_task",
                "if_rejected": [
                  {
                    "id": "12345",
                    "type": "outcome",
                    "name": "Approval Rejection Outcome",
                    "action_type": "assign_task"
                  }
                ]
              }
            ],
            "created_at": "2012-12-12T10:53:43-08:00",
            "created_by": {
              "id": "11446498",
              "type": "user"
            }
          }
        ]
      }
    ]
  }
  ```
</Accordion>


# Zip Downloads resources
Source: https://developer.box.com/reference/zip-downloads-resources



Zip downloads represent a successful request to create a ZIP archive with files and folders.

## Zip download

Represents a successful request to create a `zip` archive of a list of files and folders.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `download_url` | `string` | No | The URL that can be used to download the `zip` archive. A `Get` request to this URL will start streaming the items requested. By default, this URL is only valid for a few seconds, until the `expires_at` time, unless a download is started after which it is valid for the duration of the download. It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is. |
  | `status_url` | `string` | No | The URL that can be used to get the status of the `zip` archive being downloaded. A `Get` request to this URL will return the number of files in the archive as well as the number of items already downloaded or skipped. By default, this URL is only valid for a few seconds, until the `expires_at` time, unless a download is started after which the URL is valid for 12 hours from the start of the download. It is important to note that the domain and path of this URL might change between API calls, and therefore it's important to use this URL as-is. |
  | `expires_at` | `string` | No | The time and date when this archive will expire. After this time the `status_url` and `download_url` will return an error. By default, these URLs are only valid for a few seconds, unless a download is started after which the `download_url` is valid for the duration of the download, and the `status_url` is valid for 12 hours from the start of the download. |
  | `name_conflicts` | array of array of `object` | No | A list of conflicts that occurred when trying to create the archive. This would occur when multiple items have been requested with the same name. To solve these conflicts, the API will automatically rename an item and return a mapping between the original item's name and its new name. For every conflict, both files will be renamed and therefore this list will always be a multiple of 2. |

  ```json Example theme={null}
  {
    "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content",
    "status_url": "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status",
    "expires_at": "2020-07-22T11:26:08Z",
    "name_conflicts": [
      [
        {
          "id": "12345",
          "type": "file",
          "original_name": "Report.pdf",
          "download_name": "3aa6a7.pdf"
        },
        {
          "id": "34325",
          "type": "file",
          "original_name": "Report.pdf",
          "download_name": "5d53f2.pdf"
        }
      ]
    ]
  }
  ```
</Accordion>

## Zip download status

The status of a `zip` archive being downloaded.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `total_file_count` | `integer` | No | The total number of files in the archive. |
  | `downloaded_file_count` | `integer` | No | The number of files that have already been downloaded. |
  | `skipped_file_count` | `integer` | No | The number of files that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded. |
  | `skipped_folder_count` | `integer` | No | The number of folders that have been skipped as they could not be downloaded. In many cases this is due to permission issues that have surfaced between the creation of the request for the archive and the archive being downloaded. |
  | `state` | `enum<string>` | No | The state of the archive being downloaded. Available options: `in_progress`, `failed`, `succeeded`. |

  ```json Example theme={null}
  {
    "total_file_count": 20,
    "downloaded_file_count": 10,
    "skipped_file_count": 5,
    "skipped_folder_count": 5,
    "state": "succeeded"
  }
  ```
</Accordion>


# Tools
Source: https://developer.box.com/sdks-and-tools

The following SDKs and tools are developed and supported by Box

## SDKs

Here you will find a list of SDKs
you can use to build your application.

<Note>
  The tables below list SDKs along with additional information
  telling you if the project is maintained and has API
  parity.

  **Status:** Describes the current project status. To learn more about statuses visit [Box Open Source website][badges].
  Active projects are actively developed by Box. They receive the latest security updates and new features. For
  support with these projects please visit GitHub or [our Platform support forum][forum].

  **API Parity**: Projects with full API parity are actively updated with all
  platform functionality as this becomes available on Box. Projects
  with partial API parity lack some functionality while we work on bringing
  these projects to full parity.
</Note>

### SDKs

The table lists Box SDKs that you can use when building your
applications. For the latest API support and features, use the next
generation SDKs.

| Platform | Status | API Parity |
| - | - | - |
| [Java SDK][javasdk] | Active | Full |
| [iOS Content SDK][iossdk] | Active | Full |
| [.NET SDK][dotnetsdk] | Active | Full |
| [Python SDK][pythonsdk] | Active | Full |
| [Node SDK][nodesdk] | Active | Full |
| [Android Content SDK][androidsdk] | Deprecated | Partial |

<Warning>
  As of May 31, 2023 Android SDK is no
  longer supported. You can still
  use your existing Android SDK applications
  with no impact, but you won't receive new features,
  updates, or bug fixes.

  If you would like to continue getting the
  latest and greatest Android features, we
  recommend using Java SDK to build apps on Android.
  Refer to [this][android-docs] documentation for more details.
</Warning>

### Next Generation SDKs

<Warning>
  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts.

  Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  **All future development, including new features and updates, will be delivered through the Box core SDKs. The standalone generated artifact was introduced in the version `v10` of the Box core SDKs.**

  For more details, see our [SDK versioning strategy document][versioning].
</Warning>

Here's what you can expect from `v10`:

* **Full API support**: New Box SDKs empower developers with complete coverage of the Box API ecosystem. You can access all the latest features and functionalities offered by Box and build feature-rich applications.
* **Rapid API updates**: The new auto-generation development approach allows you to add Box APIs to SDKs at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
* **Embedded documentation**: All objects and parameters are documented directly in the source code of the SDK so all the necessary information is stored in one place.
* **Enhanced convenience methods**: The newly introduced convenience methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers that help to ensure that you’re using variables correctly, and much more.

## Box CLI

Box CLI is a user-friendly command line tool that
allows both technical and non-technical users to
leverage Box API to perform routine or bulk actions.

| Platform | Status | API Parity |
| - | - | - |
| [CLI][cli] | Active | Full |

## Box Mount

Box Mount brings Box content into any agent runtime as a standard POSIX filesystem. Agents read, write, and edit files using familiar file operations, with Box security, governance, and access controls applied to every operation. Continuous two-way sync keeps agent and Box content aligned, so people and agents collaborate in the same folders with built-in conflict protection.

<Note>
  Box Mount is in private preview. It is not publicly available and is not covered
  by a production SLA. To request access, complete the
  [Box Mount private preview form](https://bit.ly/box-mount-preview).
</Note>

<Card title="Get started with Box Mount" href={localizeLink("/guides/box-mount")} />

## Postman Collection

[Postman][postman] is a tool that lets you build and test HTTP requests in an
easy-to-use interface without configuring a full development environment. The
**Box Postman Collection** is a set of preconfigured requests that make it
possible to get started with the Box API without having to manually configure
the requests.

The simplest way to get started with Postman is with our Postman Quick Start guide.

<Card title="Get Started with the Box Postman Collection" href={localizeLink("/guides/tooling/postman")} />

## Salesforce Developer Toolkit

The Box for Salesforce Developer Toolkit allows customers to programmatically
customize the behavior of the Box for Salesforce integration. The Toolkit
consists of several global APEX methods that can be used to trigger and extend
the default behavior. The global methods can update the internal Salesforce
record to Box folder mapping and handle permission management.

<Note>
  This functionality is part of the latest Box for
  [Salesforce package][sf-package].
</Note>

<Warning>
  **What the Toolkit does NOT provide**

  The Toolkit is not a full-featured APEX wrapper for the BOX Content API. If
  this is what you are looking for, have a look at the
  [Box SDK for Salesforce][sf-sdk].
</Warning>

## Official UI Libraries

Extend your application with pre-built UI components to browse, share, and
preview files on Box.

| | | |
| - | - | - |
| Browse | Share | Preview |
| ![Browse][browseimg] | ![Share][shareimg] | ![Preview][previewimg] |
| Navigate and manipulate your files on Box using our pre-built UI. | Share files with our pre-built UI elements for file & folder collaboration. | Review over 120 file types, from PDFs to HD videos, with a rich preview experience. |

| Platform | |
| - | - |
| iOS | [Browse SDK][iosbrowsesdk], [Share SDK][iossharesdk], [Preview SDK][iospreviewsdk] |
| Android | [Browse SDK](https://github.com/box/box-android-browse-sdk), [Share SDK](https://github.com/box/box-android-share-sdk), [Preview SDK](https://github.com/box/box-android-preview-sdk) |
| Javascript | [Box UI Elements](/guides/embed/ui-elements) |

## Unofficial & Community Tools

The following tools are developed and maintained by Box and its community
members. These tools do not receive regular product updates or security updates.

| Platform | Maintained? | API Parity |
| - | - | - |
| [Salesforce SDK][salesforcesdk] | Limited, by Box and community members | Partial |
| [Ruby SDK][rubysdk] | Limited, by Box and community members | Partial |
| [Client-side JS SDK][jssdk] | Limited, by Box and community members | Partial |

<Note>
  **Maintained:** Projects with limited maintenance are updated by Box in
  collaboration with the community. They receive irregular security updates. If
  you are a Box customer on a premium support plan, please contact customer
  services for any urgent feature requests for these tools. For other support
  queries with these projects please visit GitHub or [our Platform support forum][forum].

  **API Parity:**  Projects with limited API parity can lack some functionality
  as new features are not automatically rolled out to these projects as they
  become available for Box. If you are a Box customer on a premium
  support plan, please contact customer services for any urgent feature requests
  for these tools.
</Note>

[javasdk]: https://github.com/box/box-java-sdk

[dotnetsdk]: https://github.com/box/box-windows-sdk-v2

[pythonsdk]: https://github.com/box/box-python-sdk

[nodesdk]: https://github.com/box/box-node-sdk

[iossdk]: https://github.com/box/box-ios-sdk

[androidsdk]: https://github.com/box/box-android-sdk

[android-docs]: https://github.com/box/box-java-sdk/blob/legacy/doc/android.md

[cli]: https://github.com/box/boxcli

[forum]: https://community.box.com/

[browseimg]: /static/sdks/browse.webp

[shareimg]: /static/sdks/share.webp

[previewimg]: /static/sdks/preview.webp

[iosbrowsesdk]: https://github.com/box/box-ios-browse-sdk

[iossharesdk]: https://github.com/box/box-ios-share-sdk

[iospreviewsdk]: https://github.com/box/box-ios-preview-sdk

[salesforcesdk]: https://github.com/box/box-salesforce-sdk

[rubysdk]: https://github.com/cburnette/boxr

[jssdk]: https://github.com/allenmichael/box-javascript-sdk

[postman]: https://postman.com

[badges]: https://opensource.box.com/badges/

[versioning]: /guides/tooling/sdks/sdk-versioning

[sf-package]: https://support.box.com/hc/en-us/articles/360044195713-Installing-and-Configuring-Box-For-Salesforce

[sf-sdk]: https://github.com/box/box-salesforce-sdk


# 2018
Source: https://developer.box.com/changelog/2018

Box Platform changelog: API, SDK, and product updates from 2018.

<Update label="2018-12-21">
  ## Box CLI V2 release

  A major version release (V2) has been made to the <Link href="/guides/cli">Box CLI</Link>.

  See the following links for updated information:

  * [Release notes](https://github.com/box/boxcli/blob/master/CHANGELOG.md#200): Major revision details, breaking
    changes, and bug fixes.
  * [Command list](https://github.com/box/boxcli#command-topics): All commands available in the new
    CLI.
  * <Link href="/guides/cli">Installation options</Link>: Standalone installers and
    source code options.
</Update>

<Update label="2018-12-14">
  ## Windows .NET SDK v3.10.0 released

  1. Added functionality for Metadata Cascade Policy

  [`nuget.org/packages/Box.V2`](https://www.nuget.org/packages/Box.V2)
  [`nuget.org/packages/Box.V2.Core`](https://www.nuget.org/packages/Box.V2.Core/)
</Update>

<Update label="2018-12-13">
  ## Java SDK v2.25.0 released

  1. Allow content streaming to box through `outputstream`. [#667](https://github.com/box/box-java-sdk/pull/667)
</Update>

<Update label="2018-12-12">
  ## Collaborations now show unregistered users

  An additional field, `invite_email`, has been added to the collaboration return
  object in the instance where an unregistered user has been added as a
  collaborator on a file or folder. This change was put in place because the
  current `accessible_by` object returned would show `null` as the result for an
  unregistered user. The new field will now show the email address that was used
  to invite the user.

  This change affects the following endpoints:

  * [Get Collaboration](/reference/get-collaborations-id)
  * [Get File Collaborations](/reference/get-files-id-collaborations)
  * [Get Folder Collaborations](/reference/get-folders-id-collaborations)

  Previously a collaboration object with an unregistered user would look like the
  following:

  ```js theme={null}
  {
    "type": "collaboration",
    "id": "376164239",
    .....
    "accessible_by":  null
    .....
  }
  ```

  With this new update the object returned would look like the following:

  ```js theme={null}
  {
    "type": "collaboration",
    "id": "376164239",
    ......
    "accessible_by":  null
    "invite_email": "sadfasdf@box.com",
    },
    ......
  }
  ```
</Update>

<Update label="2018-12-05">
  ## Enterprise events API adds created\_by for supervisors

  A minor change has been made to the response object of the
  [enterprise events](/reference/get-events/#request) API endpoint in the
  event that an action is taken by a supervisor or internal admin user, such as a
  Box admin.

  Prior to this update the user information of the supervisor or internal admin
  user would be displayed in the `created_by` field of the response object. With
  this update the response will now show generic user information when that user
  is a supervisor or internal admin.

  Previously the `created_by` field in the response looked like this:

  ```js theme={null}
  "created_by": {
    "type": "user",
    "id": "2030401181",
    "name": "sshah+iadev",
    "login": "admin_sshah"
  }
  ```

  With this update that same response would look similar to the following:

  ```js theme={null}
  "created_by": {
    "type": "user",
    "id": "box_support",
    "name": "Box Support",
    "login": "support@box.com"
  }
  ```
</Update>

<Update label="2018-11-16">
  ## Java SDK v2.24.0 released

  1. added tests and implementation for options object ([#661](https://github.com/box/box-java-sdk/pull/661))
  2. Expose object type on `BoxItem` ([#662](https://github.com/box/box-java-sdk/pull/662))
  3. Allow per-connection timeouts ([#660](https://github.com/box/box-java-sdk/pull/660))
  4. Add global setting for max requests ([#657](https://github.com/box/box-java-sdk/pull/657))
  5. added overload for `is_ongoing` field and added getter for `is_ongoing` ([#653](https://github.com/box/box-java-sdk/pull/653))
</Update>

<Update label="2018-11-01" description="Python SDK v2.0.0 released">
  ## Breaking Changes

  * Python 2.6 is no longer supported.

  * Python 3.3 is no longer supported.

  * `client.search()` now returns a `Search` object that exposes a `query()` method to call the Search API.
    Use `client.search().query(**search_params)` instead of `client.search(**search_params)`.

  * `client.get_memberships(...)` has a change in signature. The limit and offset parameters have swapped positions to keep
    consistency with the rest of the SDK.

  * `client.groups(...)` has been changed to `client.get_groups`. The limit and offset parameters have swapped positions.

  * The `unshared_at` parameter for `item.create_shared_link(...)` and `file.get_shared_link_download_url(...)`
    now takes an `RFC3339-formatted <https://tools.ietf.org/html/rfc3339#section-5.8>` `unicode` string instead of a
    `datetime.date`.  Users migrating from `v1.x` can pass the value of `date.isoformat()` instead of the `date`
    object itself.

  * `Events.get_events(...)` now returns a list of `Event` instances rather than a list of `dict`
    representing events.  `Event` inherits from `Mapping` but will not have all the same capabilities as
    `dict`.

    * Your code is affected if you use `Events.get_events(...)` and expect a list of `dict` rather than a list of
      `Mapping`.  For example, if you use `__setitem__` (`event['key'] = value`), `update()`, `copy()`, or
      if your code depends on the `str` or `repr` of the `Event`.  Use of `__getitem__` (`event['key']`),
      `get()`, and other `Mapping` methods is unaffected.  See the [Python
      documentation](https://docs.python.org/2.7/library/collections.html#collections-abstract-base-classes) for methods supported on
      `Mapping` instances.

    * Migration: If you still need to treat an `Event` as a `dict`, you can get a deepcopy of the original `dict`
      using the new property on `BaseAPIJSONObject`, `response_object`.

  * `LoggingNetwork` has been removed. Logging calls are now made from the `DefaultNetwork` class. In addition,
    the logging format strings in this class have changed in a way that
    will break logging for any applications that have overridden any of these
    strings. They now use keyword format placeholders instead of positional
    placeholders. All custom format strings will now have to use the same keyword
    format placeholders. Though this is a breaking change, the good news is that
    using keyword format placeholders means that any future changes will be
    automatically backwards-compatible (as long as there aren't any changes to
    change/remove any of the keywords).

  * `File.update_contents()` and `File.update_contents_with_stream()` now
    correctly return a `File` object with the correct internal JSON structure.
    Previously it would return a `File` object where the file JSON is hidden
    inside `file['entries'][0]`. This is a bug fix, but will be a breaking
    change for any clients that have already written code to handle the bug.

  * Comparing two objects (e.g. a `File` and a `Folder`) that have the same Box ID but different types with `==`
    will now correctly return `False`.

  * The following methods now return iterators over the entire collection of returned objects, rather than
    a single page:

    * `client.users()`
    * `client.groups()`
    * `client.search().query()`
    * `folder.get_items()`

    Since `folder.get_items()` now returns an iterator, `folder.get_items_limit_offset()` and
    `folder.get_items_marker()` have been removed.  To use marker based paging with `folder.get_items()`,
    pass the `use_marker=True` parameter and optionally specify a `marker` parameter to begin paging from that
    point in the collection.

    Additionally, `group.membership()` has been renamed to `group.get_memberships()`, and returns an iterator of
    membership objects.  This method no longer provides the option to return tuples with paging information.

  * The `Translator` class has been reworked; `translator.get(...)` still returns the constructor for the object class
    corresponding to the passed in type, but `translator.translate(...)` now takes a `Session` and response object
    directly and produces the translated object.  This method will also translate any nested objects found.

    * This change obviates the need for `GroupMembership` to have a custom constructor; it now uses the default
      `BaseObject` constructor.

  ## Features

  * All publicly documented API endpoints and parameters should now be supported by the SDK

  * Added more flexibility to the object translation system:

    * Can create non-global `Translator` instances, which can extend or
      not-extend the global default `Translator`.
    * Can initialize `BoxSession` with a custom `Translator`.
    * Can register custom subclasses on the `Translator` which is associated
      with a `BoxSession` or a `Client`.
    * All translation of API responses now use the `Translator` that is
      referenced by the `BoxSession`, instead of directly using the global
      default `Translator`.
    * Nested objects are now translated by `translator.translate()`

  * When the `auto_session_renewal` is `True` when calling any of the request
    methods on `BoxSession`, if there is no access token, `BoxSession` will
    renew the token *before* making the request. This saves an API call.

  * Auth objects can now be closed, which prevents them from being used to
    request new tokens. This will also revoke any existing tokens (though that
    feature can be turned off by passing `revoke=False`). Also introduces a
    `closing()` context manager method, which will auto-close the auth object
    on exit.

  * Various enhancements to the `JWTAuth` baseclass:

    * The `authenticate_app_user()` method is renamed to
      `authenticate_user()`, to reflect that it may now be used to authenticate
      managed users as well. See the method `docstring` for details.
      `authenticate_app_user()` is now an alias of `authenticate_user()`, in
      order to not introduce an unnecessary backwards-incompatibility.
    * The `user` argument to `authenticate_user()` may now be either a user
      ID string or a `User` instance. Before it had to be a `User` instance.
    * The constructor now accepts an optional `user` keyword argument, which
      may be a user ID string or a `User` instance. When this is passed,
      `authenticate_user()` and can be called without passing a value for the
      `user` argument. More importantly, this means that `refresh()` can be
      called immediately after construction, with no need for a manual call to
      `authenticate_user()`. Combined with the aforementioned improvement to
      the `auto_session_renewal` functionality of `BoxSession`, this means
      that authentication for `JWTAuth` objects can be done completely
      automatically, at the time of first API call.
    * The constructor now supports passing the RSA private key in two different
      ways: by file system path (existing functionality), or by passing the key
      data directly (new functionality). The `rsa_private_key_file_sys_path`
      parameter is now optional, but it is required to pass exactly one of
      `rsa_private_key_file_sys_path` or `rsa_private_key_data`.
    * Document that the `enterprise_id` argument to `JWTAuth` is allowed to
      be `None`.
    * `authenticate_instance()` now accepts an `enterprise` argument, which
      can be used to set and authenticate as the enterprise service account user,
      if `None` was passed for `enterprise_id` at construction time.
    * Authentications that fail due to the expiration time not falling within the
      correct window of time are now automatically retried using the time given
      in the Date header of the Box API response. This can happen naturally when
      the system time of the machine running the Box SDK doesn't agree with the
      system time of the Box API servers.

  * Added an `Event` class.

  * Moved `metadata()` method to `Item` so it's now available for `Folder`
    as well as `File`.

  * The `BaseAPIJSONObject` baseclass (which is a superclass of all API
    response objects) now supports `__contains__` and `__iter__`. They behave
    the same as for `Mapping`. That is, `__contains__` checks for JSON keys
    in the object, and `__iter__` yields all of the object's keys.

  * Added a `RecentItem` class.

  * Added `client.get_recent_items()` to retrieve a user's recently accessed items on Box.

  * Added support for the `can_view_path` parameter when creating new collaborations.

  * Added `BoxObjectCollection` and subclasses `LimitOffsetBasedObjectCollection` and
    `MarkerBasedObjectCollection` to more directly manage paging of objects from an endpoint.
    These classes manage the logic of constructing requests to an endpoint and storing the results,
    then provide `__next__` to iterate over the results. The option to return results one
    by one or as a `Page` of results is also provided.

  * Added a `downscope_token()` method to the `Client` class. This generates a token that
    has its permissions reduced to the provided scopes and for the optionally provided
    `File` or `Folder`.

  * Added methods for configuring `JWTAuth` from config file: `JWTAuth.from_settings_file` and
    `JWTAuth.from_settings_dictionary`.

  * Added `network_response` property to `BoxOAuthException`.

  * API Configuration can now be done per `BoxSession` instance.

  ## Other

  * Added extra information to `BoxAPIException`.
  * Added `collaboration()` method to `Client`.
  * Reworked the class hierarchy.  Previously, `BaseEndpoint` was the parent of `BaseObject` which was the parent
    of all smart objects.  Now `BaseObject` is a child of both `BaseEndpoint` and `BaseAPIJSONObject`.
    `BaseObject` is the parent of all objects that are a part of the REST API.  Another subclass of
    `BaseAPIJSONObject`, `APIJSONObject`, was created to represent pseudo-smart objects such as `Event` that are not
    directly accessible through an API endpoint.
  * Added `network_response_constructor` as an optional property on the
    `Network` interface. Implementations are encouraged to override this
    property, and use it to construct `NetworkResponse` instances. That way,
    subclass implementations can extend the functionality of the
    `NetworkResponse`, by re-overriding this property. This property is defined
    and used in the `DefaultNetwork` implementation.
  * Move response logging to a new `LoggingNetworkResponse` class (which is
    made possible by the aforementioned `network_response_constructor`
    property). Now the SDK decides whether to log the response body, based on
    whether the caller reads or streams the content.
  * Add more information to the request/response logs from `LoggingNetwork`.
  * Add logging for request exceptions in `LoggingNetwork`.
  * Bugfix so that the return value of `JWTAuth.refresh()` correctly matches
    that of the auth interface (by returning a tuple of
    ((access token), (refresh token or None)), instead of only the access token).
    In particular, this fixes an exception in `BoxSession` that always occurred
    when it tried to refresh any `JWTAuth` object.
  * Fixed an exception that was being raised from `ExtendableEnumMeta.__dir__()`.
  * `CPython` 3.6 support.
  * Increased required minimum version of six to 1.9.0.
</Update>

<Update label="2018-10-19">
  ## Python SDK v2 Launched

  A major update (version 2.0) of the [Box Python SDK](https://github.com/box/box-python-sdk) has been
  released with significant updates and API feature parity completion.
  [See here](https://github.com/box/box-python-sdk/releases/tag/v2.0.0) for full API release notes. Along with
  the release, the following documentation changes have been made:

  * Updated Python [quick start guides](/guides/).
  * Updated Python [API references](/reference/) code samples.
</Update>

<Update label="2018-09-27">
  ## New Box Open With Sidebar UI Element

  We have released an open beta version of a new Box UI Element, the 'Open With'
  element. 'Open With' will allow developers to embed a menu to open content
  stored in box with a partner application. The partners available with this beta
  release are Adobe Sign and G Suite.

  Documentation and setup instructions for this new element are
  [available here](/guides/embed/ui-elements).
</Update>

<Update label="2018-09-27">
  ## Java SDK v2.23.2 released

  1. Batch headers patch ([#649](https://github.com/box/box-java-sdk/pull/649))
</Update>

<Update label="2018-09-13">
  ## Java SDK v2.23.1 released

  1. Fix opening too many TCP connections when issuing a high number of requests ([#646](https://github.com/box/box-java-sdk/pull/646))
</Update>

<Update label="2018-09-13">
  ## Annotations available for Excel files in preview

  Currently, annotations capabilities don't appear within Excel files in preview,
  either via the
  [Box UI Content Preview element](/guides/embed/ui-elements) or
  expiring embed, even if annotations are enabled (`showAnnotations=true`).

  Starting on **September 13th, 2018**, users will be able to annotate Excel
  files like they can other file types (PDFs, docs, PPT). All 3 annotation
  types (highlight, point, and drawing) will be supported. If `showAnnotations`
  is set to `true` annotations on Excel files will be displayed.
</Update>

<Update label="2018-09-04">
  ## Windows .NET SDK v3.9.3 released

  * Strong named the assembly

  [`nuget.org/packages/Box.V2/3.9.3`](https://www.nuget.org/packages/Box.V2/3.9.3)
  [`nuget.org/packages/Box.V2.Core/3.9.3`](https://www.nuget.org/packages/Box.V2.Core/3.9.3)
</Update>

<Update label="2018-08-23">
  ## Java SDK v2.23.0 released

  1. Metadata cascade policy ([#603](https://github.com/box/box-java-sdk/pull/603))
</Update>

<Update label="2018-08-21">
  ## Add new fields to folder update and get info endpoints

  Two major releases have been added to the [update folder API endpoint](/reference/put-folders-id),
  `is_collaboration_restricted_to_enterprise`. This is a boolean value made to
  set whether future collaborations should be restricted to within the enterprise
  only. This does not affect existing collaborations. The value of this field
  will also be displayed when calling the [get folder info endpoint](/reference/get-folders-id).
</Update>

<Update label="2018-08-21">
  ## Add new action\_by field to enterprise events

  To better document admin actions taken on user accounts, we have added an
  `action_by` mini-user object in the enterprise events response data. This field
  will display the admin account which performed the user action, if applicable.

  For enterprise admins this would include the ID, login, and name of their
  account. For actions taken by a Box internal admin this would be:

  * id: `box_support`
  * login: `support@box.com`
  * name: `Box Support`

  The additional object is documented within the enterprise
  [event object attributes](/reference/events-resources#event).
</Update>

<Update label="2018-08-17">
  ## Box user\_id field size changed

  The `user_id` field, used to track all platform users (that is, managed,
  externally managed, and app users), will soon be updated to begin producing
  64-bit integer numeric values, rather than the 32-bit integers it creates
  currently.

  For customers who are translating the produced `user_id` strings from our APIs
  into 32-bit integer fields, your internal systems are affected by this update,
  and you must update them to support the new 64-bit `user_id` integer size. We
  recommend that all `user_id` fields be stored as strings, as per our
  [API documentation](/reference/users-resources#user).
</Update>

<Update label="2018-08-16" description="Generic method added to the Salesforce SDK">
  ## Generic method added to the Salesforce SDK

  The Box for Salesforce Developer Toolkit now provides a global method,
  `sendRequest` that accepts an [`HttpRequest`](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_httprequest.htm)
  object as a parameter and returns an
  [`HttpResponse`](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_httpresponse.htm#apex_classes_restful_http_httpresponse)
  object. This method will use the authentication details of the Service
  Account to make calls to Box's APIs, allowing you to focus on incorporating
  the business logic of your integration. For more details about the added
  method, please see the [method details](/guides/tooling/sdks/salesforce)
  and [sample code](/guides/tooling/sdks/salesforce)
  in the Box metadata sidebar for Salesforce Developer Toolkit documentation.
</Update>

<Update label="2018-08-09">
  ## Java SDK v2.22.0 Released

  1. patch for transfer content to another user ([#632](https://github.com/box/box-java-sdk/pull/632))
</Update>

<Update label="2018-07-31">
  ## Expanded Relay Workflow API

  We have expanded the capabilities of [Box Relay](https://www.box.com/collaboration/relay-workflow), a workflow tool
  co-developed between Box and IBM, with a new Workflow API. The Relay Workflow
  API allows you to launch Box Relay workflows and retrieve the statuses of those
  workflows from within your application. It also allows you to view which
  workflow templates have been published in file directly into your instance of
  Box Relay. For more information about the API, please see our
  [announcement blog post](https://medium.com/box-developer-blog/introducing-the-box-relay-workflow-api-f6eed1457711).
</Update>

<Update label="2018-07-11">
  ## Historical Platform Activity CSV report

  A new report has been made available via the website. Documentation is available
  in the Box Admin Console that displays an enterprise's historical utilization of
  platform resources. This report displays an enterprise's Monthly Active Users,
  API calls, and bandwidth consumption by application by month for
  January 1, 2017 to March 31, 2018. More information can be found
  [here](https://docs.box.com/en/box-admin-tools/reporting-and-insights/running-reports).
</Update>

<Update label="2018-07-06">
  ## Java SDK v2.21.0 released

  1. `Sharedlink` password ([#623](https://github.com/box/box-java-sdk/pull/623))
  2. Correct link ([#626](https://github.com/box/box-java-sdk/pull/626))
</Update>

<Update label="2018-06-28">
  ## Java SDK v2.20.2 released

  1. Case Insensitivity for Response Headers ([#620](https://github.com/box/box-java-sdk/pull/620))
</Update>

<Update label="2018-06-25">
  ## Update to the Box CLI

  We have released updates to the [Box CLI](/guides/cli). This
  version includes the following updates:

  * **[New Multizones commands](https://github.com/box/boxcli/pull/91)**: Adds support for
    [Box Multizones](https://blog.box.com/blog/multizones-storage-data-residency-compliance/) for data residency.
  * **[Fix for user CSV operations](https://github.com/box/boxcli/pull/82)**: Fixes a bug that
    prevented users using Open With Element: The Open With element has been moved
    from saving users data beta to CSV files.

  - **[Ability to set `can_non_owners_invite` flag on folder updates](https://github.com/box/boxcli/pull/92)**:
    Allows setting whether non-owners can invite other users to collaborate on the
    folder.

  * **[New CLI configuration dump command](https://github.com/box/boxcli/pull/83)**: Adds the
    ability to dump the Box configuration file as a single string, optionally with
    escaped quotes, in order to copy the value to general availability. Open With
    delivers an environment variable or configuration property (for example, in AWS
    individual button or Azure).
</Update>

<Update label="2018-06-18">
  ## Box Android SDK v4.2.0 released

  This version is to provide support for 16+ devices once TLS 1.0 is deprecated.
</Update>

<Update label="2018-06-14">
  ## Windows .NET SDK v3.9.2 released

  * Added support for setting flag allowing non owners of a folder to invite collaborators.

  [`nuget.org/packages/Box.V2/3.9.2`](https://www.nuget.org/packages/Box.V2/3.9.2)
  [`nuget.org/packages/Box.V2.Core/3.9.2`](https://www.nuget.org/packages/Box.V2.Core/3.9.2)
</Update>

<Update label="2018-06-07">
  ## Windows .NET SDK v3.9.1 released

  Fixed bug where Xamarin applications would run out of connections.

  [`nuget.org/packages/Box.V2/3.9.1`](https://www.nuget.org/packages/Box.V2/3.9.1)
  [`nuget.org/packages/Box.V2.Core/3.9.1`](https://www.nuget.org/packages/Box.V2.Core/3.9.1)
</Update>

<Update label="2018-06-04">
  ## Java SDK v2.20.1 released

  1. Handle JSON parse error in response exception ([#615](https://github.com/box/box-java-sdk/pull/615))
  2. Fix return object for `uploadNewVersion()` ([#614](https://github.com/box/box-java-sdk/pull/614))
</Update>

<Update label="2018-05-24">
  ## Java SDK v2.20.0 released

  * multi select metadata field ([#610](https://github.com/box/box-java-sdk/pull/610))
  * Fix check for duplicate As-User headers ([#612](https://github.com/box/box-java-sdk/pull/612))
</Update>

<Update label="2018-05-10">
  ## Windows .NET SDK v3.9.0 released

  * Added support for Storage Policies

  [`nuget.org/packages/Box.V2/3.9.0`](https://www.nuget.org/packages/Box.V2/3.9.0)
  [`nuget.org/packages/Box.V2.Core/3.9.0`](https://www.nuget.org/packages/Box.V2.Core/3.9.0)
</Update>

<Update label="2018-05-10">
  ## Java SDK v2.19.0 released

  1. Multizones ([#598](https://github.com/box/box-java-sdk/pull/598))
  2. Add `getLogin()` method on `BoxCollaborator.Info` ([#602](https://github.com/box/box-java-sdk/pull/602))
  3. Add support for `multiSelect` fields in metadata ([#597](https://github.com/box/box-java-sdk/pull/597))
</Update>

<Update label="2018-04-30">
  ## Windows .NET SDK v3.8.0 released

  * Fixed an issue where users could not create `BoxClient` on `Xamarin`
  * Added File property to `BoxLock` objects in events
  * Added `MetadataManager.DeleteMetadataTemplate(string scope, string template)` for deleting a Metadata template
  * Made API URLs modifiable in `BoxConfig`
  * Improved API response error objects/messages

  [`nuget.org/packages/Box.V2/3.8.0`](https://www.nuget.org/packages/Box.V2/3.8.0)
  [`nuget.org/packages/Box.V2.Core/3.8.0`](https://www.nuget.org/packages/Box.V2.Core/3.8.0)
</Update>

<Update label="2018-04-30">
  ## Java SDK v2.18.0 released

  1. Error object ([#588](https://github.com/box/box-java-sdk/pull/588))
  2. Quick fix for NPE on `request.toString()` in interceptor ([#595](https://github.com/box/box-java-sdk/pull/595))
  3. Add support for fetching representation content ([#583](https://github.com/box/box-java-sdk/pull/583))
  4. fixed `BoxConfig` constructor method where `privateKeyPassword` was not being set ([#593](https://github.com/box/box-java-sdk/pull/593))
</Update>

<Update label="2018-04-18">
  ## Platform Activity CSV report

  A report has been made available in the Box Admin Console that displays an
  enterprise's utilization of platform resources. The first version of this
  report displays integration into the total number of API calls to the Box
  existing Content API by day effective April 1st, 2018. Future iterations of
  this report will display additional resource consumption (Monthly Active Users,
  bandwidth, and storage) by service and will also include historical data. For
  more information, please see the <Link href="https://support.box.com/hc/en-us/articles/360043696534-Running-Reports">Running Reports</Link> article in Box
  product documentation.
</Update>

<Update label="2018-04-11">
  ## Windows .NET SDK v3.7.0 released

  1. Added support for assigning a retention policy to a metadata template
  2. Added `CONTENT_ACCESS` event type to enum

  [`nuget.org/packages/Box.V2/3.7.0`](https://www.nuget.org/packages/Box.V2/3.7.0)
  [`nuget.org/packages/Box.V2.Core/3.7.0`](https://www.nuget.org/packages/Box.V2.Core/3.7.0)
</Update>

<Update label="2018-04-11">
  ## Metadata-driven retention policies

  We have introduced new functionality in the
  [Retention Policy Object](/reference/retention-policies-resources#retention-policy)
  API Explorer element to support metadata-driven retention policies, where
  retention policies can be applied to individual files based on custom metadata.
  This also enables customers to configure retention policies at the launch file
  level in addition to at the global and folder levels. In addition to bringing
  these new, expanded Box Governance capabilities to Box Admins via the Box Admin
  Console, we’re also making these capabilities available via the
  [Retention Policy](/reference/retention-policies-resources#retention-policy) and
  [Retention Assignment](/reference/retention-policy-assignments-resources#retention-policy-assignment) APIs
  and in Box's Java, Node, and .NET [SDKs](/guides/tooling/sdks).
</Update>

<Update label="2018-04-11">
  ## Box CLI v1.2.0 released

  * Created bulk actions for the following commands:
  * users
    * update
  * groups
    * create
    * update
    * delete
  * group memberships
    * create
    * update
    * delete
  * collaborations
    * add
    * update
    * delete
  * Added filtering by event type to `box events get` and `box events poll`
  * Added a command for deleting metadata templates from files and folders.
  * Bumped underlying `box-windows-sdk` to `v3.6.0`
  * Fixed a bug hindering creating float types for metadata on files and folders.
  * Fixed a bug that did not assign the `User-Agent` HTTP header correctly.
  * Fixed a bug that wasn't reporting all errors to `stderr`.
  * Fixed a bug with bulk creation of metadata templates.
  * Fixed a bug giving duplicate commands on group `membership` command.
  * Fixed a bug with creating the wrong object for `tracking_codes` on users.
  * Fixed a bug requiring an ID in CSV files on bulk creation of users.
</Update>

<Update label="2018-04-10">
  ## Java SDK v2.17.0 released

  1. Add Metadata-driven Retention Policies support ([#535](https://github.com/box/box-java-sdk/pull/535))
</Update>

<Update label="2018-03-29">
  ## multiSelect field type added to metadata templates

  We have introduced a new attribute type to
  [Metadata Templates](/reference/metadata-templates-resources#metadata-template) called
  `multiSelect`, which translates to multiple selection. This new attribute type
  allows for a checkbox style multiple selection of values when composing
  template instances on files content with Adobe Sign, G Suite, or folders.

  The addition of this field introduces changes to the
  [Metadata Object](/reference/metadata-templates-resources#metadata-template) (template instance)
  since enabled `multiSelect` options are represented using an array of string
  values, where each string in the array corresponds to the key of a `multiSelect`
  option.
</Update>

<Update label="2018-03-29">
  ## Java SDK v2.16.1 released

  1. Add `CONTENT_ACCESS` event type.  ([#581](https://github.com/box/box-java-sdk/pull/581))
</Update>

<Update label="2018-03-28">
  ## Update to Box Annotations

  The annotations update announced on March 5, 2018 has been re-enabled.
</Update>

<Update label="2018-03-27">
  ## Windows .NET SDK v3.6.0 released

  [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#360)

  [`nuget.org/packages/Box.V2/3.6.0`](https://www.nuget.org/packages/Box.V2/3.6.0)
  [`nuget.org/packages/Box.V2.Core`](https://www.nuget.org/packages/Box.V2.Core)
</Update>

<Update label="2018-03-22">
  ## Java SDK v2.16.0 released

  1. Adjust JWT expiration interval ([#572](https://github.com/box/box-java-sdk/pull/572))
  2. Allow setting custom headers on API connection ([#562](https://github.com/box/box-java-sdk/pull/562))
  3. Fix JWT retry timestamp parsing ([#575](https://github.com/box/box-java-sdk/pull/575))
  4. Add support for User Tracking Codes ([#487](https://github.com/box/box-java-sdk/pull/487))
</Update>

<Update label="2018-03-21">
  ## Windows .NET SDK v3.5.2 released

  Fix .NET Core package

  [`nuget.org/packages/Box.V2/3.5.2`](https://www.nuget.org/packages/Box.V2/3.5.2)
  [`nuget.org/packages/Box.V2.Core/3.5.2`](https://www.nuget.org/packages/Box.V2.Core/3.5.2)
</Update>

<Update label="2018-03-15">
  ## Windows .NET SDK v3.5.1 released

  * Switched to exponential backoff when the SDK receives a rate limit or server error response.
  * Force support for TLS `v1.1` or higher when available to improve the security of connections to the Box API.
  * Perform modified retry on JWT auth for when the local clock and the Box Server clock are not aligned as well as if the JWT ID has already been consumed.
  * Made `name` parameter optional on `RestoreTrashedAsync()`.

  [`nuget.org/packages/Box.V2/3.5.1`](https://www.nuget.org/packages/Box.V2/3.5.1)
  [`nuget.org/packages/Box.V2.Core/3.5.1`](https://www.nuget.org/packages/Box.V2.Core/3.5.1)
</Update>

<Update label="2018-03-13">
  ## Update to Box Annotations

  Due to performance issues reported by some users, the update has been rolled
  back to prevent critical business applications from getting impacted. Drawing
  Annotations and Point Annotations mode features have now been turned off. We do
  not have an ETA for performance fixes or when these features will be
  re-enabled. We sincerely apologize for the inconvenience.

  Users who used the Drawing Annotations capability while it was available will
  still be able to access their annotations once the feature Edit. Documentation
  is re-enabled. Until then, the said annotations will be stored in our
  application data store but won’t be exposed via the viewers.
</Update>

<Update label="2018-03-12">
  ## Java SDK v2.15.0 released

  1. Allow retrieving Collaboration fields ([#570](https://github.com/box/box-java-sdk/pull/570))
  2. Implement Get Metadata Template by ID ([#568](https://github.com/box/box-java-sdk/pull/568))
</Update>

<Update label="2018-03-05">
  ## Update to Box Annotations

  We will be introducing two enhancements to the annotations features available
  via the Box API that your customer uses in their custom application. The
  updates are as follows:

  * **Point Annotations mode**: We are enhancing point annotations by introducing
    Point Annotations mode. This allows users to expediently add annotations on a
    document without having to re-select the point annotation icon after each
    annotation. [here](/guides/embed/ui-elements).
  * **Drawing Annotations via Expiring Embed**: We launched Drawing Annotations
    in November of 2017. This provided end users the ability to free-form draw on
    their touch-enabled devices using touch or a stylus. We are excited to share
    that we're making Drawing Annotations Full release announcement is available
    via the Expiring Embed. Users using annotations via the Get Embed Link API will
    now have a whole new way to express themselves via Box Preview.
</Update>

<Update label="2018-03-01">
  ## Java SDK v2.14.1 released

  1. Add randomization to exponential backoff ([#565](https://github.com/box/box-java-sdk/pull/565))
  2. Force TLS version 1.1 or greater when supported ([#548](https://github.com/box/box-java-sdk/pull/548))
  3. Delay successive API calls by `EventStream` ([#564](https://github.com/box/box-java-sdk/pull/564))
</Update>

<Update label="2018-03-29">
  ## Breaking change to Metadata APIs

  On March 29, 2018, we will introduce a new data type (array of strings) in the
  response body of the Metadata API endpoints. We are making this change because
  we are adding a new field type to metadata templates in Box called `multiSelect`.
  This new field type represents a checkbox type multiple selection of values
  when creating template instances on files or folders. The selected options for
  this field type are stored in an array of strings, where each string in the
  array corresponds to the key of the chosen `multiSelect` option.

  An example metadata template JSON response body is shown below. The value for
  the key `audience1` shows an example of the new data type (array of strings) that
  we are introducing in this change.

  ```js theme={null}
  {
    "audience1": ["internal", "internalEng"],
    "documentType": "Q1 plans",
    "competitiveDocument": "no",
    "status": "active",
    "author": "Jones",
    "currentState": "proposal",
    "$type": "marketingCollateral-d086c908-2498-4d3e-8a1f-01e82bfc2abe",
    "$parent": "file_5010739061",
    "$id": "2094c584-68e1-475c-a581-534a4609594e",
    "$version": 0,
    "$typeVersion": 0,
    "$template": "marketingCollateral",
    "$scope": "enterprise_12345"
  }
  ```
</Update>

<Update label="2018-02-15">
  ## Java SDK v2.14.0 released

  ## New Features, Enhancements, and Bug Fixes

  1. fixes missing `can_view_path` property on collaboration object ([#560](https://github.com/box/box-java-sdk/pull/560))
  2. Add missing methods and documentation ([#559](https://github.com/box/box-java-sdk/pull/559))
  3. Add support for setting tags on items ([#554](https://github.com/box/box-java-sdk/pull/554))
</Update>

<Update label="2018-02-08">
  ## Java SDK v2.13.0 released

  * Handle metadata values better ([#553](https://github.com/box/box-java-sdk/pull/553))
</Update>

<Update label="2018-02-01">
  ## Java SDK v2.12.0 released

  1. Fix collaboration notify parameter ([#545](https://github.com/box/box-java-sdk/pull/545))
  2. Add OAuth 2.0 token creation event type ([#533](https://github.com/box/box-java-sdk/pull/533))
  3. Implement invite user to enterprise ([#504](https://github.com/box/box-java-sdk/pull/504))
  4. Switch to `X-Box-UA` header for analytics ([#536](https://github.com/box/box-java-sdk/pull/536))
  5. Reduce Large File Upload memory usage ([#543](https://github.com/box/box-java-sdk/pull/543))
</Update>

<Update label="2018-01-31">
  ## Windows .NET SDK v3.4.2 released

  * Updated Box SDK Version in `NuSpec` file to fix dependency issues for `Box V2` and `Box V2.Core`.

  [`nuget.org/packages/Box.V2/3.4.2`](https://www.nuget.org/packages/Box.V2/3.4.2)
  [`nuget.org/packages/Box.V2.Core/3.4.2`](https://www.nuget.org/packages/Box.V2.Core/3.4.2)
</Update>

<Update label="2018-01-25">
  ## Java SDK v2.11.0 released

  1. Fix chunked upload for files > 2GB ([#531](https://github.com/box/box-java-sdk/pull/531))
  2. Add updated file version upload endpoint and deprecate old method ([#524](https://github.com/box/box-java-sdk/pull/524))
  3. Perform modified retry on JWT auth to avoid common JWT errors
</Update>

<Update label="2018-01-12">
  ## Java SDK v2.10.0 released

  * Add optional `is_confirmed` parameter for adding user email alias ([#499](https://github.com/box/box-java-sdk/pull/499))
  * Add support for token revocation ([#510](https://github.com/box/box-java-sdk/pull/510))
  * Metadata template delete ([#512](https://github.com/box/box-java-sdk/pull/512))
</Update>

<Update label="2018-01-10">
  ## Windows .NET SDK v3.4.1 released

  * Added support for [Allowed Collaboration Domains](https://developer.box.com/reference/resources/collaboration-allowlist-entry/)
  * Added Event Type enum
  * Fixed deserialization issue with `BoxRepresentationStatus`

  [`nuget.org/packages/Box.V2/3.4.1`](https://www.nuget.org/packages/Box.V2/3.4.1)
  [`nuget.org/packages/Box.V2.Core/3.4.1`](https://www.nuget.org/packages/Box.V2.Core/3.4.1)
</Update>

<Update label="2018-01-04">
  ## Java SDK v2.9.0 released

  1. Search `readme` update ([#506](https://github.com/box/box-java-sdk/pull/506))
  2. Add option to pass file `SHA-1` hash for upload integrity ([#502](https://github.com/box/box-java-sdk/pull/502))
  3. Events log limit ([#507](https://github.com/box/box-java-sdk/pull/507))
  4. Terms of Service ([#484](https://github.com/box/box-java-sdk/pull/484))
  5. Change `wiremock` port ([#505](https://github.com/box/box-java-sdk/pull/505))
  6. Delete redundant `response.disconnect()` from `moveFolderToUser()` ([#485](https://github.com/box/box-java-sdk/pull/485))
  7. Events `readme` patch ([#503](https://github.com/box/box-java-sdk/pull/503))
  8. Add missing webhook triggers to enum ([#497](https://github.com/box/box-java-sdk/pull/497))
  9. Fix `MetadataTemplate.updateMetadataTemplate()` type error ([#498](https://github.com/box/box-java-sdk/pull/498))
  10. Add missing event types to enum ([#500](https://github.com/box/box-java-sdk/pull/500))
  11. Add `modified_at` timestamp to `BoxComment.Info`([#501](https://github.com/box/box-java-sdk/pull/501))
  12. Collaboration whitelists ([#492](https://github.com/box/box-java-sdk/pull/492))
  13. Trash empty body patch ([#495](https://github.com/box/box-java-sdk/pull/495))
  14. Adding support for indefinite Box file locking by allowing null expiration ([#494](https://github.com/box/box-java-sdk/pull/494))
  15. Additional test in response for Batch API ([#474](https://github.com/box/box-java-sdk/pull/474))
  16. Fixing `BoxDeveloperEditionAPIConnection - decryptPrivateKey() - PEMParser returns PrivateKeyInfo already - Invalid cast` [#470](https://github.com/box/box-java-sdk/pull/470) ([#471](https://github.com/box/box-java-sdk/pull/471))
</Update>


# 2019
Source: https://developer.box.com/changelog/2019

Box Platform changelog: API, SDK, and product updates from 2019.

<Update label="2019-12-30">
  ## EOL of Classic Relay API Endpoints

  As previously communicated on October 18 2019, Classic Relay API
  endpoints are officially at an end of life state as of today.

  The following endpoints are affected by this EOL and will now start responding
  with error responses in applications making requests to them:

  * Get list of published Relay Classic templates.
  * Get list of Relay Classic workflows.
  * Launch a Relay Classic workflow.

  For any application encountering these error responses, please remove all calls
  to the Relay Classic APIs listed above.
</Update>

<Update label="2019-12-20">
  ## Java SDK v2.43.0 released

  1. Throw exceptions for `setMetadata` on Files and Folders for non 409 errors ([#762](https://github.com/box/box-java-sdk/pull/762))
</Update>

<Update label="2019-12-17" description="Java SDK v2.42.0 released">
  ## New Features and Enhancements

  1. `SDK-1168` Metadata Query ([#760](https://github.com/box/box-java-sdk/pull/760))
  2. Add marker based pagination for get users methods ([#759](https://github.com/box/box-java-sdk/pull/759))
</Update>

<Update label="2019-12-06" description="Windows .NET SDK v3.21.0 released">
  ## New Features, Enhancements, and Bug Fixes

  See [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3210) for details
  Commits: [`v3.20.0...v3.21.0`](https://github.com/box/box-windows-sdk-v2/compare/`v3.20.0...v3.21.0`)

  [`nuget.org/packages/Box.V2/3.21.0`](https://www.nuget.org/packages/Box.V2/3.21.0)
  [`nuget.org/packages/Box.V2.Core/3.21.0`](https://www.nuget.org/packages/Box.V2.Core/3.21.0)
</Update>

<Update label="2019-12-05">
  ## Marker-based Pagination Support for Users API

  The [Users API](/reference/get-users) now supports [marker-based
  pagination](/guides/api-calls/pagination/marker-based). Marker-based pagination is
  an alternative to regular offset-based pagination and provides an alternative
  way to get users for enterprises with a large volume of users.
</Update>

<Update label="2019-12-03" description="Preview SDK v2.29.0 released">
  ## New Features and Enhancements

  Version `2.29.0` of the Preview SDK has been released. New JavaScript and CSS
  Preview files have been made available. To adopt new changes, please see the
  [UI Elements manual installation](/guides/embed/ui-elements/installation/#manual-installation) links for Content
  Preview.

  Please see the `v2.29.0` [release notes](https://github.com/box/box-content-preview/releases/tag/v2.29.0) for a list
  of all feature changes.
</Update>

<Update label="2019-11-26">
  ## Box UI elements v11.0.2 released

  ## [11.0.2](https://github.com/box/box-ui-elements/compare/v11.0.1...v11.0.2) (2019-11-26)

  ### Bug Fixes

  * **build:** outdated release package ([`991ee17`](https://github.com/box/box-ui-elements/commit/991ee17))
</Update>

<Update label="2019-11-25">
  ## Elements v11.0 Released

  Box UI Elements version 11.0 has been released. This update includes three
  major new feature enhancements:

  * Content Explorer Grid View.
  * New Tasks Experience within the Preview Sidebar.
  * Visual Versions for the Preview Sidebar.

  Updated JavaScript and CSS files links for this release are available within
  the [UI Elements manual installation instructions](/guides/embed/ui-elements/installation/#manual-installation).

  For full information on changes in this release please see the following
  resources:

  * [Release notes](https://github.com/box/box-ui-elements/releases/tag/v11.0.0)
  * [Announcement blog post](https://medium.com/box-developer-blog/announcing-elements-11-88ee900125fd)
</Update>

<Update label="2019-11-21" description="Node SDK v1.30.0 released">
  ## New Features and Enhancements

  * Deprecated Batch API methods ([#433](https://github.com/box/box-node-sdk/pull/433)) [`b06f404`](https://github.com/box/box-node-sdk/commit/b06f404)
  * Added support for [token exchange](https://github.com/box/box-node-sdk/blob/v1.30.0/lib/box-client.js#L495) using shared links ([#398](https://github.com/box/box-node-sdk/pull/398)) [`76aa1cf`](https://github.com/box/box-node-sdk/commit/76aa1cf)

  [`v1.29.1...v1.30.0`](https://github.com/box/box-node-sdk/compare/`v1.29.1...v1.30.0`)
</Update>

<Update label="2019-11-20" description="Preview SDK v2.26.0 released">
  ## New Features and Enhancements

  Version `2.26.0` of the Preview SDK has been released. New JavaScript and CSS
  Preview files have been made available. To adopt new changes, please see the
  [UI Elements manual installation](/guides/embed/ui-elements/installation/#manual-installation) links for Content
  Preview.

  Please see the `v2.26.0` [release notes](https://github.com/box/box-content-preview/releases/tag/v2.26.0) for a list
  of all feature changes.
</Update>

<Update label="2019-11-18">
  ## New iOS SDK now available

  A new major release of the iOS SDK has been released and is now generally
  available. The new SDK includes a number of major revisions:

  * Fully rebuilt using Swift.
  * Support for Cocoapods, Carthage, and the Swift Package Manager.
  * SDK now maintains full API feature parity.

  See the [release blog post](https://medium.com/box-developer-blog/the-new-box-ios-sdk-now-available-baf624b289b4) for more information.
</Update>

<Update label="2019-11-09">
  ## Box UI elements v11.0.0 released

  ## [11.0.0](https://github.com/box/box-ui-elements/compare/v10.2.0...v11.0.0) (2019-11-09)

  ### Bug Fixes

  * **`activity-feed`:** fix long user names in tasks/comments in Edge ([#1604](https://github.com/box/box-ui-elements/issues/1604)) ([`572e4d7`](https://github.com/box/box-ui-elements/commit/572e4d7))
  * **`activity-feed`:** Fix version ordering in Activity Feed ([#1272](https://github.com/box/box-ui-elements/issues/1272)) ([`533c112`](https://github.com/box/box-ui-elements/commit/533c112))
  * **`activity-feed`:** refactor inline error for feed items and empty state ([#1697](https://github.com/box/box-ui-elements/issues/1697)) ([`2702367`](https://github.com/box/box-ui-elements/commit/2702367))
  * **`annotation`:** Fix header by adding selector used by box-annotations ([#1637](https://github.com/box/box-ui-elements/issues/1637)) ([`9302486`](https://github.com/box/box-ui-elements/commit/9302486))
  * **`app-activity`:** Remove underscores from resin feature name ([#1456](https://github.com/box/box-ui-elements/issues/1456)) ([`b7c21e7`](https://github.com/box/box-ui-elements/commit/b7c21e7))
  * **`app-activity`:** Update app activity to match comment/task ([#1449](https://github.com/box/box-ui-elements/issues/1449)) ([`b58aa2f`](https://github.com/box/box-ui-elements/commit/b58aa2f))
  * **`arrow-stepper`:** Fix arrow stepper in KeyBinding component ([#1654](https://github.com/box/box-ui-elements/issues/1654)) ([`a05b015`](https://github.com/box/box-ui-elements/commit/a05b015))
  * **`avatar`:** fix avatar initials v-alignment ([#1311](https://github.com/box/box-ui-elements/issues/1311)) ([`23e6d5f`](https://github.com/box/box-ui-elements/commit/23e6d5f))
  * **`avatar`:** Fix avatar resolution in activity sidebar ([#1243](https://github.com/box/box-ui-elements/issues/1243)) ([`88a5f1c`](https://github.com/box/box-ui-elements/commit/88a5f1c))
  * **`avatar`:** use derived state instead of effect for URL change ([#1643](https://github.com/box/box-ui-elements/issues/1643)) ([`f89c138`](https://github.com/box/box-ui-elements/commit/f89c138))
  * **`bdl`:** Add SCSS check for color variable name ([#1514](https://github.com/box/box-ui-elements/issues/1514)) ([`a4f446f`](https://github.com/box/box-ui-elements/commit/a4f446f))
  * **`bdl`:** adjust font weights to match normal and bold `lato` ([#1517](https://github.com/box/box-ui-elements/issues/1517)) ([`35a4070`](https://github.com/box/box-ui-elements/commit/35a4070))
  * **`beta-feedback`:** update `aria-labelledby` attribute name ([#1249](https://github.com/box/box-ui-elements/issues/1249)) ([`c164aec`](https://github.com/box/box-ui-elements/commit/c164aec))
  * **`breadcrumb`:** add missing import ([#1657](https://github.com/box/box-ui-elements/issues/1657)) ([`fec4735`](https://github.com/box/box-ui-elements/commit/fec4735))
  * **`button`:** remove horizontal margin from buttons ([#1362](https://github.com/box/box-ui-elements/issues/1362)) ([`a6989a0`](https://github.com/box/box-ui-elements/commit/a6989a0))
  * **`button`:** revert remove horizontal margin from buttons ([#1362](https://github.com/box/box-ui-elements/issues/1362)) ([#1400](https://github.com/box/box-ui-elements/issues/1400)) ([`3ac424c`](https://github.com/box/box-ui-elements/commit/3ac424c))
  * **`classification`:** badge should not have a `tabindex` ([#1622](https://github.com/box/box-ui-elements/issues/1622)) ([`4ab0c20`](https://github.com/box/box-ui-elements/commit/4ab0c20))
  * **`classification`:** Classification badge UX tweaks ([#1378](https://github.com/box/box-ui-elements/issues/1378)) ([`fa82a8d`](https://github.com/box/box-ui-elements/commit/fa82a8d))
  * **`classification`:** classification tooltip not showing in IE11 ([#1710](https://github.com/box/box-ui-elements/issues/1710)) ([`d08b53c`](https://github.com/box/box-ui-elements/commit/d08b53c))
  * **`classification`:** flow definitions for `onclick` ([#1712](https://github.com/box/box-ui-elements/issues/1712)) ([`9e620ce`](https://github.com/box/box-ui-elements/commit/9e620ce))
  * **`classification`:** Restoring classification badge icons ([#1390](https://github.com/box/box-ui-elements/issues/1390)) ([`5db4b3e`](https://github.com/box/box-ui-elements/commit/5db4b3e))
  * **`collaborator-avatars`:** add keyboard accessibility ([#1680](https://github.com/box/box-ui-elements/issues/1680)) ([`baefaed`](https://github.com/box/box-ui-elements/commit/baefaed))
  * **`collapsible`:** should be pure component ([#1407](https://github.com/box/box-ui-elements/issues/1407)) ([`5e32c80`](https://github.com/box/box-ui-elements/commit/5e32c80))
  * **`comment`:** Add height to comment area to support multiple mentions ([#1474](https://github.com/box/box-ui-elements/issues/1474)) ([`e270131`](https://github.com/box/box-ui-elements/commit/e270131))
  * **`comment`:** padding and `a11y` adjustments for comment UI ([#1358](https://github.com/box/box-ui-elements/issues/1358)) ([`927a34a`](https://github.com/box/box-ui-elements/commit/927a34a))
  * **`comment`:** remove redundant `aria-label` ([#1291](https://github.com/box/box-ui-elements/issues/1291)) ([`ef48f88`](https://github.com/box/box-ui-elements/commit/ef48f88))
  * **`comment`:** use overlay z-index for confirmation dialog ([#1270](https://github.com/box/box-ui-elements/issues/1270)) ([`bcf2852`](https://github.com/box/box-ui-elements/commit/bcf2852))
  * **`comments`:** format existing mentions in editor ([#1469](https://github.com/box/box-ui-elements/issues/1469)) ([`6b82510`](https://github.com/box/box-ui-elements/commit/6b82510))
  * **`constants`:** explicit type import ([#1584](https://github.com/box/box-ui-elements/issues/1584)) ([`7d38fb8`](https://github.com/box/box-ui-elements/commit/7d38fb8))
  * **`content-explorer`:** `ContentExplorer` and `ContentPicker` can handle
    sharing web links now ([#1515](https://github.com/box/box-ui-elements/issues/1515)) ([`55edef7`](https://github.com/box/box-ui-elements/commit/55edef7))
  * **`content-explorer`:** `MDVGridView` import fixes ([#1333](https://github.com/box/box-ui-elements/issues/1333)) ([`9740342`](https://github.com/box/box-ui-elements/commit/9740342))
  * **`content-explorer`:** rows no longer stuck after closing modal ([#1245](https://github.com/box/box-ui-elements/issues/1245)) ([`d7f53ff`](https://github.com/box/box-ui-elements/commit/d7f53ff))
  * **`content-preview`:** remove deeplink path upon navigation ([#1665](https://github.com/box/box-ui-elements/issues/1665)) ([`84b4ea4`](https://github.com/box/box-ui-elements/commit/84b4ea4))
  * **`content-uploader`:** Disable cancel button when 100% is reached ([#1511](https://github.com/box/box-ui-elements/issues/1511)) ([`a6de1b0`](https://github.com/box/box-ui-elements/commit/a6de1b0))
  * **`content-uploader`:** Fix cancelling task triggers the others to start ([#1653](https://github.com/box/box-ui-elements/issues/1653)) ([`f35b2ea`](https://github.com/box/box-ui-elements/commit/f35b2ea))
  * **`content-uploader`:** Fix duplicate files upload at the same time ([#1652](https://github.com/box/box-ui-elements/issues/1652)) ([`6faed59`](https://github.com/box/box-ui-elements/commit/6faed59))
  * **`datetime`:** add missing support for times w/o ms ([#1191](https://github.com/box/box-ui-elements/issues/1191)) ([`19f3703`](https://github.com/box/box-ui-elements/commit/19f3703))
  * **`deps`:** downgrade `axios` peer dependency ([#1329](https://github.com/box/box-ui-elements/issues/1329)) ([`d1a1bd9`](https://github.com/box/box-ui-elements/commit/d1a1bd9))
  * **`examples`:** change colors to the current box design language ([#1281](https://github.com/box/box-ui-elements/issues/1281)) ([`94869ad`](https://github.com/box/box-ui-elements/commit/94869ad))
  * **`explorer`:** fetch shared link on demand ([#1479](https://github.com/box/box-ui-elements/issues/1479)) ([`2d29628`](https://github.com/box/box-ui-elements/commit/2d29628))
  * **`feed`:** inline error for deeplinking feed items ([#1655](https://github.com/box/box-ui-elements/issues/1655)) ([`e2be3bd`](https://github.com/box/box-ui-elements/commit/e2be3bd))
  * **`feed`:** Task assignee names not truncating IE11 ([#1694](https://github.com/box/box-ui-elements/issues/1694)) ([`a20e610`](https://github.com/box/box-ui-elements/commit/a20e610))
  * **`floatfield`:** always allow trailing `.` for float field ([#1178](https://github.com/box/box-ui-elements/issues/1178)) ([`61d4e3d`](https://github.com/box/box-ui-elements/commit/61d4e3d))
  * **`footer-indicator`:** move tooltip to appear above footer indicator ([`bf7782c`](https://github.com/box/box-ui-elements/commit/bf7782c))
  * **`header-flyout`:** Constraint to window to fix IE11 scroll bug ([#1310](https://github.com/box/box-ui-elements/issues/1310)) ([`f8bb323`](https://github.com/box/box-ui-elements/commit/f8bb323))
  * **`i18n`:** change "accepted" copy to "approved" ([#1214](https://github.com/box/box-ui-elements/issues/1214)) ([`674bf45`](https://github.com/box/box-ui-elements/commit/674bf45))
  * **`i18n`:** Fix bug where messages starting with HTML cause an exception ([#1490](https://github.com/box/box-ui-elements/issues/1490)) ([`73d95b9`](https://github.com/box/box-ui-elements/commit/73d95b9))
  * **`i18n`:** `Param` and `Plural` should not be in the `styleguide.conf` ([#1197](https://github.com/box/box-ui-elements/issues/1197)) ([`2d34ad4`](https://github.com/box/box-ui-elements/commit/2d34ad4))
  * **`i18n`:** use plural format for task assignee message ([#1345](https://github.com/box/box-ui-elements/issues/1345)) ([`10d6b76`](https://github.com/box/box-ui-elements/commit/10d6b76))
  * **`icons`:** fill in background for globe icon ([#1226](https://github.com/box/box-ui-elements/issues/1226)) ([`c91d320`](https://github.com/box/box-ui-elements/commit/c91d320))
  * **`icons`:** fix collections icons for left navigation usability ([#1238](https://github.com/box/box-ui-elements/issues/1238)) ([`9e91115`](https://github.com/box/box-ui-elements/commit/9e91115))
  * **`icons`:** give collections Icons SUIT classNames ([#1242](https://github.com/box/box-ui-elements/issues/1242)) ([`3b62245`](https://github.com/box/box-ui-elements/commit/3b62245))
  * **`icons`:** update retry and public icon ([#1297](https://github.com/box/box-ui-elements/issues/1297)) ([`bfa075a`](https://github.com/box/box-ui-elements/commit/bfa075a))
  * **`icons`:** update trash, move/copy, add, download, upload, collections ([#1702](https://github.com/box/box-ui-elements/issues/1702)) ([`b126ecb`](https://github.com/box/box-ui-elements/commit/b126ecb))
  * **`icons`:** updating add icon style and adding hidden eye icon ([#1266](https://github.com/box/box-ui-elements/issues/1266)) ([`b47e22e`](https://github.com/box/box-ui-elements/commit/b47e22e))
  * **`iconworkflow`:** make background rectangle same as `viewBox` ([#1241](https://github.com/box/box-ui-elements/issues/1241)) ([`9e07f2e`](https://github.com/box/box-ui-elements/commit/9e07f2e))
  * **`inlinenotice`:** update to box design standard ([#1576](https://github.com/box/box-ui-elements/issues/1576)) ([`a814657`](https://github.com/box/box-ui-elements/commit/a814657))
  * **`item-properties`:** Add `aria-labelledby` to description textarea ([#1229](https://github.com/box/box-ui-elements/issues/1229)) ([`05d86b1`](https://github.com/box/box-ui-elements/commit/05d86b1))
  * **`left-sidebar`:** add key to drop wrapper for links ([#1299](https://github.com/box/box-ui-elements/issues/1299)) ([`9c78135`](https://github.com/box/box-ui-elements/commit/9c78135))
  * **`left-sidebar`:** Adjust margins for loading indicator ([#1545](https://github.com/box/box-ui-elements/issues/1545)) ([`6ba65c6`](https://github.com/box/box-ui-elements/commit/6ba65c6))
  * **`left-sidebar`:** hide toggle icon on medium screen size ([#1344](https://github.com/box/box-ui-elements/issues/1344)) ([`716fe01`](https://github.com/box/box-ui-elements/commit/716fe01))
  * **`media`:** increase specificity of Media-button CSS to avoid `.btn-plain` ([#1463](https://github.com/box/box-ui-elements/issues/1463)) ([`943638d`](https://github.com/box/box-ui-elements/commit/943638d))
  * **`mention-selector`:** Fix `hasReceivedFirstInteraction` logic ([#1434](https://github.com/box/box-ui-elements/issues/1434)) ([`afd94fa`](https://github.com/box/box-ui-elements/commit/afd94fa))
  * **`menu`:** Fix padding for menu item buttons ([#1446](https://github.com/box/box-ui-elements/issues/1446)) ([`5baeb5b`](https://github.com/box/box-ui-elements/commit/5baeb5b))
  * **`menu`:** Menu should only autofocus on mount if visible ([#1175](https://github.com/box/box-ui-elements/issues/1175)) ([`2ba8a1d`](https://github.com/box/box-ui-elements/commit/2ba8a1d))
  * **`metadata`:** Show autocomplete for metadata input fields ([#1629](https://github.com/box/box-ui-elements/issues/1629)) ([`85995cd`](https://github.com/box/box-ui-elements/commit/85995cd))
  * **`metadata`:** template dropdown scrollbar issue in safari ([#1192](https://github.com/box/box-ui-elements/issues/1192)) ([`1dc0d99`](https://github.com/box/box-ui-elements/commit/1dc0d99))
  * **`metadata-sidebar`:** bind `onApiError` properly ([#1713](https://github.com/box/box-ui-elements/issues/1713)) ([`50b72f2`](https://github.com/box/box-ui-elements/commit/50b72f2))
  * **`modal`:** move close button after header for better screen reader `a11y` ([#1684](https://github.com/box/box-ui-elements/issues/1684)) ([`29a1220`](https://github.com/box/box-ui-elements/commit/29a1220))
  * **`nav-sidebar`:** reduce size of toggle button to fix focus outline ([#1305](https://github.com/box/box-ui-elements/issues/1305)) ([`9a14ae7`](https://github.com/box/box-ui-elements/commit/9a14ae7))
  * **`notifications`:** add accessibility attributes ([#1682](https://github.com/box/box-ui-elements/issues/1682)) ([`21af355`](https://github.com/box/box-ui-elements/commit/21af355))
  * **`open-with`:** better error messaging ([#1489](https://github.com/box/box-ui-elements/issues/1489)) ([`d3d98a5`](https://github.com/box/box-ui-elements/commit/d3d98a5))
  * **`pill-selector`:** Allow copy pasting line separated values ([#1350](https://github.com/box/box-ui-elements/issues/1350)) ([`7933932`](https://github.com/box/box-ui-elements/commit/7933932))
  * **`pill-selector`:** expose `onInput` to catch input ([#1450](https://github.com/box/box-ui-elements/issues/1450)) ([`48d22a4`](https://github.com/box/box-ui-elements/commit/48d22a4))
  * **`pill-selector`:** UX tweaks ([#1315](https://github.com/box/box-ui-elements/issues/1315)) ([`e4fdf58`](https://github.com/box/box-ui-elements/commit/e4fdf58))
  * **`pill-selector-dropdown`:** disable pills when `PillSelector` is turned off ([#1357](https://github.com/box/box-ui-elements/issues/1357)) ([`2bf496e`](https://github.com/box/box-ui-elements/commit/2bf496e))
  * **`pill-selector-dropdown`:** fix aria attributes ([#1681](https://github.com/box/box-ui-elements/issues/1681)) ([`1e0d1ab`](https://github.com/box/box-ui-elements/commit/1e0d1ab))
  * **`pill-selector-dropdown`:** Fix for pills getting removed on click ([#1367](https://github.com/box/box-ui-elements/issues/1367)) ([`d67fcfe`](https://github.com/box/box-ui-elements/commit/d67fcfe))
  * **`pills`:** Fix vertical centering of pill selector input text ([#1364](https://github.com/box/box-ui-elements/issues/1364)) ([`d47c69c`](https://github.com/box/box-ui-elements/commit/d47c69c))
  * **`pillselectordropdown`:** support paste from context menu ([#1597](https://github.com/box/box-ui-elements/issues/1597)) ([`d16b0da`](https://github.com/box/box-ui-elements/commit/d16b0da))
  * **`preview`:** Clean up preview header styles and remove extra borders ([#1484](https://github.com/box/box-ui-elements/issues/1484)) ([`6c1a363`](https://github.com/box/box-ui-elements/commit/6c1a363))
  * **`quick-search`:** update border radius to follow BDL ([#1439](https://github.com/box/box-ui-elements/issues/1439)) ([`936f5e0`](https://github.com/box/box-ui-elements/commit/936f5e0))
  * **`radio-group`:** fix radio group by passing the value prop ([#1452](https://github.com/box/box-ui-elements/issues/1452)) ([`c0c05be`](https://github.com/box/box-ui-elements/commit/c0c05be))
  * **`radio-group`:** pass rest of props to radio input ([#1448](https://github.com/box/box-ui-elements/issues/1448)) ([`85ca38a`](https://github.com/box/box-ui-elements/commit/85ca38a))
  * **`scripts`:** Build and update all files prior to push ([#1415](https://github.com/box/box-ui-elements/issues/1415)) ([`e432c47`](https://github.com/box/box-ui-elements/commit/e432c47))
  * **`scroll-if-needed`:** fix scroll-if-needed on selector dropdown ([#1280](https://github.com/box/box-ui-elements/issues/1280)) ([`3776dc8`](https://github.com/box/box-ui-elements/commit/3776dc8))
  * **`search`:** Remove rounded corners for `ContentExplorer` search ([#1478](https://github.com/box/box-ui-elements/issues/1478)) ([`7d9100b`](https://github.com/box/box-ui-elements/commit/7d9100b))
  * **`security`:** Upgrade `axios` to address security vulnerability ([#1228](https://github.com/box/box-ui-elements/issues/1228)) ([`db26743`](https://github.com/box/box-ui-elements/commit/db26743))
  * **`security-badge`:** Fixing `SecurityBadge` flow type ([#1664](https://github.com/box/box-ui-elements/issues/1664)) ([`ae23f01`](https://github.com/box/box-ui-elements/commit/ae23f01))
  * **`select-field`:** Enable arrow scrolling in select fields ([#1671](https://github.com/box/box-ui-elements/issues/1671)) ([`9f040f2`](https://github.com/box/box-ui-elements/commit/9f040f2))
  * **`sidebar`:** Add flex-shrink 0 to comment input ([#1359](https://github.com/box/box-ui-elements/issues/1359)) ([`cd840f4`](https://github.com/box/box-ui-elements/commit/cd840f4))
  * **`sidebar`:** add markup and accessibility to tab list ([#1563](https://github.com/box/box-ui-elements/issues/1563)) ([`f90a0d7`](https://github.com/box/box-ui-elements/commit/f90a0d7))
  * **`sidebar`:** Fix deeplinking for version history sidebar ([#1649](https://github.com/box/box-ui-elements/issues/1649)) ([`e85e57a`](https://github.com/box/box-ui-elements/commit/e85e57a))
  * **`sidebar`:** Fix sidebar not auto-opening for large viewports ([#1508](https://github.com/box/box-ui-elements/issues/1508)) ([`dac39ee`](https://github.com/box/box-ui-elements/commit/dac39ee))
  * **`sidebar`:** Limit maximum height of additional tabs in sidebar navigation ([#1557](https://github.com/box/box-ui-elements/issues/1557)) ([`e7f953e`](https://github.com/box/box-ui-elements/commit/e7f953e))
  * **`sidebar`:** More semantically accessible tabs ([#1236](https://github.com/box/box-ui-elements/issues/1236)) ([`eb398fc`](https://github.com/box/box-ui-elements/commit/eb398fc))
  * **`sidebar`:** padding on item properties versions ([#1263](https://github.com/box/box-ui-elements/issues/1263)) ([`853e106`](https://github.com/box/box-ui-elements/commit/853e106))
  * **`sidebar`:** removing unwanted parenthesis in empty state ([#1645](https://github.com/box/box-ui-elements/issues/1645)) ([`824f390`](https://github.com/box/box-ui-elements/commit/824f390))
  * **`sidebar`:** Set contaminated state if the sidebar was forced open ([#1366](https://github.com/box/box-ui-elements/issues/1366)) ([`e71409c`](https://github.com/box/box-ui-elements/commit/e71409c))
  * **`sidebar`:** Update `flexbox` for Activity Feed Container ([#1341](https://github.com/box/box-ui-elements/issues/1341)) ([`c5e07b1`](https://github.com/box/box-ui-elements/commit/c5e07b1))
  * **`subheader`:** Add logic around grid view ([#1659](https://github.com/box/box-ui-elements/issues/1659)) ([`7a53050`](https://github.com/box/box-ui-elements/commit/7a53050))
  * **`task`:** string for task completed rule icon ([#1573](https://github.com/box/box-ui-elements/issues/1573)) ([`79c3f00`](https://github.com/box/box-ui-elements/commit/79c3f00))
  * **`task-form`:** clear task assignee autocomplete on form submit ([#1605](https://github.com/box/box-ui-elements/issues/1605)) ([`63efa10`](https://github.com/box/box-ui-elements/commit/63efa10))
  * **`task-form`:** disallow text input in date picker ([#1540](https://github.com/box/box-ui-elements/issues/1540)) ([`af49827`](https://github.com/box/box-ui-elements/commit/af49827))
  * **`task-form`:** don't disable task form submit button ([#1323](https://github.com/box/box-ui-elements/issues/1323)) ([`9a4137b`](https://github.com/box/box-ui-elements/commit/9a4137b))
  * **`task-form`:** Update error message when leaving not valued but required field ([#1353](https://github.com/box/box-ui-elements/issues/1353)) ([`be10f37`](https://github.com/box/box-ui-elements/commit/be10f37))
  * **`task-new`:** alignment fixes, CSS refactor ([#1312](https://github.com/box/box-ui-elements/issues/1312)) ([`411c3e9`](https://github.com/box/box-ui-elements/commit/411c3e9))
  * **`task-new`:** fix placement of task status checkmark ([#1321](https://github.com/box/box-ui-elements/issues/1321)) ([`9f554ff`](https://github.com/box/box-ui-elements/commit/9f554ff))
  * **`task-new`:** Minor visual tweak to add tasks menu ([#1334](https://github.com/box/box-ui-elements/issues/1334)) ([`95a3c73`](https://github.com/box/box-ui-elements/commit/95a3c73))
  * **`task-new`:** Minor visual tweaks to add tasks menu ([#1328](https://github.com/box/box-ui-elements/issues/1328)) ([`cf1acf1`](https://github.com/box/box-ui-elements/commit/cf1acf1))
  * **`tasks`:** add missing resin component ([#1513](https://github.com/box/box-ui-elements/issues/1513)) ([`00e9707`](https://github.com/box/box-ui-elements/commit/00e9707))
  * **`tasks`:** assignee input field interactions ([#1621](https://github.com/box/box-ui-elements/issues/1621)) ([`dc33967`](https://github.com/box/box-ui-elements/commit/dc33967))
  * **`tasks`:** comments menu does not appear on activity sidebar in preview ([#1250](https://github.com/box/box-ui-elements/issues/1250)) ([`be7bc2f`](https://github.com/box/box-ui-elements/commit/be7bc2f))
  * **`tasks`:** fix task issues ([#1189](https://github.com/box/box-ui-elements/issues/1189)) ([`630fd38`](https://github.com/box/box-ui-elements/commit/630fd38))
  * **`tasks`:** modal closing on resize ([#1603](https://github.com/box/box-ui-elements/issues/1603)) ([`2cbe014`](https://github.com/box/box-ui-elements/commit/2cbe014))
  * **`tasks`:** prevent resize of assignee avatar ([#1332](https://github.com/box/box-ui-elements/issues/1332)) ([`4e760f7`](https://github.com/box/box-ui-elements/commit/4e760f7))
  * **`tasks`:** Update copy for task type subtext ([#1627](https://github.com/box/box-ui-elements/issues/1627)) ([`c788770`](https://github.com/box/box-ui-elements/commit/c788770))
  * **`tasks_new`:** add missing resin component ([#1295](https://github.com/box/box-ui-elements/issues/1295)) ([`dbbf598`](https://github.com/box/box-ui-elements/commit/dbbf598))
  * **`tasks-new`:** Reset selector contacts on modal close ([#1301](https://github.com/box/box-ui-elements/issues/1301)) ([`f387a9b`](https://github.com/box/box-ui-elements/commit/f387a9b))
  * **`tasks-new`:** show "a prior collaborator" for deleted users ([#1313](https://github.com/box/box-ui-elements/issues/1313)) ([`c61fa77`](https://github.com/box/box-ui-elements/commit/c61fa77))
  * **`tasks-new`:** task actions are not updating ([#1302](https://github.com/box/box-ui-elements/issues/1302)) ([`2f88e96`](https://github.com/box/box-ui-elements/commit/2f88e96))
  * **`tasks-new`:** update documents and strings ([#1317](https://github.com/box/box-ui-elements/issues/1317)) ([`6560b23`](https://github.com/box/box-ui-elements/commit/6560b23))
  * **`template-dropdown`:** add `onMenuToggle` handler to `TemplateDropdown` ([#1318](https://github.com/box/box-ui-elements/issues/1318)) ([`2cdfcc4`](https://github.com/box/box-ui-elements/commit/2cdfcc4))
  * **`text-input`:** loses focus when tooltip toggles ([#1185](https://github.com/box/box-ui-elements/issues/1185)) ([`8a4c294`](https://github.com/box/box-ui-elements/commit/8a4c294))
  * **`tooltip`:** color contrast and layout fixes ([#1692](https://github.com/box/box-ui-elements/issues/1692)) ([`1c11770`](https://github.com/box/box-ui-elements/commit/1c11770))
  * **`unfied-share-modal`:** shared link access levels ([#1647](https://github.com/box/box-ui-elements/issues/1647)) ([`732a1dd`](https://github.com/box/box-ui-elements/commit/732a1dd))
  * **`unified-share-modal`:** add constraints to modal menus ([#1196](https://github.com/box/box-ui-elements/issues/1196)) ([`6501413`](https://github.com/box/box-ui-elements/commit/6501413))
  * **`unified-share-modal`:** classification in title ([#1453](https://github.com/box/box-ui-elements/issues/1453)) ([`4ce5a06`](https://github.com/box/box-ui-elements/commit/4ce5a06))
  * **`uploader`:** `MultiputUploads` stop hanging in IE11 ([#1283](https://github.com/box/box-ui-elements/issues/1283)) ([`c49e52f`](https://github.com/box/box-ui-elements/commit/c49e52f))
  * **`uploads`:** cancelling in-progress tasks does not start pending ones ([#1570](https://github.com/box/box-ui-elements/issues/1570)) ([`dbf115c`](https://github.com/box/box-ui-elements/commit/dbf115c))
  * **`uploads`:** Fix hanging on resuming uploads ([#1695](https://github.com/box/box-ui-elements/issues/1695)) ([`3da93c8`](https://github.com/box/box-ui-elements/commit/3da93c8))
  * **`uploads`:** Remove logic gate ([#1646](https://github.com/box/box-ui-elements/issues/1646)) ([`38d10e4`](https://github.com/box/box-ui-elements/commit/38d10e4))
  * **`uploads`:** reset item error after retry ([#1600](https://github.com/box/box-ui-elements/issues/1600)) ([`0218f10`](https://github.com/box/box-ui-elements/commit/0218f10))
  * **`uploads`:** resin for canceling uploads ([#1397](https://github.com/box/box-ui-elements/issues/1397)) ([`16311dc`](https://github.com/box/box-ui-elements/commit/16311dc))
  * **`user-link`:** allow wrapping of long user names ([#1602](https://github.com/box/box-ui-elements/issues/1602)) ([`bff49bb`](https://github.com/box/box-ui-elements/commit/bff49bb))
  * **`usm`:** "Link Settings" should not line wrap ([#1674](https://github.com/box/box-ui-elements/issues/1674)) ([`938c483`](https://github.com/box/box-ui-elements/commit/938c483))
  * **`usm`:** Add `itemTypedId` to `onPillCreate` ([#1320](https://github.com/box/box-ui-elements/issues/1320)) ([`c4149ea`](https://github.com/box/box-ui-elements/commit/c4149ea))
  * **`usm`:** Do not pass `itemTypedID` to `getContactsByEmail` ([#1354](https://github.com/box/box-ui-elements/issues/1354)) ([`e60b020`](https://github.com/box/box-ui-elements/commit/e60b020))
  * **`versions`:** Disable prior version preview for watermarked files ([#1405](https://github.com/box/box-ui-elements/issues/1405)) ([`9a527f2`](https://github.com/box/box-ui-elements/commit/9a527f2))
  * **`versions`:** Display date and name for most relevant version action ([#1568](https://github.com/box/box-ui-elements/issues/1568)) ([`b68eccd`](https://github.com/box/box-ui-elements/commit/b68eccd))
  * **`versions`:** Fix infinite load due to destroyed API factory ([#1347](https://github.com/box/box-ui-elements/issues/1347)) ([`95949e2`](https://github.com/box/box-ui-elements/commit/95949e2))
  * **`versions`:** Fix version groups collapsing prior months/years ([#1365](https://github.com/box/box-ui-elements/issues/1365)) ([`65d23b9`](https://github.com/box/box-ui-elements/commit/65d23b9))
  * **`versions`:** Improve experience for restored vs promoted versions ([#1631](https://github.com/box/box-ui-elements/issues/1631)) ([`25d0741`](https://github.com/box/box-ui-elements/commit/25d0741))
  * **`versions`:** Relax restrictions for watermarked files ([#1342](https://github.com/box/box-ui-elements/issues/1342)) ([`2487b42`](https://github.com/box/box-ui-elements/commit/2487b42))
  * **`versions`:** Reload the page when a version is promoted (temporary) ([#1395](https://github.com/box/box-ui-elements/issues/1395)) ([`de7e74e`](https://github.com/box/box-ui-elements/commit/de7e74e))
  * **`versions`:** Restrict actions and preview for watermarked files ([#1339](https://github.com/box/box-ui-elements/issues/1339)) ([`fcb390d`](https://github.com/box/box-ui-elements/commit/fcb390d))
  * **`versions`:** Restrict preview for watermarked files ([#1351](https://github.com/box/box-ui-elements/issues/1351)) ([`93b95c4`](https://github.com/box/box-ui-elements/commit/93b95c4))
  * **`versions`:** Retrieve and use file version permissions for actions ([#1193](https://github.com/box/box-ui-elements/issues/1193)) ([`9d7567e`](https://github.com/box/box-ui-elements/commit/9d7567e))
  * **`versions`:** Scroll version button into view if selected ([#1276](https://github.com/box/box-ui-elements/issues/1276)) ([`e0cd7e3`](https://github.com/box/box-ui-elements/commit/e0cd7e3))
  * **`versions`:** Show server errors without hiding version history ([#1275](https://github.com/box/box-ui-elements/issues/1275)) ([`ef3b2fd`](https://github.com/box/box-ui-elements/commit/ef3b2fd))
  * **`versions`:** Update version actions to avoid unnecessary buttons ([#1556](https://github.com/box/box-ui-elements/issues/1556)) ([`bc9672e`](https://github.com/box/box-ui-elements/commit/bc9672e))
  * **`versions`:** Update version sidebar to use latest retention schema ([#1662](https://github.com/box/box-ui-elements/issues/1662)) ([`fa66232`](https://github.com/box/box-ui-elements/commit/fa66232))
  * Adding `Accept-Language` header for `Xhr.js` ([#1368](https://github.com/box/box-ui-elements/issues/1368)) ([`361d73f`](https://github.com/box/box-ui-elements/commit/361d73f))
  * show tooltip on hover long text ([#1230](https://github.com/box/box-ui-elements/issues/1230)) ([`c41dd47`](https://github.com/box/box-ui-elements/commit/c41dd47))
  * slight adjust in check mark alignment ([#1678](https://github.com/box/box-ui-elements/issues/1678)) ([`cfd055b`](https://github.com/box/box-ui-elements/commit/cfd055b))
  * various form accessibility improvements ([#1688](https://github.com/box/box-ui-elements/issues/1688)) ([`150cbbe`](https://github.com/box/box-ui-elements/commit/150cbbe))
  * **`versions`:** Update versions restore call to match latest contract ([#1198](https://github.com/box/box-ui-elements/issues/1198)) ([`2e590d3`](https://github.com/box/box-ui-elements/commit/2e590d3))

  ### chore

  * **`deps`:** update `react` peer / development dependency ([#1606](https://github.com/box/box-ui-elements/issues/1606)) ([`1163db5`](https://github.com/box/box-ui-elements/commit/1163db5))
  * **`formik`:** upgrade to V2 ([#1698](https://github.com/box/box-ui-elements/issues/1698)) ([`6b9ded9`](https://github.com/box/box-ui-elements/commit/6b9ded9))

  ### Code Refactoring

  * Upgrade `react` and `react-dom` to `v16.8` and refactor Avatar ([#1171](https://github.com/box/box-ui-elements/issues/1171)) ([`7dd1bdf`](https://github.com/box/box-ui-elements/commit/7dd1bdf)), closes [#761](https://github.com/box/box-ui-elements/issues/761)
  * **`deps`:** Upgrade peer dependencies to latest working versions ([#1180](https://github.com/box/box-ui-elements/issues/1180)) ([`48d711e`](https://github.com/box/box-ui-elements/commit/48d711e))

  ### Features

  * **`activity-feed`:** add support for deeplinking tasks and comments ([#1623](https://github.com/box/box-ui-elements/issues/1623)) ([`52ecdcb`](https://github.com/box/box-ui-elements/commit/52ecdcb))
  * **`additional-tabs`:** gray out turned off apps ([#1503](https://github.com/box/box-ui-elements/issues/1503)) ([`132782d`](https://github.com/box/box-ui-elements/commit/132782d))
  * **`avatarinitials`:** move `backgroundColor` into SCSS ([#1585](https://github.com/box/box-ui-elements/issues/1585)) ([`781a246`](https://github.com/box/box-ui-elements/commit/781a246))
  * **`bdl`:** Add script for SCSS `bdl` scoping ([#1546](https://github.com/box/box-ui-elements/issues/1546)) ([`9bdc1e6`](https://github.com/box/box-ui-elements/commit/9bdc1e6))
  * **`classification`:** change icon for classify/classification action ([#1520](https://github.com/box/box-ui-elements/issues/1520)) ([`8eb68b3`](https://github.com/box/box-ui-elements/commit/8eb68b3))
  * **`classification`:** new badge and layout ([#1231](https://github.com/box/box-ui-elements/issues/1231)) ([`2336262`](https://github.com/box/box-ui-elements/commit/2336262))
  * **`classification`:** new section within the details sidebar ([#1237](https://github.com/box/box-ui-elements/issues/1237)) ([`90bf2f3`](https://github.com/box/box-ui-elements/commit/90bf2f3))
  * **`classification`:** remove classify from breadcrumbs ([#1549](https://github.com/box/box-ui-elements/issues/1549)) ([`adae46d`](https://github.com/box/box-ui-elements/commit/adae46d))
  * **`classification`:** updated UI for classification ([#1566](https://github.com/box/box-ui-elements/issues/1566)) ([`52e2b17`](https://github.com/box/box-ui-elements/commit/52e2b17))
  * **`comments`:** implement comment edit ([#1468](https://github.com/box/box-ui-elements/issues/1468)) ([`33dd037`](https://github.com/box/box-ui-elements/commit/33dd037))
  * **`content-explorer`:** Add ability to sort contents by size column ([#1239](https://github.com/box/box-ui-elements/issues/1239)) ([`b29b6bf`](https://github.com/box/box-ui-elements/commit/b29b6bf))
  * **`content-explorer`:** Add toggle button for grid view ([#1349](https://github.com/box/box-ui-elements/issues/1349)) ([`97a1d44`](https://github.com/box/box-ui-elements/commit/97a1d44))
  * **`content-explorer`:** Fetch thumbnails for search and recents ([#1475](https://github.com/box/box-ui-elements/issues/1475)) ([`1035afb`](https://github.com/box/box-ui-elements/commit/1035afb))
  * **`content-explorer`:** grid view slider ([#1482](https://github.com/box/box-ui-elements/issues/1482)) ([`ef4a7ee`](https://github.com/box/box-ui-elements/commit/ef4a7ee))
  * **`content-explorer`:** grid view styling ([#1464](https://github.com/box/box-ui-elements/issues/1464)) ([`f32b8ca`](https://github.com/box/box-ui-elements/commit/f32b8ca)), closes [#1409](https://github.com/box/box-ui-elements/issues/1409)
  * **`content-explorer`:** import files from `MDVGridView` ([#1294](https://github.com/box/box-ui-elements/issues/1294)) ([`a2e5bd9`](https://github.com/box/box-ui-elements/commit/a2e5bd9))
  * **`content-explorer`:** local storage for view mode preference ([#1476](https://github.com/box/box-ui-elements/issues/1476)) ([`803b0a0`](https://github.com/box/box-ui-elements/commit/803b0a0))
  * **`content-explorer`:** Remove feature flip for gallery view ([#1571](https://github.com/box/box-ui-elements/issues/1571)) ([`3e948b8`](https://github.com/box/box-ui-elements/commit/3e948b8))
  * **`content-explorer`:** show cards with thumbnails ([#1409](https://github.com/box/box-ui-elements/issues/1409)) ([`7bbc2e8`](https://github.com/box/box-ui-elements/commit/7bbc2e8))
  * **`content-explorer`:** Show grid with icons ([#1372](https://github.com/box/box-ui-elements/issues/1372)) ([`64a099e`](https://github.com/box/box-ui-elements/commit/64a099e))
  * **`content-picker`:** use radios for single select ([#1685](https://github.com/box/box-ui-elements/issues/1685)) ([`acc3395`](https://github.com/box/box-ui-elements/commit/acc3395))
  * **`content-sidebar`:** add task modal mode for edit/create ([#1257](https://github.com/box/box-ui-elements/issues/1257)) ([`0bdfc96`](https://github.com/box/box-ui-elements/commit/0bdfc96))
  * **`content-sidebar`:** programmatic refresh for sidebar panels ([#1561](https://github.com/box/box-ui-elements/issues/1561)) ([`2adbaef`](https://github.com/box/box-ui-elements/commit/2adbaef))
  * **`dropdown-menu`:** allow `esc` to propagate if dropdown is closed ([#1686](https://github.com/box/box-ui-elements/issues/1686)) ([`3d4d59e`](https://github.com/box/box-ui-elements/commit/3d4d59e))
  * **`features`:** Add background color on hover in metadata list view ([#1618](https://github.com/box/box-ui-elements/issues/1618)) ([`635808e`](https://github.com/box/box-ui-elements/commit/635808e))
  * **`features`:** Add new feature metadata-based-view ([#1519](https://github.com/box/box-ui-elements/issues/1519)) ([`faef59e`](https://github.com/box/box-ui-elements/commit/faef59e))
  * **`features`:** Show preview upon clicking the item name ([#1620](https://github.com/box/box-ui-elements/issues/1620)) ([`74e46b2`](https://github.com/box/box-ui-elements/commit/74e46b2))
  * **`ghost`:** create ghost state helper component ([#1498](https://github.com/box/box-ui-elements/issues/1498)) ([`73aadae`](https://github.com/box/box-ui-elements/commit/73aadae))
  * **`i18n`:** Implement the new `FormattedCompMessage` component ([#976](https://github.com/box/box-ui-elements/issues/976)) ([`31fdf12`](https://github.com/box/box-ui-elements/commit/31fdf12))
  * **`icon`:** create add users empty state icon ([#1638](https://github.com/box/box-ui-elements/issues/1638)) ([`33dfacb`](https://github.com/box/box-ui-elements/commit/33dfacb))
  * **`icon`:** create login and storage icon ([#1708](https://github.com/box/box-ui-elements/issues/1708)) ([`0115fb6`](https://github.com/box/box-ui-elements/commit/0115fb6))
  * **`icons`:** Add `CollectionItemLink` icon ([#1550](https://github.com/box/box-ui-elements/issues/1550)) ([`1558d36`](https://github.com/box/box-ui-elements/commit/1558d36))
  * **`icons`:** add collections icons for bolt and star ([#1338](https://github.com/box/box-ui-elements/issues/1338)) ([`8e9d503`](https://github.com/box/box-ui-elements/commit/8e9d503))
  * **`icons`:** add collections star filled icon ([#1547](https://github.com/box/box-ui-elements/issues/1547)) ([`55a182e`](https://github.com/box/box-ui-elements/commit/55a182e))
  * **`icons`:** add `IconFolderTree` icon ([#1696](https://github.com/box/box-ui-elements/issues/1696)) ([`add261b`](https://github.com/box/box-ui-elements/commit/add261b))
  * **`icons`:** add icons for collections ([#1224](https://github.com/box/box-ui-elements/issues/1224)) ([`a01ea82`](https://github.com/box/box-ui-elements/commit/a01ea82))
  * **`icons`:** add new shield Icon ([#1216](https://github.com/box/box-ui-elements/issues/1216)) ([`753d0e2`](https://github.com/box/box-ui-elements/commit/753d0e2))
  * **`icons`:** Add sandbox and puzzle piece icons ([#1370](https://github.com/box/box-ui-elements/issues/1370)) ([`67b6db4`](https://github.com/box/box-ui-elements/commit/67b6db4))
  * **`icons`:** add workflow icon ([#1225](https://github.com/box/box-ui-elements/issues/1225)) ([`9d73144`](https://github.com/box/box-ui-elements/commit/9d73144))
  * **`icons`:** creating task empty state icon ([#1583](https://github.com/box/box-ui-elements/issues/1583)) ([`cac4023`](https://github.com/box/box-ui-elements/commit/cac4023))
  * **`icons`:** new lightning icon ([#1183](https://github.com/box/box-ui-elements/issues/1183)) ([`ebccf18`](https://github.com/box/box-ui-elements/commit/ebccf18))
  * **`icons`:** update `IconShare` and `IconCollaboration` to new `32x32` icons ([#1232](https://github.com/box/box-ui-elements/issues/1232)) ([`4f4e31b`](https://github.com/box/box-ui-elements/commit/4f4e31b))
  * **`icons`:** update to new globe icon and add new globe `tinycon` ([#1217](https://github.com/box/box-ui-elements/issues/1217)) ([`3dded61`](https://github.com/box/box-ui-elements/commit/3dded61))
  * **`inline-edit`:** user should see instance field input ([#1172](https://github.com/box/box-ui-elements/issues/1172)) ([`1f90dde`](https://github.com/box/box-ui-elements/commit/1f90dde))
  * **`left-nav`:** add Box Relay icon ([#1207](https://github.com/box/box-ui-elements/issues/1207)) ([`29f07a6`](https://github.com/box/box-ui-elements/commit/29f07a6)), closes [#1206](https://github.com/box/box-ui-elements/issues/1206)
  * **`left-sidebar`:** `LeftSidebar` supports custom `navLinkRenderer` ([#1510](https://github.com/box/box-ui-elements/issues/1510)) ([`f9705a2`](https://github.com/box/box-ui-elements/commit/f9705a2))
  * **`leftsidebar`:** Show drop zones only on hover ([#1548](https://github.com/box/box-ui-elements/issues/1548)) ([`a45c998`](https://github.com/box/box-ui-elements/commit/a45c998))
  * **`media`:** create media object component ([#1383](https://github.com/box/box-ui-elements/issues/1383)) ([`5140c13`](https://github.com/box/box-ui-elements/commit/5140c13))
  * **`metadata`:** Enable metadata template filtering ([#1598](https://github.com/box/box-ui-elements/issues/1598)) ([`7b341f7`](https://github.com/box/box-ui-elements/commit/7b341f7))
  * **`metadata-views`:** Handle edit and cancel edit actions ([#1703](https://github.com/box/box-ui-elements/issues/1703)) ([`d55f84a`](https://github.com/box/box-ui-elements/commit/d55f84a))
  * **`metadata-views`:** Show edit icon in metadata view ([#1667](https://github.com/box/box-ui-elements/issues/1667)) ([`1b8a29d`](https://github.com/box/box-ui-elements/commit/1b8a29d))
  * **`metadata-views`:** Update metadata columns prop type in metadata view ([#1666](https://github.com/box/box-ui-elements/issues/1666)) ([`cbf96ef`](https://github.com/box/box-ui-elements/commit/cbf96ef))
  * **`new-tasks`:** Fetch task collaborators ([#1286](https://github.com/box/box-ui-elements/issues/1286)) ([`fb84aee`](https://github.com/box/box-ui-elements/commit/fb84aee))
  * **`office-online`:** adding excel spreadsheet icon for `xlsb` files ([`ee8569f`](https://github.com/box/box-ui-elements/commit/ee8569f))
  * **`pill-selector`:** `formik` wrapper for pill selector ([#1194](https://github.com/box/box-ui-elements/issues/1194)) ([`c75a7bb`](https://github.com/box/box-ui-elements/commit/c75a7bb))
  * **`pill-selector`:** update flow type for downstream issue ([#1210](https://github.com/box/box-ui-elements/issues/1210)) ([`69f25e8`](https://github.com/box/box-ui-elements/commit/69f25e8))
  * **`preview`:** Add support for custom logo URL in preview header ([#1714](https://github.com/box/box-ui-elements/issues/1714)) ([`d37b9ec`](https://github.com/box/box-ui-elements/commit/d37b9ec))
  * **`preview`:** better message when blocked by a policy ([#1346](https://github.com/box/box-ui-elements/issues/1346)) ([`a6cde28`](https://github.com/box/box-ui-elements/commit/a6cde28))
  * **`preview`:** new icon for security blocking ([#1396](https://github.com/box/box-ui-elements/issues/1396)) ([`9355631`](https://github.com/box/box-ui-elements/commit/9355631))
  * **`preview`:** Upgrade default version of box-content-preview to 2.16.0 ([#1562](https://github.com/box/box-ui-elements/issues/1562)) ([`7617fd2`](https://github.com/box/box-ui-elements/commit/7617fd2))
  * **`radio`:** `formik` wrapper for `RadioButton` ([#1204](https://github.com/box/box-ui-elements/issues/1204)) ([`0b51080`](https://github.com/box/box-ui-elements/commit/0b51080))
  * **`react`:** Add text for max version history ([#1630](https://github.com/box/box-ui-elements/issues/1630)) ([`705e71f`](https://github.com/box/box-ui-elements/commit/705e71f))
  * **`scroll`:** upgrade scroll in to view if needed ([#1200](https://github.com/box/box-ui-elements/issues/1200)) ([`1532617`](https://github.com/box/box-ui-elements/commit/1532617))
  * **`security`:** adding `SecurityBadge` component ([#1663](https://github.com/box/box-ui-elements/issues/1663)) ([`3d210bb`](https://github.com/box/box-ui-elements/commit/3d210bb))
  * **`select`:** make caret rotate up/down on open/close respectively ([#1218](https://github.com/box/box-ui-elements/issues/1218)) ([`9627e2b`](https://github.com/box/box-ui-elements/commit/9627e2b))
  * **`select-field`:** Allow rendering custom options ([#1516](https://github.com/box/box-ui-elements/issues/1516)) ([`53fe270`](https://github.com/box/box-ui-elements/commit/53fe270))
  * **`shared-link-settings-modal`:** Disable direct downloads if classified ([#1500](https://github.com/box/box-ui-elements/issues/1500)) ([`2ede02a`](https://github.com/box/box-ui-elements/commit/2ede02a))
  * **`sidebar`:** Add support for toggling the sidebar externally ([#1293](https://github.com/box/box-ui-elements/issues/1293)) ([`04468fc`](https://github.com/box/box-ui-elements/commit/04468fc))
  * **`sidebar`:** programmatic refresh ([#1472](https://github.com/box/box-ui-elements/issues/1472)) ([`c7a19e7`](https://github.com/box/box-ui-elements/commit/c7a19e7))
  * **`sidebar`:** Show retention policy info in sidebar ([#1648](https://github.com/box/box-ui-elements/issues/1648)) ([`cb9e714`](https://github.com/box/box-ui-elements/commit/cb9e714))
  * **`sidebar`:** Toggle button ([#1268](https://github.com/box/box-ui-elements/issues/1268)) ([`e2ad4ab`](https://github.com/box/box-ui-elements/commit/e2ad4ab))
  * **`task-new`:** add ability to add/remove assignees ([#1284](https://github.com/box/box-ui-elements/issues/1284)) ([`8e87280`](https://github.com/box/box-ui-elements/commit/8e87280))
  * **`task-new`:** Add support for edit modal ([#1261](https://github.com/box/box-ui-elements/issues/1261)) ([`d13839c`](https://github.com/box/box-ui-elements/commit/d13839c))
  * **`tasks`:** add any task icon + tooltip ([#1491](https://github.com/box/box-ui-elements/issues/1491)) ([`cf1c5b7`](https://github.com/box/box-ui-elements/commit/cf1c5b7))
  * **`tasks`:** add any/all checkbox ([#1487](https://github.com/box/box-ui-elements/issues/1487)) ([`21271e3`](https://github.com/box/box-ui-elements/commit/21271e3))
  * **`tasks`:** add in comment modification option for tasks ([#1247](https://github.com/box/box-ui-elements/issues/1247)) ([`b5775de`](https://github.com/box/box-ui-elements/commit/b5775de))
  * **`tasks`:** Add new task edit API methods ([#1260](https://github.com/box/box-ui-elements/issues/1260)) ([`e05d5a7`](https://github.com/box/box-ui-elements/commit/e05d5a7))
  * **`tasks`:** handle new error message with title and description ([#1564](https://github.com/box/box-ui-elements/issues/1564)) ([`7d691df`](https://github.com/box/box-ui-elements/commit/7d691df))
  * **`tasks`:** strings for any completion rule ([#1471](https://github.com/box/box-ui-elements/issues/1471)) ([`cdaf285`](https://github.com/box/box-ui-elements/commit/cdaf285))
  * **`tasks`:** Update task status to not use an icon ([#1169](https://github.com/box/box-ui-elements/issues/1169)) ([`b4b8bf0`](https://github.com/box/box-ui-elements/commit/b4b8bf0))
  * **`tasks-new`:** add assignee list ([#1287](https://github.com/box/box-ui-elements/issues/1287)) ([`04b7458`](https://github.com/box/box-ui-elements/commit/04b7458))
  * **`tasks-new`:** Edit task message and due date in `TaskForm` ([#1269](https://github.com/box/box-ui-elements/issues/1269)) ([`7f63d97`](https://github.com/box/box-ui-elements/commit/7f63d97))
  * **`tasks-new`:** remove beta label functionality from modal header ([#1314](https://github.com/box/box-ui-elements/issues/1314)) ([`dca414b`](https://github.com/box/box-ui-elements/commit/dca414b))
  * **`tasks-new`:** tasks resin tracking for edit modal ([#1327](https://github.com/box/box-ui-elements/issues/1327)) ([`5b5b354`](https://github.com/box/box-ui-elements/commit/5b5b354))
  * **`typography`:** update body typography ([#1442](https://github.com/box/box-ui-elements/issues/1442)) ([`375c336`](https://github.com/box/box-ui-elements/commit/375c336)), closes [#1439](https://github.com/box/box-ui-elements/issues/1439) [#1441](https://github.com/box/box-ui-elements/issues/1441)
  * **`unified-share-modal`:** add external collaboration warning message ([#1220](https://github.com/box/box-ui-elements/issues/1220)) ([`064bd2f`](https://github.com/box/box-ui-elements/commit/064bd2f))
  * **`unified-share-modal`:** add property to limit the number of contacts ([#1304](https://github.com/box/box-ui-elements/issues/1304)) ([`2af11b1`](https://github.com/box/box-ui-elements/commit/2af11b1))
  * **`unified-share-modal`:** invite section tooltip changes ([#1499](https://github.com/box/box-ui-elements/issues/1499)) ([`d7730c7`](https://github.com/box/box-ui-elements/commit/d7730c7)), closes [#1498](https://github.com/box/box-ui-elements/issues/1498)
  * **`unified-share-modal`:** invite section tooltips changes ([#1504](https://github.com/box/box-ui-elements/issues/1504)) ([`b9486bc`](https://github.com/box/box-ui-elements/commit/b9486bc))
  * **`unified-share-modal`:** show classification for the file ([#1425](https://github.com/box/box-ui-elements/issues/1425)) ([`e3c7277`](https://github.com/box/box-ui-elements/commit/e3c7277))
  * **`unified-share-modal`:** Show external collaborators indicator ([#1256](https://github.com/box/box-ui-elements/issues/1256)) ([`613a438`](https://github.com/box/box-ui-elements/commit/613a438))
  * **`uploads`:** add resin targets for uploads manager ([#1384](https://github.com/box/box-ui-elements/issues/1384)) ([`29d2af5`](https://github.com/box/box-ui-elements/commit/29d2af5))
  * **`uploads`:** resume a single file upload ([#1552](https://github.com/box/box-ui-elements/issues/1552)) ([`093f889`](https://github.com/box/box-ui-elements/commit/093f889))
  * **`uploads`:** resume multiple unsuccessful uploads ([#1553](https://github.com/box/box-ui-elements/issues/1553)) ([`60406b9`](https://github.com/box/box-ui-elements/commit/60406b9))
  * **`uploads`:** uploads manager contents for resumable uploads ([#1555](https://github.com/box/box-ui-elements/issues/1555)) ([`8380bc7`](https://github.com/box/box-ui-elements/commit/8380bc7))
  * **`usm`:** expand Invite Section based on `initiallySelectedContacts` ([#1470](https://github.com/box/box-ui-elements/issues/1470)) ([`b756a22`](https://github.com/box/box-ui-elements/commit/b756a22))
  * **`validators`:** `host`, `ipv4` and domain name validators ([#1212](https://github.com/box/box-ui-elements/issues/1212)) ([`f653dac`](https://github.com/box/box-ui-elements/commit/f653dac))
  * **`versions`:** Add client-side error messages for version actions ([#1404](https://github.com/box/box-ui-elements/issues/1404)) ([`8ead57c`](https://github.com/box/box-ui-elements/commit/8ead57c))
  * **`versions`:** Add resin tracking for sidebar back button ([#1309](https://github.com/box/box-ui-elements/issues/1309)) ([`901c23d`](https://github.com/box/box-ui-elements/commit/901c23d))
  * **`versions`:** Add resin tracking to all version history actions ([#1285](https://github.com/box/box-ui-elements/issues/1285)) ([`a4942d3`](https://github.com/box/box-ui-elements/commit/a4942d3))
  * **`versions`:** Add support for deep linking to `ContentSidebar` ([#1203](https://github.com/box/box-ui-elements/issues/1203)) ([`78ab636`](https://github.com/box/box-ui-elements/commit/78ab636))
  * **`versions`:** Add support for file version restore actions ([#1184](https://github.com/box/box-ui-elements/issues/1184)) ([`d5396bd`](https://github.com/box/box-ui-elements/commit/d5396bd))
  * **`versions`:** Add support for version action callbacks ([#1417](https://github.com/box/box-ui-elements/issues/1417)) ([`099a09e`](https://github.com/box/box-ui-elements/commit/099a09e))
  * **`versions`:** Add support for version limits to sidebar ([#1316](https://github.com/box/box-ui-elements/issues/1316)) ([`bec5699`](https://github.com/box/box-ui-elements/commit/bec5699))
  * **`versions`:** Add version group headers based on relative date ([#1330](https://github.com/box/box-ui-elements/issues/1330)) ([`51d5633`](https://github.com/box/box-ui-elements/commit/51d5633))
  * add `metadata_queries` API layer ([#1481](https://github.com/box/box-ui-elements/issues/1481)) ([`2f6ef29`](https://github.com/box/box-ui-elements/commit/2f6ef29))
  * add prop for resumable uploads feature flip ([#1447](https://github.com/box/box-ui-elements/issues/1447)) ([`3f19a3b`](https://github.com/box/box-ui-elements/commit/3f19a3b))
  * Adding prop `initiallySelectedContacts` to `UnifiedShareModal` ([#1424](https://github.com/box/box-ui-elements/issues/1424)) ([`8966016`](https://github.com/box/box-ui-elements/commit/8966016))
  * default task icons to `$bdl-box-blue` ([#1509](https://github.com/box/box-ui-elements/issues/1509)) ([`dbc7103`](https://github.com/box/box-ui-elements/commit/dbc7103))
  * increase fetched file collaborators for tasks/comments ([#1483](https://github.com/box/box-ui-elements/issues/1483)) ([`05f65f4`](https://github.com/box/box-ui-elements/commit/05f65f4))

  ### Performance Improvements

  * **`sidebar`:** Lazy load sidebar panels without 500 millisecond delay ([#1223](https://github.com/box/box-ui-elements/issues/1223)) ([`bb216b4`](https://github.com/box/box-ui-elements/commit/bb216b4))
  * **`sidebar`:** merge response to avoid redundant API calls ([#1617](https://github.com/box/box-ui-elements/issues/1617)) ([`69ad154`](https://github.com/box/box-ui-elements/commit/69ad154))
  * **`version`:** Remove version history modal ([#1633](https://github.com/box/box-ui-elements/issues/1633)) ([`eb0aac6`](https://github.com/box/box-ui-elements/commit/eb0aac6))

  ### Reverts

  * **`avatar`:** Move Avatar back to non-hook implementation ([#1186](https://github.com/box/box-ui-elements/issues/1186)) ([`69f329b`](https://github.com/box/box-ui-elements/commit/69f329b))

  ### BREAKING CHANGES

  * **`formik`:** `inputProps` dropped from Toggle component. `formik` has been upgraded to V2. [Upgrade guide](https://github.com/jaredpalmer/formik/blob/master/docs/migrating-v2.md).

  * Peer dependency React requirement have been bumped higher

  * refactor(avatar): Refactor Avatar to use hooks

  * fix(test): Fixed various test issues, downgraded enzyme back to 3.8.0

  * fix(avatar): remove redundant check

  * **`classification`:** Also changes `advisoryMessage` prop to definition to keep terminology consistent

  * feat(classification): Increasing classification icon stroke width

  * **`typography`:** The color of the body will be default to [#222](https://github.com/box/box-developer-changelog/issues/222) which
    is the `bdl-gray`

  * feat(typography): update letter spacing for common typography

  * **`typography`:** The letter spacing for common typography will now
    be `px` instead of `em`. Please check scaling.

  * **`classification`:** The API for providing classification data to the sidebar has changed to `{ advisoryMessage, name }`

  * feat: design changes

  * feat: classification badge changes

  * fix: PR feedback

  * fix: snapshot

  * **`icons`:** Replacing `IconShield` with a new Icon that represent
    Shield. It follows the 32 x 32 guideline. Please override any style if needed.

  * **`deps`:** update react-\* peer dependencies to 16.9.0

  Updating to React 16.9 includes deprecation warnings for lifecycle methods.
  This affects one of our dependencies, react-tether; we have no immediate
  plans to silence the warnings.

  * **`security`:** Upgrade `axios` peer dependency to address [https://nvd.nist.gov/vuln/detail/CVE-2019-10742](https://nvd.nist.gov/vuln/detail/CVE-2019-10742)

  * **`icons`:** update to new globe icon which uses `20x20` by default instead of `16x16` and introduced new globe `tinycon`

  * **`validators`:** Adds peer dependency of [**`@hapi/address`**](https://github.com/hapi/address) used for email and domain validation

  * fix: added uncommon `tlds` for email checking

  * fix: adding some bad `tlds`

  * **`scroll`:** Major version upgrade for scroll-into-view-if-needed.

  * **`i18n`:** Added additional peer dependencies to support `i18n` `FormattedCompMessage` component

  Implement a new component called `FormattedCompMessage`. This translates strings which can contain HTML or other JSX components in a safe way by hiding the contents of those tags from the translators or hackers and substituting the contents from source strings into the translations. Example:

  ```javascript theme={null}
  <FormattedCompMessage id="mystring" description="translator's comment">
     You can <span class="foo">delete</span> <Link to={url}>these files</Link>, or just
    <span id="x" class="unshare">unshare them</span>.
  </FormattedCompMessage>
  ```

  `FormattedCompMessage` is built as a layer on top of `react-intl`, and uses it to do the actual translations. Its function is to transform a tree of React elements into a coded string, get that string translated with `react-intl`, transform the coded translated string back into a tree of React elements, and finally substitute the hidden React elements from the source tree back into the translation tree in the right locations.

  The component depends on the new babel plugin `babel-plugin-box-i18n` to extract the coded texts from the source code and place them into the same type of JSON files that the `react-intl` babel plugin produces. In this way, the translation process downstream from there works with no further changes. The translations appear in the properties files some time later and `react-intl` picks them up as normal. The `FormattedCompMessage` can retrieve these translations using `react-intl`. The `babel-pluging-box-i18n` plugin also enforces Box's policies, such as the requirement that all strings have a unique id and a description for the translators.

  The `FormattedCompMessage` component can support plurals in a React-idiomatic way by embedding `<Plural>` components in the body of the `FormattedCompMessage`:

  ```javascript theme={null}
  <FormattedCompMessage id="mystring" description="translator's comment" count={count}>
    <Plural category="one">This is the <strong>singular</strong> string.</Plural>
    <Plural category="other">This is the <strong>plural</strong> string.</Plural>
  </FormattedCompMessage>
  ```

  Note that HTML and subcomponents are allowed in the plural string as well.

  The `FormattedCompMessage` component supports replacement parameters in a React-idiomatic way by embedding `<Param>` components in the body of the `FormattedCompMessage`:

  ```javascript theme={null}
  <FormattedCompMessage id="mystring" description="translator's comment">
    User <Param value={user.name} description="The user's full name"/> has already deleted this file.
  </FormattedCompMessage>
  ```

  Note that the `Param` tags can be used inside of `Plural` tags as well, as they are normal components.

  * **`deps`:** Peer dependencies have been updated and will require downstream applications to update as well to avoid NPM warnings.
  * **`icons`:** Old `IconShare` defaulted to `26x26` and old `IconCollaboration` defaulted to `27x26` but new icons are defaulted to `32x32`.  Also, default SVG classnames are now changed to `bdl-IconShare` and `bdl-IconCollaboration`.
</Update>

<Update label="2019-10-25">
  ## New parameters for Search API

  New optional query parameters have been made available for the
  [Search API](/reference/get-search), namely `sort` and `direction`.

  The purpose of these parameters is to allow applications to sort items by their
  `modified_at` date in ascending or descending order.
</Update>

<Update label="2019-10-25">
  ## New fields for File Versions

  New optional fields have been made available within the File Version object,
  namely `trashed_by`, `restored_by` and `restored_at`.

  The fields will be returned as part of the standard
  [File Version object](/reference/resources/file-version/).

  The purpose of these fields is to have a better understanding of when file
  versions have been moved in and out of the trash, and by whom.
</Update>

<Update label="2019-10-24" description="Python SDK v2.6.1 released">
  ## New Features and Enhancements

  * Added `api_` call decorator for copy method.
</Update>

<Update label="2019-10-24" description="Java SDK v2.41.0 released">
  ## New Features and Enhancements

  1. Added enum for complete field on `BoxTasks` Actions enum ([#745](https://github.com/box/box-java-sdk/pull/745))
</Update>

<Update label="2019-10-24">
  ## Java SDK v2.40.0 released

  1. Update `comments.md` ([#749](https://github.com/box/box-java-sdk/pull/749))
  2. Update `events.md` ([#750](https://github.com/box/box-java-sdk/pull/750))
  3. Update `collections.md` ([#748](https://github.com/box/box-java-sdk/pull/748))
  4. Update `files.md` ([#747](https://github.com/box/box-java-sdk/pull/747))
  5. Update `files.md` ([#746](https://github.com/box/box-java-sdk/pull/746))
  6. Update `files.md` to tag thumbnail code sample ([#733](https://github.com/box/box-java-sdk/pull/733))
  7. Update `authentication.md` ([#739](https://github.com/box/box-java-sdk/pull/739))
</Update>

<Update label="2019-10-23">
  ## New Shield Error Code

  A new error code for [Box Shield](https://www.box.com/shield) has been released. The new
  `403 - forbidden_by_policy` error code will be raised when the enterprise has
  applied Shield access policies that prevent the action, such as downloading
  items.

  The resolution path is to contact your Box admin to adjust the Shield access
  policies if the action is required.

  See the
  [error code documentation](/guides/api-calls/permissions-and-errors/common-errors)
  for more details and solution path.
</Update>

<Update label="2019-10-18">
  ## Relay API Endpoints will EOL on December 31st, 2019

  On December 31st, 2019, Box will end of life all Relay Classic API endpoints,
  which includes the following functions:

  * Get list of published Relay Classic templates.
  * Get list of Relay Classic workflows.
  * Launch a Relay Classic workflow.

  To ensure that your application continues to function after December 31st
  please remove all calls to the Relay Classic APIs listed above.
</Update>

<Update label="2019-10-17">
  ## Java SDK v2.39.0 released

  1. Deprecating batch ([#741](https://github.com/box/box-java-sdk/pull/741))
  2. Add support for Task `completion_rule` ([#738](https://github.com/box/box-java-sdk/pull/738))
</Update>

<Update label="2019-09-19">
  ## Windows .NET SDK v3.20.0 released

  See [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3200) for details
  Commits: [`v3.19.0...v3.20.0`](https://github.com/box/box-windows-sdk-v2/compare/`v3.19.0...v3.20.0`)

  [`nuget.org/packages/Box.V2/3.20.0`](https://www.nuget.org/packages/Box.V2/3.20.0)
  [`nuget.org/packages/Box.V2.Core/3.20.0`](https://www.nuget.org/packages/Box.V2.Core/3.20.0)
</Update>

<Update label="2019-09-19">
  ## Java SDK v2.38.0 released

  1. Added field `trashed_by`, `restored_at`, `restored_by`, `purged_at` to `FileVersion` ([#734](https://github.com/box/box-java-sdk/pull/734))
  2. Set file attributes on chunked uploads ([#730](https://github.com/box/box-java-sdk/pull/730))
</Update>

<Update label="2019-09-18">
  ## New security enhancements for token revocation

  We have enhanced the capabilities of the [token
  revocation](/reference/post-oauth2-revoke/) endpoint to permit
  [downscoped tokens](/guides/authentication/tokens/downscope) to be
  revoked prior to their expiration time. Previous to this update only fully
  scoped access tokens could be revoked through the /revoke endpoint. With this
  new enhancement downscoped tokens may now be revoked in addition to the fully
  scoped access tokens.

  More information is available [here](https://medium.com/box-developer-blog/new-security-enhancements-for-revoking-access-tokens-79b9960a7ce2).
</Update>

<Update label="2019-09-11">
  ## New completion\_rule field for Tasks

  A new optional field has been made available within the Task object,
  `completion_rule`. This field may be set through the use of the
  [Create Task](/reference/post-tasks) and [Update Task](/reference/put-tasks-id)
  endpoints, and will be returned as part of the standard
  [Task object](/reference/tasks-resources#task).

  The purpose of this field is to set the conditions under which a task is
  completed, based on user involvement. When a task is created with a completion
  rule of `all_assignees` (default), the task will only be considered completed
  when all assignees have completed the task. When a task is created with a
  completion rule of `any_assignee`, the task will be considered completed when
  one assignee has completed the task.
</Update>

<Update label="2019-08-29">
  ## Windows .NET SDK v3.19.0 released

  See [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3190) for details
  Commits: [`v3.18.0...v3.19.0`](https://github.com/box/box-windows-sdk-v2/compare/`v3.18.0...v3.19.0`)

  [`nuget.org/packages/Box.V2/3.19.0`](https://www.nuget.org/packages/Box.V2/3.19.0)
  [`nuget.org/packages/Box.V2.Core/3.19.0`](https://www.nuget.org/packages/Box.V2.Core/3.19.0)
</Update>

<Update label="2019-08-29">
  ## Python SDK v2.6.0 released

  Adding a new get admin events function with `created_before`, `created_after`, and `event_type` parameters. Thank you `@capk1rk`!
</Update>

<Update label="2019-08-29">
  ## Box CLI v2.4.0 released

  [CHANGELOG](https://github.com/box/boxcli/blob/master/CHANGELOG.md#240-2019-08-29)

  * Fix output when updating collaboration role to owner ([#165](https://github.com/box/boxcli/pull/165))  [`f8be639`](https://github.com/box/boxcli/commit/f8be639)
  * Print all columns in CSV output for heterogeneous collection ([#164](https://github.com/box/boxcli/pull/164))  [`a8dda02`](https://github.com/box/boxcli/commit/a8dda02)
  * Update plugin-help to resolve warning about `lodash.template` ([#160](https://github.com/box/boxcli/pull/160))  [`3730bc5`](https://github.com/box/boxcli/commit/3730bc5)
  * Bump `lodash` from 4.17.11 to 4.17.13 ([#156](https://github.com/box/boxcli/pull/156))  [`d035e74`](https://github.com/box/boxcli/commit/d035e74)
  * Add support for setting external app user ID ([#153](https://github.com/box/boxcli/pull/153))  [`d68b61b`](https://github.com/box/boxcli/commit/d68b61b)
  * Update `js-yaml` to 3.13.1 ([#151](https://github.com/box/boxcli/pull/151))  [`13745df`](https://github.com/box/boxcli/commit/13745df)

  [`v2.3.0...v2.4.0`](https://github.com/box/boxcli/compare/`v2.3.0...v2.4.0`)
</Update>

<Update label="2019-08-22">
  ## Node SDK v1.29.1 released

  * Regenerate JTI and retry auth request when JTI claim is rejected ([#405](https://github.com/box/box-node-sdk/pull/405))  [`c0ccdb9`](https://github.com/box/box-node-sdk/commit/c0ccdb9)

  [`v1.29.0...v1.29.1`](https://github.com/box/box-node-sdk/compare/`v1.29.0...v1.29.1`)
</Update>

<Update label="2019-08-22">
  ## Java SDK v2.37.0 released

  1. Improving authentication docs for `BoxConfig.readFrom()` ([#723](https://github.com/box/box-java-sdk/pull/723))
  2. Add replace functionality for multi select metadata ([#726](https://github.com/box/box-java-sdk/pull/726))
</Update>

<Update label="2019-08-01">
  ## Java SDK v2.36.0 released

  1. Added convenience function for shared link and fixed setting… ([#720](https://github.com/box/box-java-sdk/pull/720))
  2. Add missing fields to files, folders, and web links ([#719](https://github.com/box/box-java-sdk/pull/719))
</Update>

<Update label="2019-07-18">
  ## Java SDK v2.35.0 released

  1. Added support for `is_externally_owned` field ([#714](https://github.com/box/box-java-sdk/pull/714))
  2. Added exception messaging for old `error` and `error_description` ([#710](https://github.com/box/box-java-sdk/pull/710))
</Update>

<Update label="2019-06-26">
  ## New supported values in Tasks API

  On June 26th, Box released support for a new task type, general tasks. When
  creating or updating a task, the `action` field can either be `review` for
  approval tasks or `complete` for the new general tasks.

  This change also affects the accepted values when updating a task assignment.
  If you want to update an approval/review task, the `resolution_state` can be
  set to `incomplete`, `approved`, or `rejected`. A general/complete task can
  have a `resolution_state` of `incomplete` or `completed`.

  The Tasks API doesn't refer to tasks as "General" or "Approval" within the
  response body. This is reflected only within Box's UI.

  Docs can be found [here](/reference/tasks-resources#task).
</Update>

<Update label="2019-06-20">
  ## Windows .NET SDK v3.18.0 released

  See [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3180) for details
  Commits: [`v3.17.0...v3.18.0`](https://github.com/box/box-windows-sdk-v2/compare/`v3.17.0...v3.18.0`)

  [`nuget.org/packages/Box.V2/3.18.0`](https://www.nuget.org/packages/Box.V2/3.18.0)
  [`nuget.org/packages/Box.V2.Core/3.18.0`](https://www.nuget.org/packages/Box.V2.Core/3.18.0)
</Update>

<Update label="2019-06-20">
  ## Python SDK v2.5.0 released

  Allowed passing `None` to clear `configurable_permission` field in the `add_member()` method.
</Update>

<Update label="2019-06-06">
  ## Java SDK v2.34.0 released

  1. Added fields: action for task ([#707](https://github.com/box/box-java-sdk/pull/707))
</Update>

<Update label="2019-05-31">
  ## Replaced Obsolete Field in Collaborations

  In 2018 a new field, `acceptance_requirements_status` was added to the GET
  collaborations/id API endpoint to support additional notification use cases.
  This field includes terms of service, 2-factor auth, and strong password
  requirements. The existing `acceptance_requirements` field, which only contains
  Terms of Service requirements, have been replaced with the new
  `acceptance_requirements_status`.

  Previously a call to `GET
    /collaboration/<collaboration_id>?fields=acceptance_requirements` would return
  an object like the following:

  ```js theme={null}
  "acceptance_requirements": {
      "terms_of_service": {
          "type": "terms_of_service",
          "id": <tos_id>
      }
  }
  ```

  With the new field, the request `GET
    /collaboration/<collaboration_id>?fields=acceptance_requirements_status` would
  return the following:

  ```js theme={null}
   "acceptance_requirements_status": {
      "terms_of_service_requirement": {
          "is_accepted": true,
          "terms_of_service": {
              "type": "terms_of_service",
              "id": <tos_id>
          }
      },
      "strong_password_requirement": {
          "enterprise_has_strong_password_required_for_external_users": true,
          "user_has_strong_password": false
      },
      "two_factor_authentication_requirement": {
          "enterprise_has_two_factor_auth_enabled": true,
          "user_has_two_factor_authentication_enabled" true
      }
  }
  ```
</Update>

<Update label="2019-05-23">
  ## Java SDK v2.33.0 released

  1. Added test for making sure part buffer is correct size ([#703](https://github.com/box/box-java-sdk/pull/703))
  2. Allow setting `can_non_owners_invite` field on Folder objects ([#700](https://github.com/box/box-java-sdk/pull/700))
</Update>

<Update label="2019-05-23">
  ## Box CLI v2.3.0 released

  [CHANGELOG](https://github.com/box/boxcli/blob/master/CHANGELOG.md#230-2019-05-23)

  [`v2.2.0...v2.3.0`](https://github.com/box/boxcli/compare/`v2.2.0...v2.3.0`)
</Update>

<Update label="2019-05-16">
  ## Python SDK v2.4.1 released

  1. Added ability for users to use set metadata on [files](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#set-metadata) and [folders](https://github.com/box/box-python-sdk/blob/master/docs/usage/folders.md#set-metadata)
</Update>

<Update label="2019-05-15">
  ## TLS 1.0 deprecated complete

  On May 13th, 2019, Box began the process of disabling TLS 1.0 requests to Box
  APIs. As of today, all TLS 1.0 API requests will be returning a response
  stating that a secure connection could not be established when making API calls.

  Impacted developers will have been notified through multiple channels over the
  last 6-12 months, but should your application be impacted you will need to
  update your systems to again be able to make API requests to Box.

  Please see our TLS 1.0 deprecation guide to
  upgrade your systems to TLS 1.2.

  For any questions or for addition support, please
  [file a support ticket](https://support.box.com/hc/en-us/requests/new).
</Update>

<Update label="2019-05-10">
  ## Box CLI v2.2.0 released

  * Update CHANGELOG for `v2.2.0` release ([#143](https://github.com/box/boxcli/pull/143))  [`96b49d5`](https://github.com/box/boxcli/commit/96b49d5)
  * Remove unnecessary dependency ([#141](https://github.com/box/boxcli/pull/141))  [`7ac5563`](https://github.com/box/boxcli/commit/7ac5563)
  * Record text of third party licenses ([#142](https://github.com/box/boxcli/pull/142))  [`47b78f1`](https://github.com/box/boxcli/commit/47b78f1)
  * Build command docs on separate pages ([#139](https://github.com/box/boxcli/pull/139))  [`01534f1`](https://github.com/box/boxcli/commit/01534f1)
  * Catch bulk input errors with converted delegate command ([#134](https://github.com/box/boxcli/pull/134))  [`5cd5eee`](https://github.com/box/boxcli/commit/5cd5eee)
  * Add metadata set commands ([#136](https://github.com/box/boxcli/pull/136))  [`efa33ed`](https://github.com/box/boxcli/commit/efa33ed)
  * Add issue template ([#138](https://github.com/box/boxcli/pull/138))  [`a5cbddf`](https://github.com/box/boxcli/commit/a5cbddf)
  * Fix duplicate call during bulk input on delegated command ([#133](https://github.com/box/boxcli/pull/133))  [`ba3d65a`](https://github.com/box/boxcli/commit/ba3d65a)
  * Fix adding `web_links` to a collection ([#132](https://github.com/box/boxcli/pull/132))  [`8fc2023`](https://github.com/box/boxcli/commit/8fc2023)
  * Add search sort flags ([#131](https://github.com/box/boxcli/pull/131))  [`57f8d3d`](https://github.com/box/boxcli/commit/57f8d3d)

  [`v2.1.0...v2.2.0`](https://github.com/box/boxcli/compare/`v2.1.0...v2.2.0`)
</Update>

<Update label="2019-05-09">
  ## Windows .NET SDK v3.17.0 released

  * Fixed the encoding of dates in the query parameters for Events and Search endpoints
  * Deprecated `FilesManager.DownloadStreamAsync()` and introduced a replacement method with correct parameter types for byte offsets: `FilesManager.DownloadAsync()`

  [`nuget.org/packages/Box.V2/3.17.0`](https://www.nuget.org/packages/Box.V2/3.17.0)
  [`nuget.org/packages/Box.V2.Core/3.17.0`](https://www.nuget.org/packages/Box.V2.Core/3.17.0)
</Update>

<Update label="2019-04-29">
  ## Windows .NET SDK v3.16.0 released

  * Added `sort` and `direction` parameters to `client.SearchManager.SearchAsync()` to control sort order
  * Added `extension` parameter to `client.FilesManager.GetThumbnailAsync()` to control which thumbnail format is returned (thanks `@guilmori`!)
  * Fixed a bug where query string parameters were not correctly encoded
  * Added `SetFileMetadataAsync()` and `SetFolderMetadataAsync()` methods to `client.MetadataManager` to set metadata
    keys and values, overwriting existing values for the provided keys.
  * Automatically retry most API calls when the API responds with a transient error status code

  [`nuget.org/packages/Box.V2/3.16.0`](https://www.nuget.org/packages/Box.V2/3.16.0)
  [`nuget.org/packages/Box.V2.Core/3.16.0`](https://www.nuget.org/packages/Box.V2.Core/3.16.0)
</Update>

<Update label="2019-04-25">
  ## Node SDK v1.29.0 released

  * Prepare `v1.29.0` release ([#381](https://github.com/box/box-node-sdk/pull/381))  [`4860e7c`](https://github.com/box/box-node-sdk/commit/4860e7c)
  * Add convenience methods for setting metadata ([#376](https://github.com/box/box-node-sdk/pull/376))  [`1938e39`](https://github.com/box/box-node-sdk/commit/1938e39)
  * Use HTML comments in issue template  [`01f21df`](https://github.com/box/box-node-sdk/commit/01f21df)
  * Document search sort parameters ([#370](https://github.com/box/box-node-sdk/pull/370))  [`257e748`](https://github.com/box/box-node-sdk/commit/257e748)

  [`v1.28.0...v1.29.0`](https://github.com/box/box-node-sdk/compare/`v1.28.0...v1.29.0`)
</Update>

<Update label="2019-04-25">
  ## Java SDK v2.32.0 released

  1. Support for Set Metadata ([#697](https://github.com/box/box-java-sdk/pull/697))
</Update>

<Update label="2019-04-15">
  ## Changes to Task (Assignment) API responses

  We have released an update to the API responses of the
  [Get Task](/reference/get-tasks-id) and
  [Get Task Assignment](/reference/get-task-assignments-id) endpoints.

  Prior to this change, if a call was made to get a task or task assignment with
  a valid task ID, and that file was deleted or your permissions changed to
  prevent viewing the file, you would receive a 404 error because the tasks would
  be deleted with the file.

  With this new change, the response returned will be the task object with a
  `null` response where the item would be, rather than a 404 error response.
</Update>

<Update label="2019-04-11">
  ## Java SDK v2.31.0 released

  1. Add support for sorting folder items ([#694](https://github.com/box/box-java-sdk/pull/694))
</Update>

<Update label="2019-04-10">
  ## Box CLI v1.4.0 released

  * Added the option to update collaboration expiration date
</Update>

<Update label="2019-04-08">
  ## Java SDK v2.30.1 released

  1. Fix date parsing to correctly handle RFC3339 timezone format ([#693](https://github.com/box/box-java-sdk/pull/693))
</Update>

<Update label="2019-04-04">
  ## Java SDK v2.30.0 released

  1. Added `action_by` field to `BoxEvent` ([#692](https://github.com/box/box-java-sdk/pull/692))
</Update>

<Update label="2019-04-01">
  ## Java SDK v2.29.0 released

  1. Support for uploading file with description ([#690](https://github.com/box/box-java-sdk/pull/690))
  2. Add sort and direction fields to search ([#689](https://github.com/box/box-java-sdk/pull/689))
</Update>

<Update label="2019-03-29">
  ## Python SDK v2.3.2 released

  * Fixing an issue in `v2.3.1` where package could not be installed.
</Update>

<Update label="2019-03-29">
  ## Box CLI 2.1.0 release

  A new version of the Box CLI has been released, taking the version from 2.0.0
  to 2.1.0. This release includes a number of feature enhancements and bug fixes:

  * Fixed paging for events commands ([link](https://github.com/box/boxcli/pull/126))
  * Updated `lodash` version ([link](https://github.com/box/boxcli/pull/129))
  * Send fields parameter to API when `--fields` flag is used ([link](https://github.com/box/boxcli/pull/113))
  * Fix event-types flag ([link](https://github.com/box/boxcli/pull/120))
  * Added build NPM script ([link](https://github.com/box/boxcli/commit/f0f88f66e3014afba616b5a2994157d435094b56))
</Update>

<Update label="2019-03-28">
  ## Windows .NET SDK v3.15.0 released

  * Added support for passing custom `IBoxService` to `BoxJWTAuth` constructor.

  [`nuget.org/packages/Box.V2/3.15.0`](https://www.nuget.org/packages/Box.V2/3.15.0)
  [`nuget.org/packages/Box.V2.Core/3.15.0`](https://www.nuget.org/packages/Box.V2.Core/3.15.0)
</Update>

<Update label="2019-03-28">
  ## Python SDK v2.3.0 released

  * Added the ability to set [file description upon upload](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#upload-a-file)
  * Added support for [basic authenticated proxy and unauthenticated proxy](https://github.com/box/box-python-sdk/blob/master/docs/usage/configuration.md#proxy)
</Update>

<Update label="2019-03-28">
  ## Node SDK v1.28.0 released

  * Prepare for `v1.28.0` release ([#366](https://github.com/box/box-node-sdk/pull/366))  [`8fa21de`](https://github.com/box/box-node-sdk/commit/8fa21de)
  * Add common item methods for Web Links ([#364](https://github.com/box/box-node-sdk/pull/364))  [`7549d4f`](https://github.com/box/box-node-sdk/commit/7549d4f)

  [`v1.27.0...v1.28.0`](https://github.com/box/box-node-sdk/compare/`v1.27.0...v1.28.0`)
</Update>

<Update label="2019-03-18">
  ## Box Android SDK v4.2.3 released

  Contains various bug fixes and stability improvements
</Update>

<Update label="2019-03-14">
  ## Python SDK v2.2.2 released

  * Updated `requests-toolbelt` dependency restriction
</Update>

<Update label="2019-03-07">
  ## Windows .NET SDK v3.14.1 released

  * Removed unnecessary `package.config` from sample files.

  [`nuget.org/packages/Box.V2/3.14.1`](https://www.nuget.org/packages/Box.V2/3.14.1)
  [`nuget.org/packages/Box.V2.Core/3.14.1`](https://www.nuget.org/packages/Box.V2.Core/3.14.1)
</Update>

<Update label="2019-03-07">
  ## Java SDK v2.28.1 released

  1. Wrong casting for response in `BoxAPIResponse` for `BoxMetadataCascadePolicy.forceApply()` ([#685](https://github.com/box/box-java-sdk/pull/685))
</Update>

<Update label="2019-03-01">
  ## Windows .NET SDK v3.14.0 released

  * Added trace ID to API response exception message.
  * Fix deserialization of translated task assignment status.

  [`nuget.org/packages/Box.V2/3.14.0`](https://www.nuget.org/packages/Box.V2/3.14.0)
  [`nuget.org/packages/Box.V2.Core/3.14.0`](https://www.nuget.org/packages/Box.V2.Core/3.14.0)
</Update>

<Update label="2019-02-21">
  ## Windows .NET SDK v3.13.1 released

  * Fixed an issue where some objects related to Events did not have their `.Id` property correctly deserialized from JSON

  [`nuget.org/packages/Box.V2/3.13.1`](https://www.nuget.org/packages/Box.V2/3.13.1)
  [`nuget.org/packages/Box.V2.Core/3.13.1`](https://www.nuget.org/packages/Box.V2.Core/3.13.1)
</Update>

<Update label="2019-02-21">
  ## Java SDK v2.28.0 released

  1. Added Request ID to exception message with Trace ID ([#684](https://github.com/box/box-java-sdk/pull/684))
  2. user avatar feature ([#683](https://github.com/box/box-java-sdk/pull/683))
</Update>

<Update label="2019-02-15">
  ## Python SDK v2.2.1 released

  * Fixing an issue in `v2.2.0` where package could not be installed.
</Update>

<Update label="2019-02-15">
  ## Python SDK v2.2.0 released

  * Added ability for user to [retrieve an avatar](https://github.com/box/box-python-sdk/blob/master/docs/usage/user.md#get-the-avatar-for-a-user) for a user.
  * Changed retry strategy to use exponential back-off with randomized jitter.
</Update>

<Update label="2019-02-14">
  ## Windows .NET SDK v3.13.0 released

  * Added the `.InviteEmail` property to `BoxCollaboration` objects, which displays the email address for the invited
    user in a pending collaboration
  * Added `.Timezone`, `.IsExternalCollabRestricted`, `.Tags`, and `.Hostname` properties to `BoxUser` objects

  [`nuget.org/packages/Box.V2/3.13.0`](https://www.nuget.org/packages/Box.V2/3.13.0)
  [`nuget.org/packages/Box.V2.Core/3.13.0`](https://www.nuget.org/packages/Box.V2.Core/3.13.0)
</Update>

<Update label="2019-02-08">
  ## Windows .NET SDK v3.12.0 released

  * Added `client.FilesManager.GetCollaborationsCollectionAsync()` and deprecated
    `client.FilesManager.GetCollaborationsAsync()` to enable paging through the entire
    collection of collaborations on a file
  * Added `client.WebLinksManager.CopyAsync()`, `client.WebLinksManager.CreateSharedLinkAsync()`,
    and `client.WebLinksManager.DeleteSharedLinkAsync()`
  * Added `client.UsersManager.GetUserAvatarAsync()` for retrieving a user's avatar image

  [`nuget.org/packages/Box.V2/3.12.0`](https://www.nuget.org/packages/Box.V2/3.12.0)
  [`nuget.org/packages/Box.V2.Core/3.12.0`](https://www.nuget.org/packages/Box.V2.Core/3.12.0)
</Update>

<Update label="2019-02-08">
  ## Python SDK v2.1.0 released

  * Added ability for user to [chunk upload files](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#chunked-upload) and resume uploads for interrupted uploads.
  * Added ability to [verify webhook message](https://github.com/box/box-python-sdk/blob/master/docs/usage/webhook.md#validate-webhook-message)
  * Added ability for user to add metadata classification to [files](https://github.com/box/box-python-sdk/blob/master/docs/usage/files.md#set-a-classification) and [folders](https://github.com/box/box-python-sdk/blob/master/docs/usage/folders.md#set-a-classification).
  * Bug fix where calling  `.response_object()` method on an API object could throw.
</Update>

<Update label="2019-01-31">
  ## Java SDK v2.27.0 Released

  1. Metadata Classification ([#671](https://github.com/box/box-java-sdk/pull/671))
</Update>

<Update label="2019-01-18">
  ## Windows .NET SDK v3.11.0 released

  * Added support for reading and writing more Group fields
  * Fixed an issue where the `UnsharedAt` field of a shared link could not be set to `null`
  * Fixed renaming a file on new version upload
  * Added the ability to set the content modification timestamp on file version upload
  * Fixed issues around reading the source of an event when the source item is a web link

  [`nuget.org/packages/Box.V2/3.11.0`](https://www.nuget.org/packages/Box.V2/3.11.0)
  [`nuget.org/packages/Box.V2.Core/3.11.0`](https://www.nuget.org/packages/Box.V2.Core/3.11.0)
</Update>

<Update label="2019-01-18">
  ## New Sidebar UI Element & Open With Element GA

  Two major releases have been made to the Box UI Elements:

  1. New Sidebar Element: This new element provides capabilities for
     incorporating the metadata sidebar for a file directly into your own
     application or website. Documentation is available
     [here](/guides/embed/ui-elements).
  2. GA of Open With Element: The Open With element has been moved from beta to
     general availability. Open With delivers an individual button or an integration
     into the existing Content Explorer element to launch file content with Adobe
     Sign, G Suite, or Box Edit. Documentation is available
     [here](/guides/embed/ui-elements).

  Full release announcement is available [here](https://medium.com/box-developer-blog/new-sidebar-element-the-ga-of-open-with-935936a0628f).
</Update>

<Update label="2019-01-17">
  ## Java SDK v2.26.0 released

  1. add missing fields to task and folder and add ability to get fields for tasks ([#677](https://github.com/box/box-java-sdk/pull/677))
  2. Fixed typos in `README.md` ([#678](https://github.com/box/box-java-sdk/pull/678))
  3. Add `invite_email` field to collaboration object ([#672](https://github.com/box/box-java-sdk/pull/672))
</Update>

<Update label="2019-01-03">
  ## Java SDK v2.25.1 released

  1. dependency upgrade for `bouncycastle` and `jose4j` ([#669](https://github.com/box/box-java-sdk/pull/669))
</Update>


# 2020
Source: https://developer.box.com/changelog/2020

Box Platform changelog: API, SDK, and product updates from 2020.

<Update label="2020-12-14">
  ## Blank OAuth 2 redirect URI change

  On September 28th, 2020 we announced upcoming changes to our
  [security requirements for OAuth 2 app redirect URIs](/changelog/2020).
  As of today, applications that use a blank redirect URI will no longer be
  permitted, and will begin to produce an error stating `redirect_uri missing`
  when attempting to redirect the user, stating that there is a mismatched URI.

  Impacted applications will have received multiple emails to the developer email
  address associated with the application and account, and are part of a small
  subset of applications that were grandfathered in to allow the functionality to
  persist.

  New applications, or any OAuth 2 applications that have a redirect URI
  specified are not impacted.

  ## How to update your OAuth 2 app redirect URI

  If your OAuth 2 application has started to produce an error during the redirect
  phase, you may be impacted by this change. To update your application(s),
  use the following steps:

  * Go to the
    [Box developer console](https://cloud.app.box.com/developers/console) as the
    user who owns the application(s).
  * From the top navigation, click on **Configuration**.
  * Scroll down to the **OAuth 2.0 Redirect URI** section. 
  * For any application where this URI is blank, add the URI that is being used
    in the application code when redirecting the user back to your application
    from the Box auth step,
    [as is described in this guide](/guides/authentication/oauth2/with-sdk/#2-redirect-user).
</Update>

<Update label="2020-12-03">
  ## New type field in search API responses

  A new field, `type`, has been introduced in the
  [search result response object](https://developer.box.com/reference/resources/search-result-with-shared-link/) for returned shared
  link items.

  This response object format is only returned when making calls to the
  [content search](https://developer.box.com/reference/get-search/) endpoint with the
  `include_recent_shared_links` query parameter set to `true`.

  There is no impact to existing applications that are currently consuming this
  response object.

  ## Updates

  Prior to this release, the return object for shared link search results
  included two objects:

  * `accessible_via_shared_link`: The shared link which the item is accessible
    from.
  * `item`: The file, folder, or web link that matched the search query.

  ```js theme={null}
  {
    "accessible_via_shared_link": "https://www.box.com/s/vfejh7y01sb263wjtgfe",
    "item": {
      ...
    }
  }
  ```

  This update introduces the new `type` field, which is a string that will always
  be set to `search_result`.

  ```js theme={null}
  {
    "type": "search_result",
    "accessible_via_shared_link": "https://www.box.com/s/vfejh7y01sb263wjtgfe",
    "item": {
      ...
    }
  }
  ```

  For complete format information see the
  [shared link search result](https://developer.box.com/reference/resources/search-result-with-shared-link/) response object.
</Update>

<Update label="2020-12-03">
  ## Box CLI v2.8.0 released

  ## Warning

  * Due to the changes in ([#217](https://github.com/box/boxcli/pull/217)), additional details about Box Items may now be returned for some commands.

  ### New Features and Enhancements

  * Output contents of array for bulk commands ([#217](https://github.com/box/boxcli/pull/217))

  ### Bug Fixes

  * Fix bug with setting proxy settings ([#218](https://github.com/box/boxcli/pull/218))
</Update>

<Update label="2020-11-24">
  ## Box Java SDK v2.52.0 released

  ### New Features and Enhancements

  * Add folder lock functionality ([#856](https://github.com/box/box-java-sdk/pull/856))
  * Add support for search parameter to get shared link
    items ([#855](https://github.com/box/box-java-sdk/pull/855))

  ### Bug Fixes

  * Fix bug with updating tracking codes ([#857](https://github.com/box/box-java-sdk/pull/857))
</Update>

<Update label="2020-11-17">
  ## Announcing Client Credentials Grant authentication

  A new method for authenticating your JWT applications is now released.
  This new method, Client Credentials Grant, does not impact existing applications
  but offers an easier way to authenticate for new apps. Prior to today, we
  required a public/private key pair and assertion to verify an application’s
  identity and retrieve an Access Token. Now, you can request a token using only
  your client ID and client secret.

  ```cURL theme={null}
  curl --location --request POST ‘https://api.box.com/oauth2/token’ \
  --header ‘Content-Type: application/x-www-form-urlencoded’ \
  --data-urlencode ‘client_id=<client_id>’ \
  --data-urlencode ‘client_secret=<client_secret>’ \
  --data-urlencode ‘grant_type=client_credentials’ \
  --data-urlencode ‘box_subject_type=enterprise’ \
  --data-urlencode ‘box_subject_id=<enterprise_id>’
  ```

  For further information, please visit our [guide](/guides/authentication/jwt/without-sdk/#client-credentials-grant).

  ## Updates

  * Added client credentials grant as an auth option for new applications
  * Added 2FA requirement to copy/view client secret
  * Added selected authentication method in the Enterprise Authorization request
  * Removed the ability to change authentication type
</Update>

<Update label="2020-11-17">
  ## Box iOS SDK v4.2.0 released

  ## Breaking Changes

  ### New Features and Enhancements

  * Add error information for disconnected OAuth web sessions

  ### Bug Fixes

  * Fix bug with creating collaboration
  * Fix bug with getting enterprise events
</Update>

<Update label="2020-11-13">
  ## Box Java SDK v2.51.1 released

  ### Bug Fixes

  * Fix for cross-enterprise collaborator calls to `updateMetadata`
    on files
</Update>

<Update label="2020-11-13">
  ## Box Content Preview v2.57.0 released

  ### New Features and Enhancements

  * Add react versions of core control components ([#1282](https://github.com/box/box-content-preview/pull/1282))
  * Add react versions of existing control icons ([#1280](https://github.com/box/box-content-preview/pull/1280))
  * Add react versions of fullscreen and zoom controls ([#1283](https://github.com/box/box-content-preview/pull/1283))
  * Add react versions of text viewer controls ([#1284](https://github.com/box/box-content-preview/pull/1284))
  * Add instrumentation for annotation creation ([#1275](https://github.com/box/box-content-preview/pull/1275))
  * Upgrade `react` and `react-dom` to `^16.9.0` ([#1278](https://github.com/box/box-content-preview/pull/1278))

  ### Bug Fixes

  * Select newly created annotation ([#1276](https://github.com/box/box-content-preview/pull/1276))
  * Allow download of files via embedded links in Chrome ([#1277](https://github.com/box/box-content-preview/pull/1277))
  * Revert `pdf.js` to `v2.2.228` due to font rendering issue ([#1274](https://github.com/box/box-content-preview/pull/1274))
</Update>

<Update label="2020-11-09">
  ## Simplified App Creation Flow

  A new, simplified app creation flow is now available in the Box
  [Developer Console](https://app.box.com/developers/console). The three
  types of applications are Custom Apps, Limited Access Apps, and Box Custom
  Skills.

  We added plain language to describe exactly when to select each
  app type and links to relevant documentation if you require additional
  information to help with your selection. The application type you select impacts
  which authentication methods are available.

  Most notably, is our new app type, Limited Access Apps. Select this app type if
  you'd like to leverage [Box View](/guides/embed/box-view/) or Box's preview services
  within another application. This app type only provides access to
  [app token authentication](/guides/authentication/app-token/), which has
  [restricted API capabilities](/guides/authentication/app-token/endpoints/).
  For full details, please visit our [guide](/guides/applications/platform-apps/index/) on
  selecting an app type.
</Update>

<Update label="2020-11-04">
  ## Box CLI v2.7.0 released

  ### New Features and Enhancements

  * Make commands `collaborations:add`, `shared-links:update`, `shared-links:delete`, `users:search` that were previously hidden, now available ([#211](https://github.com/box/boxcli/issues/211))
  * Add `filter_term` parameter to `groups:list` ([#210](https://github.com/box/boxcli/issues/210))

  ### Bug Fixes

  * Fix bug with setting proxy settings ([#213](https://github.com/box/boxcli/issues/213))
</Update>

<Update label="2020-11-02">
  ## Box Node SDK v1.35.0 released

  ### New Features and Enhancements

  * Add support for search parameter to get shared link items ([#547](https://github.com/box/box-node-sdk/issues/547))
</Update>

<Update label="2020-10-29">
  ## Box Java SDK v2.51.0 released

  ### New Features and Enhancements

  * Add support for `copyInstanceOnItemCopy` field for metadata templates ([#850](https://github.com/box/box-java-sdk/pull/850))
  * Add support for more fields in `BoxCollaborator.Info` ([#843](https://github.com/box/box-java-sdk/pull/843))

  ### Bug Fixes

  * Update `getAllGroupsByName()` to use documented parameter ([#851](https://github.com/box/box-java-sdk/pull/851))
</Update>

<Update label="2020-10-26">
  ## New Folder Lock APIs now available

  A new collections of APIs have been released to allow developers to lock move
  and delete operations on folders. New [API reference](/reference/post-folder-locks) and
  [guides](/guides/folders/single/create-lock) have been made available to help create and manage you folder
  locks.

  To create a lock on a folder to prevent it from being moved or deleted, supply
  the ID of a folder to the `folder_locks` endpoint.

  ```curl theme={null}
  curl -i -X POST "https://api.box.com/2.0/folder_locks" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "Content-Type: application/json" \
       -d '{
         "folder": {
           "type": "folder",
           "id": "33552487093"
         }
       }'
  ```

  Additional API endpoints are available to allow a developer to list all locks
  on a given folder, or to delete an existing folder lock with a folder lock ID.

  * **Create a folder lock**: [Guide](/guides/folders/single/create-lock) | [API Reference](/reference/post-folder-locks)
  * **List all locks on a folder**: [Guide](/guides/folders/single/get-locks) | [API Reference](/reference/get-folder-locks)
  * **Delete a folder lock**: [Guide](/guides/folders/single/delete-lock) | [API Reference](/reference/delete-folder-locks-id)
</Update>

<Update label="2020-10-22">
  ## New Folder Lock APIs now available

  A new collections of APIs have been released to permit the restriction of move
  and delete actions on folders. New [API reference](/reference/post-folder-locks) and [guides](/guides/folders/single/create-lock)
  have been made available to help create and manage you folder locks.

  To create a lock on a folder to prevent it from being moved or deleted, supply
  the ID of a folder to the `POST /folder_locks/` endpoint.

  ```curl theme={null}
  curl -i -X POST "https://api.box.com/2.0/folder_locks" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -H "Content-Type: application/json" \
       -d '{
         "folder": {
           "type": "folder",
           "id": "33552487093"
         }
       }'
  ```

  Additional API endpoints are available to allow a developer to list all locks
  on a given folder, or to remove an existing folder lock from a folder.

  * **Create a folder lock**: [Guide](/guides/folders/single/create-lock) | [API Reference](/reference/post-folder-locks)
  * **List all locks on a folder**: [Guide](/guides/folders/single/get-locks) | [API Reference](/reference/get-folder-locks)
  * **Remove a folder lock**: [Guide](/guides/folders/single/delete-lock) | [API Reference](/reference/delete-folder-locks-id)
</Update>

<Update label="2020-10-21">
  ## Metadata Cascade Policies API leaves Beta

  The [Metadata Cascade Policies API](/reference/post-metadata-cascade-policies) is now generally available to all
  and no longer in Beta.

  Over the past years, we've made a lot of technical improvements to our metadata
  infrastructure and we're happy to announce that we've now gotten to the moment
  where the Metadata Cascade Policies API is leaving Beta. This release does not
  involve any breaking changes and any existing application should not see any
  impact from this release.

  Since we initially launched, Metadata Cascade Policies has become over 10 times
  faster when applying metadata to new instances. Additionally, we've also made
  significant strides in reliability and observability to ensure a top-notch API
  experience, in line with the rest of our API suite.

  For more details about metadata, and metadata cascade policies, please visit the
  [Metadata guides](/guides/metadata) and our dedicated [Metadata Cascade Policies](/reference/post-metadata-cascade-policies)
  reference documentation.
</Update>

<Update label="2020-10-19" description="Box Windows SDK v3.25.0 released">
  ## Box Windows SDK v3.25.0 released

  ### New Features and Enhancements

  * Add support for filtering when getting Groups ([#703](https://github.com/box/box-windows-sdk-v2/issues/703))
  * Add zip functionality ([#700](https://github.com/box/box-windows-sdk-v2/issues/700))
  * Deprecate one of the overloaded `ExecuteMetadataQueryAsync()` methods ([#699](https://github.com/box/box-windows-sdk-v2/issues/699))
  * Add support for `copyInstanceOnItemCopy` field for metadata templates  ([#698](https://github.com/box/box-windows-sdk-v2/issues/698))

  ### Bug Fixes

  * Fix bug with JWT Authentication automatic retry ([#697](https://github.com/box/box-windows-sdk-v2/issues/697))

  [`www.nuget.org/packages/Box.V2/3.25.0`](https://www.nuget.org/packages/Box.V2/3.25.0)
  [`www.nuget.org/packages/Box.V2.Core/3.25.0`](https://www.nuget.org/packages/Box.V2.Core/3.25.0)
</Update>

<Update label="2020-10-08">
  ## Search API adds support for Shared Links

  The [Search API](/reference/get-search) now supports returning files,
  folders and web links that the user has recently accessed
  through a shared link.

  Shared items can be requested by calling the
  [`GET /search`](/reference/get-search) API with the new
  `include_recent_shared_links` query parameter set to `true`.

  ```sh theme={null}
  curl -i -X GET https://api.box.com/2.0/search?query=Contract&include_recent_shared_link=true
  ```

  By default, the API won't return any shared items if this
  query parameter is not provided or not set to true.

  ## Change in response format

  When `include_recent_shared_links` is set to `true`, the
  response has slightly changed to allow for the additional
  information to be returned. Rather than returning a direct list
  of files, folders, and web links the API now returns a list of
  objects containing an `item` and an `accessible_via_shared_link`
  property.

  <Tabs>
    <Tab title="With shared link results">
      ```json theme={null}
      {
        "entries": [
          {
            "item": {
              "id": 12345,
              "etag": 1,
              "type": "file",
              "sequence_id": 3,
              "name": "Contract.pdf",
              ...
            },
            "accessible_via_shared_link": "https://www.box.com/s/vspke7y05sb214wjokpk"
          }
          ...
        ],
        "limit": 1000,
        "offset": 2000,
        "total_count": 5000
      }
      ```
    </Tab>

    <Tab title="Without">
      ```json theme={null}
      {
        "entries": [
          {
            "id": 12345,
            "etag": 1,
            "type": "file",
            "sequence_id": 3,
            "name": "Contract.pdf",
            ...
          },
          ...
        ],
        "limit": 1000,
        "offset": 2000,
        "total_count": 5000
      }
      ```
    </Tab>
  </Tabs>

  This change in response format should not impact any existing applications
  as it only applies to any API call made with the new query parameter.
</Update>

<Update label="2020-10-05">
  ## Box Node SDK v1.34.3 released

  ### Bug Fixes

  * Upgrade `ajv` dependency ([#545](https://github.com/box/box-node-sdk/issues/545))
</Update>

<Update label="2020-10-02">
  ## New File Request APIs available

  A new collection of APIs are now available that allows
  developers to create and update File Requests. We've
  updated the [reference documentation](/reference/post-file-requests-id-copy) and added
  [new guides](/guides/file-requests) to help you manage your file requests.

  To create a copy of an existing file request, all you need is
  the unique ID of an existing file request, and the ID of the
  folder to apply the new request to.

  ```curl theme={null}
  curl -i -X POST "https://api.box.com/2.0/file_requests/42037322/copy" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
         "folder": {
           "id": "2233212"
         }
       }'
  ```

  Additional APIs are available that allow a developer to get more details
  about a file request, update a file request, and delete a file request.
  For more details, please check out the developer documentation.

  * **Create a template file request**: [Guide](/guides/file-requests/template)
  * **Create a copy of a file request**: [Guide](/guides/file-requests/copy) | [API Reference](/reference/post-file-requests-id-copy)
  * **Get information about a file request**: [Guide](/guides/file-requests/get) | [API Reference](/reference/get-file-requests-id)
  * **Update a file request's configuration**: [Guide](/guides/file-requests/update) | [API Reference](/reference/put-file-requests-id)
  * **Delete a file request**: [Guide](/guides/file-requests/delete) | [API Reference](/reference/delete-file-requests-id)
</Update>

<Update label="2020-10-02">
  ## Box Python SDK v2.10.0 released

  ### New Features and Enhancements

  * Add support for `copyInstanceOnItemCopy` field for metadata templates ([#546](https://github.com/box/box-ios-sdk/pull/546))
  * Allow creating tasks with the `action` and `completion_rule` parameters ([#544](https://github.com/box/box-ios-sdk/pull/544))
  * Add Zip functionality ([#539](https://github.com/box/box-ios-sdk/pull/539))

  ### Bug Fixes

  * Fix bug with updating a collaboration role to owner ([#536](https://github.com/box/box-ios-sdk/pull/536))
  * Allow `ints` to be passed in as item IDs ([#530](https://github.com/box/box-ios-sdk/pull/530))
</Update>

<Update label="2020-10-29">
  ## Change to OAuth 2 app redirect URI requirements

  On October 29th, 2020, Box will begin employing stricter requirements for
  redirect URIs used within new and existing
  [OAuth 2](/guides/authentication/oauth2/)-based Box integrations that may affect
  your application.

  Existing application owners that currently use a blank redirect URI in their
  application configuration, as
  [described here](/guides/authentication/oauth2/oauth2-setup/#redirect-uri), will
  need to update the redirect URI to match the redirect used within the code
  redirect step,
  [described here](/guides/authentication/oauth2/with-sdk/#2-redirect-user).

  On October 29th, 2020, applications that are still configured with a blank URI
  will begin returning an error when the user is redirected back to your
  application if URI adjustments aren't made.

  All impacted application owners and collaborators have been notified via
  the email address associated with their developer account.

  ## How to validate and make the change

  To validate your redirect URI and update your application(s) if they are
  affected, take the following steps:

  * Go to the
    [Box developer console](https://cloud.app.box.com/developers/console) as the
    user who owns the application(s).
  * For each **Custom App** using **OAuth 2** (client-side authentication) click
    on the application to open it.
  * From the left navigation, click on **Configuration**.
  * Scroll down to the **OAuth 2.0 Redirect URI** section. 
  * For any application where this URI is blank, add the URI that is being used
    in the application code when redirecting the user back to your application
    from the Box auth step,
    [as is described in this guide](/guides/authentication/oauth2/with-sdk/#2-redirect-user).
</Update>

<Update label="2020-09-25">
  ## Search API adds support for Shared Links

  The [Search API](/reference/get-search) now supports returning files,
  folders and web links that the user has recently accessed
  through a shared link.

  Shared items can be requested by calling the
  [`GET /search`](/reference/get-search) API with the new
  `include_recent_shared_links` query parameter set to `true`.

  ```sh theme={null}
  curl -i -X GET https://api.box.com/2.0/search?query=Contract&include_recent_shared_link=true
  ```

  By default, the API won't return any shared items if this
  query parameter is not provided or not set to true.

  ## Change in response format

  When `include_recent_shared_links` is set to `true`, the
  response has slightly changed to allow for the additional
  information to be returned. Rather than returning a direct list
  of files, folders, and web links the API now returns a list of
  objects containing an `item` and an `accessible_via_shared_link`
  property.

  <Tabs>
    <Tab title="With shared link results">
      ```json theme={null}
      {
        "entries": [
          {
            "item": {
              "id": 12345,
              "etag": 1,
              "type": "file",
              "sequence_id": 3,
              "name": "Contract.pdf",
              ...
            },
            "accessible_via_shared_link": "https://www.box.com/s/vspke7y05sb214wjokpk"
          }
          ...
        ],
        "limit": 1000,
        "offset": 2000,
        "total_count": 5000
      }
      ```
    </Tab>

    <Tab title="Without">
      ```json theme={null}
      {
        "entries": [
          {
            "id": 12345,
            "etag": 1,
            "type": "file",
            "sequence_id": 3,
            "name": "Contract.pdf",
            ...
          },
          ...
        ],
        "limit": 1000,
        "offset": 2000,
        "total_count": 5000
      }
      ```
    </Tab>
  </Tabs>

  This change in response format should not impact any existing applications
  as it only applies to any API call made with the new query parameter.
</Update>

<Update label="2020-09-10">
  ## Group API adds new filter and permissions

  The [`GET /groups`](/reference/get-groups) API now supports
  filtering groups by name using a new `filter_term` field.

  ```curl theme={null}
  curl -i -X GET "https://api.box.com/2.0/groups?filter_term=Engineering" \
       -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  Additionally, all the Group endpoints now allow a developer to request
  a new
  [`permissions`](/reference/groups-resources#group-full)
  field, which currently has one attribute defining
  if the authenticated user can invite the group to any item.

  ```curl theme={null}
  curl -i -X GET "https://api.box.com/2.0/groups?field=permissions" \
       -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ```json theme={null}
  {
      "total_count": 1,
      "entries": [
          {
              "type": "group",
              "id": "223353242",
              "permissions": {
                  "can_invite_as_collaborator": true
              }
          }
      ],
      "limit": 100,
      "offset": 0
  }
  ```

  For more details about how to work with groups, please visit the
  [`Group API documentation`](/reference/get-groups).
</Update>

<Update label="2020-08-25">
  ## New multiSelect metadata support in search API

  Starting today, the [Search API](/reference/get-search) adds support for matching items
  by multiple values of a [`multiSelect` metadata field](/guides/metadata/fields/multi-select). Before this
  change, it was not possible to find items by the value of a `multiSelect` field.

  To perform a search for items where a metadata field matches
  multiple values, the `mdfilters` parameter now supports a list of values.

  ```curl theme={null}
  curl -G 'https://api.box.com/2.0/search' \
       -H 'Authorization: Bearer <ACCESS_TOKEN>' \
       -d 'mdfilters=[{"scope":"enterprise_12345","templateKey":"contractInfo","filters":{"products":["shield","platform")]}}]'
  ```

  In this example, the `mdfilters` query parameter contains one filter with a
  `scope`, a `templateKey`, and a set of `filters`. Here is the same filter
  in a more readable format.

  ```json theme={null}
  [
    {
      "scope": "enterprise_12345",
      "templateKey": "contractInfo",
      "filters": {
        "products": [
          "shield",
          "platform"
        ]
      }
    }
  ]
  ```

  What is new here is that the `products` filter now performs a match on multiple
  values, only returning files and folders for which the template has a `products`
  value of either `shield` or `platform`. The value of the field can contain
  multiple values and only match on one of the values specified in the filter.
  For example `["shield", "governance"]` will be a match for the filter
  `["shield", "platform"]` as `shield` is included in the filter.
</Update>

<Update label="2020-08-21">
  ## Box CLI v2.6.0 released

  [CHANGELOG](https://github.com/box/boxcli/blob/master/CHANGELOG.md#260-2020-08-20)

  * Add zip functionality ([#203](https://github.com/box/boxcli/issues/203)) [`1953639`](https://github.com/box/boxcli/commit/1953639fe78def22e9c9d392e784577fc089f842)
  * Add proxy support for `http`, `https`, `socks` and `pac` protocols. Proxy settings can be found under `box configure:settings` ([#202](https://github.com/box/boxcli/issues/202)) [`21671c8`](https://github.com/box/boxcli/commit/21671c854a3fe835eb46df6e640fa2237d23a313)
  * Fix filename issue when saving reports on Windows ([#195](https://github.com/box/boxcli/issues/195)) [`31853d3`](https://github.com/box/boxcli/commit/31853d30e9e20a1dc6967a8277fa38165ca671f4)

  [https://github.com/box/boxcli/compare/v2.5.1...v2.6.0](https://github.com/box/boxcli/compare/v2.5.1...v2.6.0)
</Update>

<Update label="2020-08-20">
  ## Box Node SDK v1.34.2 released

  * Make iterator bug fix for uploading files non breaking ([#534](https://github.com/box/box-node-sdk/issues/534)) [`b0baa18`](https://github.com/box/box-node-sdk/commit/b0baa18ef6d9dab99fd1db5b898d2cce46e5521d)

  [https://github.com/box/box-node-sdk/compare/v1.34.1...v1.34.2](https://github.com/box/box-node-sdk/compare/v1.34.1...v1.34.2)
</Update>

<Update label="2020-08-20">
  ## Box Java SDK v2.50.1 released

  Fix bug that occurred when downscoping a token for a Box folder ([#832](https://github.com/box/box-java-sdk/issues/832))
</Update>

<Update label="2020-08-17">
  ## Box Node SDK v1.34.1 released

  * Fix iterator bug for uploading new file versions ([#531](https://github.com/box/box-node-sdk/issues/531)) [`69b1387`](https://github.com/box/box-node-sdk/commit/69b138746c64ac8ee68b421853ca9ff4cc28531e)

  [https://github.com/box/box-node-sdk/compare/v1.34.0...v1.34.1](https://github.com/box/box-node-sdk/compare/v1.34.0...v1.34.1)
</Update>

<Update label="2020-08-07">
  ## Box Node SDK v1.34.0 released

  * Add zip functionality ([#525](https://github.com/box/box-node-sdk/issues/525)) [`2f89357`](https://github.com/box/box-node-sdk/commit/2f893577fd06dcac449ac9bfeb72cd76e1e839ae)
  * Add proxy support for HTTP, HTTPS, SOCKS and PAC protocols ([#529](https://github.com/box/box-node-sdk/issues/529)) [`b08cc24`](https://github.com/box/box-node-sdk/commit/b08cc24f240075fb24d9e5827f50ec9e26eeebc8)

  [https://github.com/box/box-node-sdk/compare/v1.33.0...v1.34.0](https://github.com/box/box-node-sdk/compare/v1.33.0...v1.34.0)
</Update>

<Update label="2020-07-30">
  ## Updates to Search Relevance & Performance

  In January, updates were released to Box's search [tokenizer](https://en.wikipedia.org/wiki/Lexical_analysis#Tokenization),
  improving the relevancy of search results and performance. This change does not
  effect how metadata is tokenized.

  Notable changes to the API-initiated searches include:

  * The ability to use "[stop words](https://en.wikipedia.org/wiki/Stop_words)", for example ("the"), ("is"),
    ("at"), ("which"), and ("on").
  * Improved Japanese text tokenization and improved search results.

  See the [full-text search](/guides/search) documentation for more
  information on how to search using Box's API.
</Update>

<Update label="2020-07-22">
  ## New Zip Download APIs available

  A new collection of APIs are now available that allows developers to create a
  Zip file containing a specified list of files and folders. We've updated the
  reference documentation for this [Zip Download API](/reference/post-zip-downloads). SDK
  support for these new endpoints is currently in development and scheduled
  to be released in the next 3 months.
</Update>

<Update label="2020-07-22">
  ## Box Java SDK v2.50.0 released

  1. Add retries on request creation errors ([#828](https://github.com/box/box-java-sdk/issues/828))
</Update>

<Update label="2020-07-21">
  ## Box Windows SDK v3.24.0 released

  See [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3240-2020-07-21) for details.

  Commits: [https://github.com/box/box-windows-sdk-v2/compare/v3.23.0...v3.24.0](https://github.com/box/box-windows-sdk-v2/compare/v3.23.0...v3.24.0)

  [`nuget.org/packages/Box.V2/3.24.0`](https://www.nuget.org/packages/Box.V2/3.24.0)
  [`nuget.org/packages/Box.V2.Core/3.24.0`](https://www.nuget.org/packages/Box.V2.Core/3.24.0)
</Update>

<Update label="2020-07-17">
  ## Box Java SDK v2.49.0 released

  1. Add `fields` parameter for metadata query ([#826](https://github.com/box/box-java-sdk/issues/826))
  2. Add zip functionality ([#825](https://github.com/box/box-java-sdk/issues/825))
  3. Fix bug with setting the unshared at date for a shared link ([#819](https://github.com/box/box-java-sdk/issues/819))
</Update>

<Update label="2020-07-16">
  ## Change to enterprise events for content access

  Starting today, the [enterprise event stream](/guides/events/enterprise-events/for-enterprise/) will
  begin producing new content access events.

  A new `CONTENT_ACCESS` event is triggered when a file was accessed by an
  authorized user or programmatically by a Box application.

  See the [enterprise events](/guides/events/enterprise-events/for-enterprise/) documentation
  for more information on other event types.
</Update>

<Update label="2020-07-15">
  ## Changes to Metadata Query API syntax

  The [Metadata Query API](/guides/metadata/queries) has been updated to **require explicitly
  defined response fields**.

  ```curl theme={null}
  curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
        -H 'Authorization: Bearer <ACCESS_TOKEN>" '
        -H 'Content-Type: application/json'
        -d '{
          "from": "enterprise_123456.customerInfo",
          "query": "tav >= :value",
          "query_params": {
            "value": 200000
          },
          "fields": [
            "name",
            "metadata.enterprise_123456.customerInfo.tav"
         ],
          "ancestor_folder_id": "0"
        }'
  ```

  Additionally, **the response format now returns a list of items** rather
  than a list of query results. Any metadata is now nested within the item,
  rather than listed side-by-side with the item. Only fields specified in the
  `field` array - as well as any base fields - are returned in the response.

  ```json theme={null}
  {
    "entries": [{
      "id": "394384323",
      "type": "file",
      "etag": 1,
      "name": "Contract.pdf",
      "metadata": {
        "enterprise_123456": {
          "customerInfo": {
            "$parent": "folder_12345,",
            "$scope": "enterprise_123456",
            "$template": "customerInfo",
            "$version": 1,
            "tav": 1000000
          }
        }
      }
    }]
  }
  ```

  ## Legacy syntax

  For reference, the API would previously return all standard fields for an item
  as well as the matched metadata.

  ```curl theme={null}
  curl -X POST https://api.box.com/2.0/metadata_queries/execute_read \
        -H 'Authorization: Bearer <ACCESS_TOKEN>" '
        -H 'Content-Type: application/json'
        -d '{
          "from": "enterprise_123456.customerInfo",
          "query": "tav >= :value",
          "query_params": {
            "value": 200000
          },
          "ancestor_folder_id": "0"
        }'
  ```

  The response body previously returned the items as a list of entries, each
  containing an `item` and a `metadata` instance.

  ```json theme={null}
  {
    "entries":[
      {
        "item":{
          "type":"file",
          "id":"394384323",
          "name": "Contract.pdf",
          "file_version":{
            "type":"file_version",
            "id":"33482348",
            "sha1":"69888bb1bff455d1b2f8afea75ed1ff0b4879bf6"
          },
          ...
        },
        "metadata":{
          "enterprise_123456":{
            "customerInfo":{
              "tav": 1000000,
              "$id": "01234500-12f1-1234-aa12-b1d234cb567e",
              "$parent": "folder_12345,",
              "$scope": "enterprise_123456",
              "$template": "customerInfo",
              "$type": "customerInfo-6bcba49f-ca6d-4d2a-a758-57fe6edf44d0",
              "$typeVersion": 2,
              "$version": 1,
              "$canEdit": true
            }
          }
        }
      },
      ...
    ],
    "limit": 20,
    "next_marker":"AAAAAmVYB1FWec8GH6yWu2nwmanfMh07IyYInaa7DZDYjgO1H4KoLW29vPlLY173OKsci6h6xGh61gG73gnaxoS+o0BbI1/h6le6cikjlupVhASwJ2Cj0tOD9wlnrUMHHw3/ISf+uuACzrOMhN6d5fYrbidPzS6MdhJOejuYlvsg4tcBYzjauP3+VU51p77HFAIuObnJT0ff"
  }
  ```

  This legacy syntax **will still be available for any existing Metadata Query API
  users only**. The legacy syntax will be turned off When all existing customers
  have been migrated over to the new syntax.
</Update>

<Update label="2020-06-25">
  ## Box Node SDK v1.33.0 released

  * Add path parameter sanitization ([#505](https://github.com/box/box-node-sdk/issues/505)) [`46b780a`](https://github.com/box/box-node-sdk/commit/46b780a577999262f09f167c577471275c066609)
  * Add support for all streams for uploading files ([#519](https://github.com/box/box-node-sdk/issues/519)) [`93a27ec`](https://github.com/box/box-node-sdk/commit/93a27ec8a5cdf4cb23d16d322e1e884913472239)

  [https://github.com/box/box-node-sdk/compare/v1.32.0...v1.33.0](https://github.com/box/box-node-sdk/compare/v1.32.0...v1.33.0)
</Update>

<Update label="2020-06-24">
  ## Box Java SDK v2.48.0 released

  `v2.48.0`

  1. Add ability to get groups by name with fields option ([#789](https://github.com/box/box-java-sdk/issues/789))
  2. Add shared link downscoping ([#785](https://github.com/box/box-java-sdk/issues/785))
  3. Deprecate the use of float for Metadata values, in preference of the underlying value (double) ([#811](https://github.com/box/box-java-sdk/issues/811))
  4. Add iterator support for group collaborations ([#813](https://github.com/box/box-java-sdk/issues/813))
  5. Add ability to set the filename when uploading a new version of a file ([#810](https://github.com/box/box-java-sdk/issues/810))
  6. Add support for the classification field for Files and Folders ([#809](https://github.com/box/box-java-sdk/issues/809))
  7. Add support for setting Tracking Codes ([#766](https://github.com/box/box-java-sdk/issues/766))
  8. Fix issue for `getIsExternallyOwned()` for Files and Folders ([#808](https://github.com/box/box-java-sdk/issues/808))
</Update>

<Update label="2020-06-23">
  ## Box Python SDK v2.9.0 released

  * Fix exception handling for OAuth
  * Fix path parameter sanitization
</Update>

<Update label="2020-06-11">
  ## Change to enterprise events for tasks

  Starting today, the [enterprise event stream](/guides/events/enterprise-events/for-enterprise/) will
  begin producing new task and task assignment events, and some existing task
  events will return additional fields.

  ## New events

  * A new `TASK_UPDATE` event is triggered when a task is updated
  * A new `TASK_ASSIGNMENT_DELETE` event is triggered when a task is unassigned
    from a user

  ## Updated events

  ### Changes to `TASK_CREATE`

  When a task is created, the event now includes the task's ID (`task.id`), the ID
  of the user who created the task (`task.created_by.id`), the task's description
  (`task.message`), and the optional due date of the task  (`task.due_date`)
  within the `additional_details` object.

  ```json theme={null}
  "additional_details": {
    "task": {
      "id": "1234567",
      "due_at": "2020-07-06T10:49:44-07:00",
      "message": "task description",
      "created_by": {
        "id": 123456,
        "login": "email@example.com"
      },
      ...
    }
  }
  ```

  ### Changes to `TASK_ASSIGNMENT_CREATE` and `TASK_ASSIGNMENT_UPDATE`

  When a task assignment is created or updated, the event now includes the task's
  ID (`task.id`), the ID of the assigned user (`task_assignment.assigned_to.id`)
  and their login (`task_assignment.assigned_to.login`), the task's description
  (`task.message`), and the optional due date of the task (`task.due_date`) within
  the `additional_details` object.

  ```json theme={null}
  "additional_details": {
    "task": {
      "id": "1234567",
      "created_by": {
        "id": 12345,
        "login": "email@example.com"
      }
    },
    "task_assignment": {
      "assigned_to": {
        "id": 12346,
        "login": "email+2@example.com"
      },
      "status": "NOT_STARTED",
      "message": "assignee message"
    },
    ...
  }
  ```

  See the [enterprise events](/guides/events/enterprise-events/for-enterprise/) documentation
  for more information on other event types.
</Update>

<Update label="2020-05-15">
  ## Box iOS SDK v4.1.0 released

  **Breaking Changes:**

  **New Features and Enhancements:**

  * Add ability to cancel uploads and downloads
  * Add support for the uploader display name field for Files and File Versions
  * Add support for the classification field for Files and Folders
  * Add path parameter sanitization

  **Bug Fixes:**

  * Fix logging of API responses
</Update>

<Update label="2020-05-12">
  ## Windows .NET SDK v3.23.0 released

  See [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3230-2020-05-12) for details
  Commits: [`v3.22.0...v3.23.0`](https://github.com/box/box-windows-sdk-v2/compare/`v3.22.0...v3.23.0`)

  [`nuget.org/packages/Box.V2/3.23.0`](https://www.nuget.org/packages/Box.V2/3.23.0)
  [`nuget.org/packages/Box.V2.Core/3.23.0`](https://www.nuget.org/packages/Box.V2.Core/3.23.0)
</Update>

<Update label="2020-05-12">
  ## New shield alert events

  As of today, [Box Shield](https://www.box.com/shield) will begin producing new security events
  within the [enterprise event stream](/guides/events/enterprise-events/for-enterprise/) for Shield
  customers who are configured to listen for the new events.

  The possible incident events produced by Shield are:

  * Suspicious locations
  * Suspicious sessions
  * Anomalous download
  * Malicious content

  See the [shield alert events](/guides/events/event-triggers/shield-alert-events/) documentation
  for more information on the payloads produced within these events.
</Update>

<Update label="2020-04-24">
  ## Python SDK v2.8.0 released

  * Added support for token exchange using shared links
  * Added the ability to pass in a SHA1 value for file uploads
</Update>

<Update label="2020-04-23">
  ## New classification field for Files

  A new optional field has been made available within the `Field` object,
  `classification`. This field represents the classification that is currently
  applied to a file.

  The classification can be requested via any endpoint that returns a file, like
  the [Get file information](/reference/get-files-id) and supports [requesting
  additional `fields`](/guides/api-calls/request-extra-fields).

  ```js theme={null}
  {
    "id": "123456789",
    "type": "file",
    "etag": "1",
    "classification": {     
      "name": "Top Secret",     
      "definition": "Content that should not be shared outside the company.",
      "color": "#FF0000"
    },
    ...
  }
  ```

  The classification can be set through the API, Box Shield, or by a user using
  the web application.
</Update>

<Update label="2020-04-23">
  ## Java SDK v2.47.0 released

  1. Fix path parameter sanitization ([#797](https://github.com/box/box-java-sdk/pull/797))
  2. Add support for the uploader display name field for Files and File version ([#791](https://github.com/box/box-java-sdk/pull/791))
</Update>

<Update label="2020-04-23">
  ## Add new uploader\_display\_name field to file and file versions

  A new field, `uploader_display_name` has been added to both file and file
  version resources. This field provides the name of the user at the time of
  upload.

  ```json theme={null}
  {
    ...
    "uploader_display_name": "Ellis Wiggins"
  }
  ```

  This field can be requested on any of the file and file
  version endpoints by providing the `fields` query parameter, for example:

  ```bash theme={null}
  curl -X GET https://api.box.com/2.0/files/12345?fields=uploader_display_name \
       -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  When the file is uploaded by a logged out anonymous, the email of the
  user is returned instead. If no email is available then the field will default
  to the text `Someone`.
</Update>

<Update label="2020-04-21">
  ## New Metadata Query APIs available

  A new API is now available that allows developers to query files and folders
  by the metadata attached to them. We've updated the reference documentation for
  this [Metadata Query API](/reference/post-metadata-queries-execute-read), as well as released some brand new
  [guides](/guides/metadata/queries) and an update to the [metadata quick start guide](/guides/metadata/quick-start).
</Update>

<Update label="2020-04-21">
  ## Box CLI v2.5.1 released

  [CHANGELOG](https://github.com/box/boxcli/blob/master/CHANGELOG.md#251-2020-04-14)

  * Added `--quiet` flag to suppress any non-error output to `stderr` ([#167](https://github.com/box/boxcli/pull/167)) [`27045c6`](https://github.com/box/boxcli/commit/27045c6)
  * Fixed a bug for the `--restrict-collaboration` flag for `box folders:update` where previously the flag would not restrict the collaborations when passed as true and would restrict collaborations when passed as false ([#175](https://github.com/box/boxcli/pull/175)) [`e6e1120`](https://github.com/box/boxcli/commit/e6e1120)
  * Added `box trash:restore` to restore a trashed item and `box trash:get` to get information on a trashed item ([#179](https://github.com/box/boxcli/pull/179)) [`74db947`](https://github.com/box/boxcli/commit/74db947)
  * Fixed a bug where flags that can be specified multiple times in a single command could not be passed through the command line for bulk commands ([#183](https://github.com/box/boxcli/pull/183)) [`63db0ac`](https://github.com/box/boxcli/commit/63db0ac)
  * **Note**: Skipped version 2.5.0 due to development of new release process

  [`v2.4.0...v2.5.1`](https://github.com/box/boxcli/compare/`v2.4.0...v2.5.1`)
</Update>

<Update label="2020-04-09">
  ## Java SDK v2.46.0 released

  1. Fix retry logic ([#787](https://github.com/box/box-java-sdk/pull/787))
  2. Add path parameter sanitization ([#790](https://github.com/box/box-java-sdk/pull/790))
  3. Add ability to set expiration date for a collaboration ([#788](https://github.com/box/box-java-sdk/pull/788))
</Update>

<Update label="2020-04-02">
  ## Java SDK v2.45.0 released

  1. Add preflight check before chunked uploads ([#782](https://github.com/box/box-java-sdk/pull/782))
  2. Check that part was successfully uploaded for large file uploads… ([#781](https://github.com/box/box-java-sdk/pull/781))
  3. Fix bug with unexpected disconnect in File Rename ([#779](https://github.com/box/box-java-sdk/pull/779))
  4. Return metadata for each item returned by a metadata query ([#778](https://github.com/box/box-java-sdk/pull/778))
</Update>

<Update label="2020-04-01">
  ## Node SDK v1.32.0 released

  * Temporarily removed Node 4 and Node 5 builds from Travis, due to tests not passing.  Will investigate, going forward ([#495](https://github.com/box/box-node-sdk/pull/495)). [`dc558e9`](https://github.com/box/box-node-sdk/commit/dc558e9)
  * Fixed an issue where an error is thrown during a retry when a response is not returned by the previous call  ([#477](https://github.com/box/box-node-sdk/pull/477)). [`f1b3449`](https://github.com/box/box-node-sdk/commit/f1b3449)
  * Added the ability to [query](https://github.com/box/box-node-sdk/blob/v1.32.0/docs/metadata.md#query) Box items based on their metadata ([#487](https://github.com/box/box-node-sdk/pull/487)). [`6f08931`](https://github.com/box/box-node-sdk/commit/6f08931)

  [`v1.31.0...v1.32.0`](https://github.com/box/box-node-sdk/compare/`v1.31.0...v1.32.0`)
</Update>

<Update label="2020-03-30">
  ## Potential impactful changes to format of Metadata date fields

  As part of ongoing improvements to our Metadata infrastructure we will be
  rolling out three potential impactful changes to the format of `date` fields in
  metadata templates. These changes make the format our API returns more
  consistent between API calls.

  The first change affects the usage of time zone offsets in dates. Previously,
  the API would inconsistently return dates with and without timezone offsets if a
  date was set to include one. From now on all dates are converted to UTC /
  Zulu-time, removing the timezone offset.

  For example:

  * Assume a date was set to `2020-02-20T12:00:00.000-01:00`
  * Previously the API would return `2020-02-20T12:00:00.000-01:00` (the original
    value) or `2020-02-20T13:00:00.000Z` (the UTC adjusted value)
  * From now on it will always return `2020-02-20T13:00:00.000Z` (the UTC adjusted
    value)

  The second change affects the sub-second precision of dates returned by the
  metadata API. Previously, the API would return values with 0 to 3 digits of
  sub-second precision. From now on Box will always return metadata date-time
  values with millisecond precision.

  For example:

  * Previously the API might return `2020-02-20T12:00:00Z`,
    `2020-02-20T12:00:00.0Z`, `2020-02-20T12:00:00.00Z`or
    `2020-02-20T12:00:00.000Z`
  * From now on it will always return `2020-02-20T12:00:00.000Z`

  The final change affects the usage of the
  [`test`](/guides/metadata/instances/update#test-a-value) operation when updating a
  metadata instance. Previously the test would compare the date-time values using
  the literal string value. After this update they are compared using their UNIX
  timestamp in milliseconds.

  For example:

  * Previously `2020-01-21T19:20:00.123-08:00` would not be equivalent to
    `2020-01-22T03:20:00.123Z`
  * From now on `2020-01-21T19:20:00.123-08:00` is equivalent to
    `2020-01-22T03:20:00.123Z`

  ## How this can affect an application

  Any application that implements `RFC3339`-compliant date-time parsing will not
  need to perform any action as these are all valid `RFC3339` values representing
  the same dates. Any application that does not implement `RFC3339` compliant
  date-time parsing should be updated to do so.

  All official Box SDKs support `RFC3339`-compliant date-time parsing, so any
  application using an up-to-date version of an official Box SDK would not require
  any update.

  ## What do if this affected your application

  Roll-out of this change will be performed gradually over the next few weeks.
  Although the metadata team will be monitoring potential impact, please reach out
  to your customer success manager or our support channels if you find yourself
  impacted.
</Update>

<Update label="2020-03-30">
  ## Change to metadata instance version

  As part of ongoing improvements to our Metadata infrastructure we will be
  rolling out a small change to the [`version`](r:/metadata/#param-\$version) value
  of a metadata Instance.

  Previously, the version number associated with a metadata instance would be
  incremented if a field on the associated metadata template was deleted, or if an
  `enum` field's option was deleted on the associated metadata template.

  Going forward, these changes will not increment the version number of a metadata
  instance.

  This behavior has always been implicit and we recognize that very little value
  can be derived form to the metadata instance version. Therefore we do not expect
  this change to have any impact on any of our customers. Regardless, please reach
  out to your customer success manager or our support channels if you find
  yourself impacted.
</Update>

<Update label="2020-02-25">
  ## Windows .NET SDK v3.22.0 Released

  See [Changelog](https://github.com/box/box-windows-sdk-v2/blob/master/CHANGELOG.md#3220-2020-02-25) for details
  Commits: [`v3.21.0...v3.22.0`](https://github.com/box/box-windows-sdk-v2/compare/`v3.21.0...v3.22.0`)

  [`nuget.org/packages/Box.V2/3.22.0`](https://www.nuget.org/packages/Box.V2/3.22.0)
  [`nuget.org/packages/Box.V2.Core/3.22.0`](https://www.nuget.org/packages/Box.V2.Core/3.22.0)
</Update>

<Update label="2020-02-14">
  ## Node SDK v1.31.0 released

  * Fix Authentication Request Retries ([#454](https://github.com/box/box-node-sdk/pull/454)) [`dd3253e`](https://github.com/box/box-node-sdk/commit/dd3253e)
  * Added marker-based paging for users endpoints ([#461](https://github.com/box/box-node-sdk/pull/461)) [`055cb5b`](https://github.com/box/box-node-sdk/commit/055cb5b)
  * Added `getNextMarker()` to `PagingIterator` to get the next marker ([#461](https://github.com/box/box-node-sdk/pull/461)) [`055cb5b`](https://github.com/box/box-node-sdk/commit/055cb5b)

  [`v1.30.0...v1.31.0`](https://github.com/box/box-node-sdk/compare/`v1.30.0...v1.31.0`)
</Update>

<Update label="2020-02-13">
  ## Java SDK v2.44.1 Released

  1. Fix formatting bug for Java Logger ([#775](https://github.com/box/box-java-sdk/pull/775))
  2. Improve date / time parsing for responses ([#772](https://github.com/box/box-java-sdk/pull/772))
</Update>

<Update label="2020-02-13">
  ## Box iOS SDK v4.0.0 released

  **Breaking Changes:**

  * Change `status` field for task assignments from a String to an Enum
  * Remove `macOS`, `tvOS`, and `watchOS` support

  **New Features and Enhancements:**

  * Make authentication session classes `OAuth2Session`, `SingleTokenSession`, and `DelegatedAuthSession` public
</Update>

<Update label="2020-02-03">
  ## Preview SDK v2.34.0 released

  Version `2.34.0` of the Preview SDK has been released. New JavaScript and CSS
  Preview files have been made available. To adopt new changes, please see the
  [UI Elements manual installation](/guides/embed/ui-elements/installation/#manual-installation) links for Content
  Preview.

  Please see the `v2.34.0` [release notes](https://github.com/box/box-content-preview/releases/tag/v2.34.0) for a list
  of all feature changes.
</Update>

<Update label="2020-01-22">
  ## Python SDK v2.7.1 released

  * Fixed bug in `_get_retry_request_callable` introduced in release 2.7.0 which caused chunked uploads to fail
</Update>

<Update label="2020-01-22">
  ## Preview SDK v2.33.1 released

  Version `2.33.1` of the Preview SDK has been released. New JavaScript and CSS
  Preview files have been made available. To adopt new changes, please see the
  [UI Elements manual installation](/guides/embed/ui-elements/installation/#manual-installation) links for Content
  Preview.

  Please see the `v2.33.1` [release notes](https://github.com/box/box-content-preview/releases/tag/v2.33.1) for a list
  of all feature changes.
</Update>

<Update label="2020-01-21">
  ## Java SDK v2.44.0 released

  1. Fix Authentication Request Retries ([#764](https://github.com/box/box-java-sdk/pull/764))
</Update>

<Update label="2020-01-20">
  ## Refreshed Postman Collection & Quick Start

  The Box Postman collection has been updated with new features and an integrated
  quick-start guide. Key features include:

  * An end-to-end [Postman quick-start guide](/guides/tooling/postman) that
    helps users to install Postman, set up a Box App, and load their API
    credentials into Postman.
  * A [restructured Postman collection](/guides/tooling/postman) for the Box APIs that
    automatically detects when API credentials have expired and offers integrated
    solutions for refreshing these credentials when needed.

  The [legacy Postman collection](/guides/tooling/postman) will stay available
  for the foreseeable future.
</Update>

<Update label="2020-01-16">
  ## Python SDK v2.7.0 released

  * Fixed bug in `get_admin_events` function which caused errors when the optional `event_types` parameter was omitted.
  * Add marker based pagination for listing users.
  * Added support for more attribute parameters when uploading new files and new versions of existing files.
  * Combined preflight check and lookup of accelerator URL into a single request for uploads.
  * Fixed JWT retry logic so a new JTI claim is generated on each retry.
  * Fixed bug where JWT authentication requests returned incorrect error codes.
  * Fixed retry logic so when a Retry-After header is passed back from the API, the SDK waits for the amount of time specified in the header before retrying.
</Update>


# 2021
Source: https://developer.box.com/changelog/2021

Box Platform changelog: API, SDK, and product updates from 2021.

<Update label="2021-12-17">
  ## End of Support for Obsolete Language Versions

  As Box to prepares to release the next major versions of the Python and
  Java SDKs, this is an alert that support is ending for obsolete language
  versions.

  On January 17, 2022, major releases of the [Python](https://github.com/box/box-python-sdk/releases) and [Java](https://github.com/box/box-java-sdk/releases) SDK
  libraries are planned, ending support for obsolete language versions. The Python
  SDK will abandon Python 2.7 and Python 3.5 starting from version `v3.0.0` of the
  Python SDK. The Java SDK will abandon Java 7 starting from version `v3.0.0` of
  the Java SDK. Applications using the Python or Java SDK can still use the
  respective older versions of those libraries located in the [GitHub](https://github.com/box/sdks)
  release section, but any future new features will not be available for use.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed. You can also connect with the SDK
  team on the respective GitHub repository.
</Update>

<Update label="2021-12-14">
  ## Box Windows SDK v4.1.0 released

  ### Bug Fixes

  * add missing `configureAwait`(false) when awaiting to prevent deadlocks ([#775](https://github.com/box/box-windows-sdk-v2/issues/775)) ([`b16267e`](https://github.com/box/box-windows-sdk-v2/commit/b16267e8f3dca5396e87be660e30a1e9405d8139))

  ### New Features and Enhancements

  * add configurable `Timeout` for `BoxClient` ([#779](https://github.com/box/box-windows-sdk-v2/issues/779)) ([`ac842ed`](https://github.com/box/box-windows-sdk-v2/commit/ac842ed4ba1a2dfe499706524441bc6ae3b3c192))
  * add file request API ([#777](https://github.com/box/box-windows-sdk-v2/issues/777)) ([`1098f75`](https://github.com/box/box-windows-sdk-v2/commit/1098f75983e2d784521f13b8d53df0e55d03203b))
  * add `vanity_name` to `SharedLink` ([#782](https://github.com/box/box-windows-sdk-v2/issues/782)) ([`00a1e26`](https://github.com/box/box-windows-sdk-v2/commit/00a1e265569d76c2c9593aa259202d7febef629c))

  - [https://www.nuget.org/packages/Box.V2/4.1.0](https://www.nuget.org/packages/Box.V2/4.1.0)
  - [https://www.nuget.org/packages/Box.V2.Core/4.1.0](https://www.nuget.org/packages/Box.V2.Core/4.1.0)
</Update>

<Update label="2021-12-08">
  ## Box Python SDK v2.14.0 released

  ### New Features and Enhancements

  * Add `admin_logs_streaming` support for events stream ([#623](https://github.com/box/box-python-sdk/pull/623))
  * Add `vanity_name` parameter for creating shared link to a file or folder ([#637](https://github.com/box/box-python-sdk/pull/637))
  * Add getting files and file versions under retention for a retention policy assignment ([#633](https://github.com/box/box-python-sdk/pull/633))
  * Support base item operations for WebLink class ([#639](https://github.com/box/box-python-sdk/pull/639))

  ### Bug Fixes

  * Limit cryptography to version \<3.5.0 ([#636](https://github.com/box/box-python-sdk/pull/636))
  * Avoid raising 404 when a thumbnail cannot be generated for a file ([#642](https://github.com/box/box-python-sdk/pull/642))
</Update>

<Update label="2021-11-29">
  ## OAuth 2.0 Redirect URL Updates

  Today, we released a new feature to the Box Developer Console, allowing developers to add multiple redirect URIs for an OAuth 2.0 application.

  Starting November 29, 2021, new applications using OAuth 2.0 will require the
  URIs set in the configuration tab of the Developer Console to strictly match the
  one used during redirect. In addition, both new and existing applications, will
  gain the ability to add multiple redirect URIs.

  For existing applications, the deadline to make changes to this URL and avoid service
  disruption is May 13, 2022.

  ## Updates

  * The Box Developer Console OAuth 2.0 application configuration section has a new button to add multiple redirect URIs
  * Redirect URIs now force strict checking to match the URI passed in and URIs configured in the OAuth 2.0 application configuration
  * Updated the `redirect_uri` query parameter wording on the [`GET /authorize`](/reference/get-authorize/#param-redirect_uri) endpoint page
  * Updated the OAuth 2.0 [setup](/guides/authentication/oauth2/oauth2-setup/), [with SDK](/guides/authentication/oauth2/with-sdk/), and [without SDK](/guides/authentication/oauth2/without-sdk/) guide pages

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-11-23">
  ## Box Java SDK v2.58.0 released

  ### New Features and Enhancements

  * SDK support for new GET /events `stream_type`: `admin_logs_streaming` ([#938](https://github.com/box/box-java-sdk/pull/938))
  * Adding `BoxDeveloperEditionAPIConnection#getUserConnection` to indicate that we can use this connection for managed users or app users ([#940](https://github.com/box/box-java-sdk/pull/940))

  ### Bug Fixes

  * Fix for deprecated enums still being used ([#931](https://github.com/box/box-java-sdk/issues/931))
</Update>

<Update label="2021-11-22">
  ## New Shield Download Event

  Today, we released a new `event_type` to the [Enterprise Event](/guides/events/enterprise-events/for-enterprise) stream
  for downloads that are restricted based on a Shield access policy.

  If an admin creates a shield access policy that restricts downloads and an
  end user is blocked from downloading a file, an event is produced
  within the [enterprise event](/guides/events/enterprise-events/for-enterprise) stream. Events will also be generated
  when a user is viewing a folder with a file restricted from download, viewing a
  file in preview that is restricted from download, and when a user requests to
  download a file through the API that is restricted from download. These events
  follow the standard event object schema and the `event_type` value set
  to `SHIELD_DOWNLOAD_BLOCKED`.

  ## Updates

  * Added a [new section](/guides/events/event-triggers/shield-alert-events/#download-restriction) to the Smart Access event trigger documentation
  * Added `SHIELD_DOWNLOAD_BLOCKED` to the [enterprise event list](/guides/events/enterprise-events/for-enterprise/#event-types)

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-11-17">
  ## New Event Stream Live Monitoring stream\_type

  Today, we released a new `stream_type` for the [`GET /events`](/reference/get-events)
  API called `admin_logs_streaming`. This allows for near real time monitoring of
  events after they happen in Box.

  We recommend that applications subscribing to live events through `admin_logs`
  migrate to `admin_logs_streaming` for the lowest and most consistent latency.
  This `stream_type` requires the user to be an enterprise admin or co-admin with
  the permission to **Run new reports and access existing reports**.

  ## Updates

  We have made several documentation updates to help you learn about the new option

  * Completely reorganized the [events](/guides/events) guide section for
    easier understanding, including adding additional information to all pages
    in the various sections
  * Updated the OpenAPI specification for the [`GET /events`](/reference/get-events) endpoint
    to include the new `stream_type` option of `admin_logs_streaming`
  * Added a new how to migrate [`stream_type` page](/guides/events/enterprise-events/migrate-to-stream) with steps
    on switching

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-11-16">
  ## Added Retention Policy Marker Based Pagination

  Our OpenAPI specification has been updated for retention policy and retention
  policy assignment endpoints to show use of `marker` based pagination and
  `fields` query parameters.

  ## Updates

  The following updates were made:

  * Added `fields`, `limit`, and `marker` query parameters to the
    [`GET /retention-policies`](/reference/get-retention-policies) and
    [`GET /retention-policies-id-assignments`](/reference/get-retention-policies-id-assignments)
    endpoints.
  * Added `limit` and `next_marker ` to the response object for
    [retention policies](/reference/retention-policies-resources#retention-policies) and
    [retention policy assignments](/reference/retention-policy-assignments-resources#retention-policy-assignments)

  ## Where to get support

  Should you have any issues or need further guidance, please create a post on
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-11-03">
  ## Extend Retention Via Files API

  Now, you can extend the retention date for a file that is already under
  retention using the new `disposition_at` field. If the date is extended, it
  cannot be reverted or updated to a date prior to the new date.

  ## Updates

  * Added a `disposition_at` field to the [File(Full) resource](/reference/resources/file--full/#param-disposition_at)
  * Added a `disposition_at` parameter to the [PUT file endpoint](/reference/put-files-id/#param-disposition_at)
  * Added a note in the [retention policy guide section](/guides/retention-policies/#extend-retention-for-a-file)

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-11-02" description="Box Windows SDK v4.0.0 released">
  ## Box Windows SDK v4.0.0 released

  ### Breaking changes

  * Extract interfaces for BoxClient and Managers to improve testability ([#603](https://github.com/box/box-windows-sdk-v2/pull/603))
  * Add BoxConfigBuilder and make BoxConfig immutable ([#737](https://github.com/box/box-windows-sdk-v2/pull/737))
  * Expose tasks from async methods ([#742](https://github.com/box/box-windows-sdk-v2/pull/742))
  * Use DateTimeOffset instead of DateTime ([#749](https://github.com/box/box-windows-sdk-v2/pull/749))
  * Rework returned exceptions ([#753](https://github.com/box/box-windows-sdk-v2/pull/753))
  * Upgrade .NET Standard to 2.0 ([#755](https://github.com/box/box-windows-sdk-v2/pull/755))

  ### New Features and Enhancements

  * Add ability to get files under retention for assignment and file versions under retention for assignment ([#734](https://github.com/box/box-windows-sdk-v2/pull/734))
  * Add `is_collaboration_restricted_to_enterprise` flag support for `Folder` update ([#732](https://github.com/box/box-windows-sdk-v2/pull/732))
  * Replace insensitive language ([#738](https://github.com/box/box-windows-sdk-v2/pull/738))
  * Add new, easier to use method for create terms of service user status ([#740](https://github.com/box/box-windows-sdk-v2/pull/740))
  * Allow sort and direction parameter to be passed in when getting trashed items ([#754](https://github.com/box/box-windows-sdk-v2/pull/754))
  * Add support for Task completion\_rule field ([#758](https://github.com/box/box-windows-sdk-v2/pull/758))
  * Add BoxSign API support ([#765](https://github.com/box/box-windows-sdk-v2/pull/765))

  ### Bug Fixes

  * Fix `Cannot access a closed Stream.Request` exception during upload ([#739](https://github.com/box/box-windows-sdk-v2/pull/739)) ([#757](https://github.com/box/box-windows-sdk-v2/pull/757))

  - [https://www.nuget.org/packages/Box.V2/4.0.0](https://www.nuget.org/packages/Box.V2/4.0.0)
  - [https://www.nuget.org/packages/Box.V2.Core/4.0.0](https://www.nuget.org/packages/Box.V2.Core/4.0.0)
</Update>

<Update label="2021-10-28">
  ## Box iOS SDK v5.0.0 released

  ### Breaking changes

  * Update PagingIterator to return pages and simplify logic ([#737](https://github.com/box/box-ios-sdk/pull/737))
  * Remove insensitive language field `collaborationWhiteList` in BoxClient. Use `collaborationAllowList` instead. ([#790](https://github.com/box/box-ios-sdk/pull/790))

  ### New Features and Enhancements

  * Replace insensitive event types ([#785](https://github.com/box/box-ios-sdk/pull/785))
  * Add SignAPI support ([#792](https://github.com/box/box-ios-sdk/pull/792))
</Update>

<Update label="2021-10-27">
  ## Box Sign Enterprise Events

  [Box Sign](/guides/box-sign) events are now available via the enterprise events stream.
  For full details, please see our [Box Sign events guide](/guides/events/event-triggers/sign-events).

  ## Updates

  * Add sign request [document events](/guides/events/event-triggers/sign-events/#document-events): created, converted, completed,
    cancelled and expired

  * Add sign request [signer events](/guides/events/event-triggers/sign-events/#signer-events): assigned, viewed by signer, downloaded,
    forwarded, signed and declined

  * Add two new [statuses](/reference/resources/sign-requests/#param-status): `downloaded` and `downloaded and signed`
</Update>

<Update label="2021-10-20">
  ## Box UI Elements v14.0.0 released

  ## [14.0.0](https://github.com/box/box-ui-elements/releases/tag/v14.0.0) (2021-10-20)

  ## Bug Fixes & Features

  This release fixes several bugs. For a full list, [please see the release notes](https://github.com/box/box-ui-elements/releases/tag/v14.0.0)
</Update>

<Update label="2021-10-20">
  ## App Diagnostics Report Feedback

  We recently [started releasing](/changelog/2021) the new
  [App Diagnostics Report](https://developer.box.com/guides/troubleshooting/app-diagnostics-report/) to customers, and we would love to hear your
  thoughts! Visit the [forum post](https://support.box.com/hc/en-us/community/posts/4408877038483-App-Diagnostics-Report-Feedback) to provide any feedback.
</Update>

<Update label="2021-10-18">
  ## Box Java SDK v2.57.0 released

  ### New Features and Enhancements

  * Add support for marker-based paging in `BoxFolder.getChildren` ([#927](https://github.com/box/box-java-sdk/pull/927))
  * Upgraded `minimal-json` to version 0.9.5
  * Upgraded `jose4j` to version 0.7.9
  * Adding Gradle wrapper in version 4.0.1 ([#928](https://github.com/box/box-java-sdk/pull/928))

  ### Bug Fixes:\*\*

  * Fix for infinite recursion ([#924](https://github.com/box/box-java-sdk/pull/924))
  * Fix unable to set Vanity URL on `BoxSharedLink` for `BoxFile` and `BoxFolder`
    ([#925](https://github.com/box/box-java-sdk/issues/925))
</Update>

<Update label="2021-10-07">
  ## Update to Webhooks Response

  The [webhook response](/reference/get-webhooks) has been updated to show the correct
  Webhook (Mini) object in the entries array.

  ## Bug Fixes

  * Added a `mini` resource for [Webhook](/reference/resources/webhook--mini)
  * Corrected the [get-webhooks](/reference/get-webhooks) response object
</Update>

<Update label="2021-10-07">
  ## New App Diagnostics Report

  A new report will be gradually deployed to customers starting Thursday, October
  7th, 2021. We plan to have the report released to all customers by October 25th.

  Developers can now review API activity for their applications by generating an
  App Diagnostics Report from the Developer Console. Checkout the
  [guide](/guides/troubleshooting/app-diagnostics-report) to see the steps required to run a report!

  As always, if you have issues you may file a
  [support ticket](https://developer.box.com/support) or post on our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum).
</Update>

<Update label="2021-10-06">
  ## Support for Adobe Creative Cloud Previews

  In conjunction with WebApp preview, Adobe Photoshop, Illustrator,
  and InDesign files are now supported via API.

  ## Updates

  Files with extensions `indt`, `idml`, `indd`, and `inx` are supported by:

  * [Thumbnails](/guides/representations/thumbnail)
  * [Image Viewer UI Element](/guides/embed/ui-elements/viewers-and-events/#image-viewer)
  * [Annotations](/guides/embed/ui-elements/annotations)
  * [Thumbnail Representation](/guides/representations/thumbnail-representation)
</Update>

<Update label="2021-09-30">
  ## Box Python SDK v2.13.0 released

  ### New Features and Enhancements

  * Sensitive language replacement ([#609](https://github.com/box/box-python-sdk/pull/609))
  * Add BoxSign support ([#617](https://github.com/box/box-python-sdk/pull/617))

  ### Bug Fixes

  * Upgrade cryptography to version 3 ([#620](https://github.com/box/box-python-sdk/pull/620))
</Update>

<Update label="2021-09-29">
  ## Box Node SDK v2.0.0 released

  ### Breaking changes

  * Drop support for Node 6,7 ([#670](https://github.com/box/box-node-sdk/pull/670))

  ### New Features and Enhancements

  * Add support for `is_external_collab_restricted` User property ([#668](https://github.com/box/box-node-sdk/pull/668))
  * Bump proxy-agent from 4.0.0 to 5.0.0 ([#664](https://github.com/box/box-node-sdk/pull/664))
</Update>

<Update label="2021-12-21">
  ## EOS for Open With UI Element and EOL for Adobe Sign

  Today, the [Open With UI element](/guides/embed/ui-elements/open-with) can integrate with Box Tools, Google
  Workspace, and Adobe Sign. In an effort to continuously improve the Box
  experience, we are focusing our resources on new features and functionality that
  better align with our users' evolving needs.

  December 21, 2021 the following changes will occur:

  * We will discontinue support of the Box Open With UI Element for Box Tools and
    Google Workspace for any new customers. A new customer is any customer not using
    this element prior to December 21. Any customers leveraging the Open With UI
    Element with Box Tools and/or Google Workspace prior to December 21 are
    considered existing customers and will continue to receive support until further
    notice. The Box Tools and Google Workspace Web App functionality will not be
    impacted.

  * Adobe Sign will no longer be available for use by new or existing customers
    via the Open With UI element or Web Application.

  Should you have any further questions, please contact us by opening a
  [support](https://developer.box.com/support) ticket or posting on the [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum).
</Update>

<Update label="2021-09-07">
  ## New enhancements to retention APIs

  Two new API endpoints have been introduced to get files and file versions that
  are under retention for a given retention policy assignment. These APIs are
  part of the [retention policy](/guides/retention-policies) suite of APIs. They are
  intended to replace the separate [file](/reference/get-file-version-retentions-id) and [file version](/reference/get-file-version-retentions)
  retention endpoints, which will soon be deprecated from the Box API. The date
  of the deprecation will be announced at a later date.

  When a retention policy is applied via a retention policy assignment, folders
  are selected for which the retention policy should be applied. The files and
  file versions within those folders will be the content that is returned from
  calling these new endpoints.

  ## Features

  This release has introduced the following new content and features.

  * [Get files under retention](/reference/get-retention-policy-assignments-id-files-under-retention): Returns a list of files under
    retention that are associated with the specified retention policy assignment.
  * [Get file versions under retention](/reference/get-retention-policy-assignments-id-file-versions-under-retention): Returns a list
    of file versions under retention that are associated with the specified
    retention policy assignment.
  * Added an editable `description` field to the
    [retention policy](/reference/resources/retention-policy) resource.
  * Added a non-writable `start_field_date` to the
    [retention policy assignment](/reference/resources/retention-policy-assignment)
    resource. This field is the metadata field's key id. The value can also be
    `upload_date` if the `assigned_to` type is not `metadata_template` or a date
    field has not been selected.
</Update>

<Update label="2021-09-01">
  ## Classification Name Field now in Events API

  If a classification exists on content, the [events](/reference/get-events/) API now
  returns the classification `name` field in the response object.

  * The updates to the event source response object can be
    seen [here](/reference/resources/event-source/).
  * A new [guide page](/guides/events/event-triggers/event-source) has been added to show examples for an
    event triggered by a user source and an event source.

  Below is an example of the response before and after the enhancement. Please
  note that if a classification doesn't exist, the before example will still
  be returned.

  Before:

  ```js theme={null}
  {
    "source": {
      "item_type": "file",
      "item_id": "8903212345",
      "item_name": "example.docx",
      "parent": {
        "type": "folder",
        "name": "All Files",
        "id": "0"
      },
      "owned_by": {
        "type": "user",
        "id": "11446498",
        "name": "Aaron Levie",
        "login": "notifications@example.com"
      }
    }
  }
  ```

  After:

  ```js theme={null}
  {
    "source": {
      "item_type": "file",
      "item_id": "8903212345",
      "item_name": "example.docx",
      "parent": {
        "type": "folder",
        "name": "All Files",
        "id": "0"
      },
      "owned_by": {
        "type": "user",
        "id": "11446498",
        "name": "Aaron Levie",
        "login": "notifications@example.com"
      },
      "classification": {
        "name": "Top Secret"
      }
    }
  }
  ```

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-08-31">
  ## Notice of behavior change for item preview events

  Starting today, we will begin rolling out changes to the behavior
  of item preview events when an application consumes those events from our
  [event API endpoints](https://developer.box.com/reference/get-events/).

  This change will only affect the
  `ITEM_PREVIEW` [user event](https://developer.box.com/guides/events/enterprise-events/for-user/#event-types) and will not affect existing
  [enterprise events](https://developer.box.com/guides/events/enterprise-events). The new behavior will not cause
  downtime within existing applications or require any application changes to
  prevent uptime disruptions.

  ## Change overview

  Within the previous behavior when events were consumed, previewed item
  events were surfaced through the `ITEM_PREVIEW` event type for the owner of
  the content as well as any contributors assigned to the content. This meant
  that if a file with 2000 collaborators on it was previewed, the file owner
  plus all 2000 collaborators would have an event created stating that the file
  was previewed.

  With the new behavior, notification of an item being previewed will only be
  created for the owner of the content and will not be produced for
  collaborators. This will help to reduce the noise of the event stream while
  preserving the ability to see when items are previewed as a content owner.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-08-31">
  ## Box Java SDK v2.56.0 released

  ### New Features and Enhancements

  * Replace `submaster` `GroupMembershipRole` with `coadmin`. Replace `MASTER_INVITE_ACCEPT` and `MASTER_INVITE_REJECT` with `ADMIN_INVITE_ACCEPT` and `ADMIN_INVITE_REJECT`. ([#907](https://github.com/box/box-java-sdk/pull/907))
  * Add `tracking_codes` to create User API call ([#910](https://github.com/box/box-java-sdk/pull/910))

  ### Bug Fixes

  * Fix `url` for `BoxFileRequest.Info` object ([#906](https://github.com/box/box-java-sdk/pull/906))
  * Attempt to fix thread locking issue on refresh of access token ([#912](https://github.com/box/box-java-sdk/pull/912))
</Update>

<Update label="2021-08-30" description="Box Node SDK v1.39.0 released">
  ## Box Node SDK v1.39.0 released

  ### New Features and Enhancements

  * Add support for Box Sign API ([#658](https://github.com/box/box-node-sdk/pull/658))
  * Enhance TS Imports ([#656](https://github.com/box/box-node-sdk/pull/656))
</Update>

<Update label="2021-08-06">
  ## Box Node SDK v1.38.0 released

  ### New Features and Enhancements

  * Add sensitive language event types for admin invites ([#648](https://github.com/box/box-node-sdk/pull/648))
  * Use `BetterDocs` to adapt `JSDocs` to `TypeScript` ([#646](https://github.com/box/box-node-sdk/pull/646))
  * Change `ProxyAgent` import to be dynamic ([#641](https://github.com/box/box-node-sdk/pull/641))
  * New API for get files and file versions under retention ([#585](https://github.com/box/box-node-sdk/pull/585))

  ### Bug Fixes

  * Deeply freeze Config except Buffers and Readable streams ([#651](https://github.com/box/box-node-sdk/pull/651))
  * Fix a typo in docs of `src/managers/search.ts` ([#649](https://github.com/box/box-node-sdk/pull/649))
  * Update broken documentation link ([#647](https://github.com/box/box-node-sdk/pull/647))
  * fix type annotations for `exchangeToken` functions ([#645](https://github.com/box/box-node-sdk/pull/645))
  * Deprecate files `getThumbnail` API in favor of
    `getRepresentationContent` ([#627](https://github.com/box/box-node-sdk/pull/627))
</Update>

<Update label="2021-06-04">
  ## Upcoming change to JWT format

  On August 4th, 2021, as part of our continued infrastructure upgrades, we will
  begin deployment of a change that may affect custom applications leveraging
  Server Authentication with JSON Web Tokens (JWT).

  Potential impact will require additional verification from customers who do not
  use an official [Box SDK](https://developer.box.com/sdks-and-tools) and are storing tokens in a database.

  All customers and application owners who are potentially impacted have been
  notified directly via email.

  ## Change overview

  This change may only impact applications leveraging Server Authentication with
  JSON Web Tokens (JWT). Tokens will continue to return as a string as stated in
  our [documentation](https://developer.box.com/reference/post-oauth2-token/). However, the format will be longer and contain

  special characters.

  An example of a token returned today: `NXWd9KDPVofXQKZJlQjICCWFHEmuOihs`.

  After this change, tokens will return in the following format:

  `1!yxxhRreQCKcEbC_ZfYvPudyLe7Ed36gIQcqqZo2pfaVZyxNBkQjoHk0fgA1iTY3_uwXgif-hg-gne
    aUdLRmGCb2He6tyQ_rA8aV-CllTyBbd9Tx-wU6Fnt4Df9XjzBAk8Dj7RYc1Ew_fcY2vfycpCvjwHLgql
    jzjEpVIrOpOlK_2AyP5FExzn0x7DtbkaGc6avJU8UMQd_huXoJ7CnXIL_JBzVrW4D32pBLQ2AZIuecOZ
    NMIy9T8PdUiZIG6xKEPqYmm21mQHEM0d7dT5foSBtjm65-Ah2tb2MdSGFb1G1O24vz2GmYFgmIe5UOol
    qYIGg-0u2xQPC3F76WiNCiU_TP1JDQYi3HKaos807WkRtnBY5Vd-VAbY9DH-Qo3u1EiB0RFr4cht2N7V
    B99y-379IEYzCojL2V58dE_pBxpRMv4KcOLVsUfDkbx3uo34H4UzOycI_IWGWrhVJD4M7GeLeD_5Vkmj
    fbwYl2CmHdXAKbZKtXTHjzB0CZixZriT_wRUpsN8GTrrxGbx9ukgzJWRJwelGZ_1Yx7vP4Zkx3OfR5Be
    -Tso7xdHd9rW0FXsu024U7dMNuQ6kpP1_kJI2Y`.

  Please note that this is not a new format to Box, as this format is currently
  returned when [downscoping tokens](https://developer.box.com/guides/authentication/access-tokens/downscope).

  ## Verifying application impact

  1. Navigate to **Admin Console** > **Apps** Tab > **Custom Apps**.
  2. Click **View** for each app row listed
  3. Scroll to the bottom of the app details page and verify the selected
     authentication method. Affected apps will say
     **Server Authentication with JSON Web Tokens**.

  For each application identified above, you will need to determine:

  1. Is it using an official [Box SDK](https://developer.box.com/sdks-and-tools)? If so, no further action is
     required to prepare for this change. While it is always best practice to be
     on the latest version, no minimum versions are required for compatibility.

  2) If an official SDK is not used, are tokens stored in a database? If so, you
     will need to preform additional verification that the database can handle both
     the new length and special characters.

  ## Testing before release

  If you have identified an application that leverages Server Authentication with
  JWT and stores tokens in a database, you will want to preform the test below
  before August 4th.

  As mentioned above, the new format for tokens is currently used when
  [downscoping tokens](https://developer.box.com/guides/authentication/access-tokens/downscope). Therefore, preform the following steps to
  assess impact:

  1. Generate an Access Token for the application

  2) [Downscope](https://developer.box.com/guides/authentication/access-tokens/downscope) the token from step 1

  3. Attempt to store the downscoped token in your database

  If you are successfully able to store the token in the database no further
  action is necessary to prepare for this change.

  If you are unable to store the token, your database must be updated to support
  the additional length and special characters.

  ## Where to get support

  Should you have any questions or need further guidance, please email
  [jwt-set-rollout@box.com](mailto:jwt-set-rollout@box.com).
</Update>

<Update label="2021-07-26">
  ## New Getting Started Guide

  Check out our [step by step guide](/guides/getting-started) to getting started with the Box API.
  Discover best use cases, user models, architecture patterns, and more.

  ## Features

  * Use case evaluation: [Guide](page/platform/use-cases/)
  * Common user models: [Guide](page/platform/user-types/)
  * Common architecture patterns: [Guide](page/platform/appendix/architecture-patterns/)
  * Locating common values: [Guide](page/platform/appendix/locating-values/)
  * Security overview: [Guide](/guides/security)
  * Authentication best practices: [Guide](/guides/authentication/best-practices)
  * Detailed authorization steps: [Guide](/guides/authorization)
</Update>

<Update label="2021-07-30">
  ## Box Java SDK v2.55.1 released

  ### Bug Fixes

  * Restore methods for Execute Metadata Query, which were removed in [#890](https://github.com/box/box-java-sdk/pull/890), and mark them as deprecated ([#905](https://github.com/box/box-java-sdk/pull/905))
</Update>

<Update label="2021-07-26">
  ## Release of Box Sign API

  Today, July 26th, 2021, beings the roll out of Box Sign! Programmatically
  harness the full functionality of the [Box Sign web app experience](https://support.box.com/hc/en-us/articles/4404086827411-Introducing-Box-Sign) by
  leveraging our newest API endpoints to create, list, resend, and cancel Box Sign
  requests.

  While Box Sign does not need to be enabled by an Admin to use its API endpoints,
  it does need to be rolled out to your enterprise. We will notify Admins as it
  becomes available for their Box instance.

  At a minimum, creating a Box Sign request requires selecting a file for
  signature, a destination folder for the signed document/[signing log](https://support.box.com/hc/en-us/articles/4404095202579-Viewing-the-signing-log), and
  designating signers. At this time, only one file can be signed per request.

  ```curl theme={null}
  curl -i -X PUT "https://api.box.com/2.0/sign_requests" \
       -H "Authorization: Bearer <ACCESS_TOKEN>" \
       -d '{
         "signers": [
            {    
              "role": "signer",
              "email": "example_email@box.com"
            }
          ],
         "source_files": [
            {
              "type": "file",
              "id": "123456789"
            }
         ],
         "parent_folder": 
            {
              "type": "folder",
              "id": "0987654321"
            }
       }'
  ```

  ## Features

  * Add endpoint to **create** Box Sign requests: [Guide](/guides/box-sign/create-sign-request) |
    [API reference](/reference//post-sign-requests)
  * Add endpoint to **list** Box Sign requests: [Guide](/guides/box-sign/list-sign-requests/#all) |
    [API reference](/reference/get-sign-requests)
  * Add endpoint to **get** Box Sign requests by ID: [Guide](/guides/box-sign/list-sign-requests/#by-id) |
    [API reference](/reference/get-sign-requests-id)
  * Add endpoint to **resend** Box Sign requests: [Guide](/guides/box-sign/resend-sign-request) |
    [API reference](/reference/post-sign-requests-id-resend)
  * Add endpoint to **cancel** Box Sign requests: [Guide](/guides/box-sign/cancel-sign-request) |
    [API reference](/reference/post-sign-requests-id-cancel)
  * Java SDK support: [GitHub](https://github.com/box/box-java-sdk/tree/main/src/test/java/com/box/sdkgen/signrequests)
</Update>

<Update label="2021-07-26">
  ## Box Java SDK v2.55.0 released

  NOTE: Due to the benign nature of the "breaking change" below, we decided NOT to increment the major version for this release.  There should be no customer impact due to this change.

  ### Breaking Changes

  * Update execute metadata query to match API response ([#890](https://github.com/box/box-java-sdk/pull/890))
    * NOTE: This change removes a method without deprecating it.  It was not possible to use the method correctly at all, because the underlying service no longer supported it.

  ### New Features and Enhancements

  * Remove or deprecate insensitive language (\[[#889](https://github.com/box/box-java-sdk/issues/889)])([https://github.com/box/box-java-sdk/pull/889](https://github.com/box/box-java-sdk/pull/889))
  * Add support for `is_external_collab_restricted` parameter for User ([#896](https://github.com/box/box-java-sdk/pull/896))
  * Add configurable permissions support for `GroupMembership` ([#897](https://github.com/box/box-java-sdk/pull/897))
  * Add `SHIELD_JUSTIFICATION_APPROVAL` event type ([#898](https://github.com/box/box-java-sdk/pull/898))
  * Add ability to get files under retention for assignment and file versions under retention for assignment ([#899](https://github.com/box/box-java-sdk/pull/899))
  * Add `TASK_UPDATE`, `FILE_VERSION_RESTORE` and `ADVANCED_FOLDER_SETTINGS_UPDATE` event types ([#902](https://github.com/box/box-java-sdk/pull/902))
  * Add Box Sign API support ([#904](https://github.com/box/box-java-sdk/pull/904))

  ### Bug Fixes

  * Add setters for `BoxLegalHoldPolicy` ([#885](https://github.com/box/box-java-sdk/pull/885))
  * Add setters for `BoxTaskAssignment` ([#886](https://github.com/box/box-java-sdk/pull/886))
  * Add setters for Group Membership and Web Links ([#887](https://github.com/box/box-java-sdk/pull/887))
  * Add setters for Webhooks ([#888](https://github.com/box/box-java-sdk/pull/888))
  * Deprecate `BoxFile.getThumbnail` in favor of `BoxFile.getRepresentationContent` ([#891](https://github.com/box/box-java-sdk/pull/891))
</Update>

<Update label="2021-07-16">
  ## Updated file size limits

  Today we released our newest business plan, Enterprise Plus, which supports
  uploads and downloads up to 150GB. In addition, we upgraded file size limits for
  some of our existing plans, as detailed below. For details on how to confirm
  the file size limit for your account, please visit our
  [upload guide](/guides/uploads/direct).

  ## Updates

  * Enterprise: 50 GB
  * Digital Workplace Suite: 50 GB
  * Digital Workplace Global Suite: 50 GB
  * Digital Business Suite: 50 GB
  * Digital Business Global Suite: 50 GB
  * Enterprise Plus: 150 GB
</Update>

<Update label="2021-07-16">
  ## New Manual Start Workflow Endpoints

  Two new API endpoints have been introduced for
  [Box Relay](https://www.box.com/collaboration/relay-workflow)

  * Get workflows configured on a folder
  * Start a manual start flow within a workflow for file(s)

  The new endpoints do not allow you to update any information within the
  workflows. Also, the post endpoint can only start flows with a `trigger_type`
  of `WORKFLOW_MANUAL_START`. There is an optional `outcome_parametes` object
  within the post request body. If your flow is configured to accept selections
  at start time, you will need to send in these as a parameter. A guide with all
  the options you can send in will be made available soon.

  ## Features

  This release has introduced the following new content and features.

  * New [workflow](/reference/workflows-resources#workflow) resource
  * New [GET](/reference/get-workflows) workflows endpoint
  * New [POST](/reference/post-workflows-id-start) start manual workflow endpoint
</Update>

<Update label="2021-07-01">
  ## Notice of behavior change for item open events

  Starting today, we will begin rolling out changes to the behavior
  of `ITEM_OPEN` events when an application consumes those events from our
  [event API endpoint](https://developer.box.com/reference/get-events).

  This change will only affect the `ITEM_OPEN` [enterprise event](/guides/events/enterprise-events/for-enterprise).
  The new behavior will not cause downtime within existing applications or
  require any application changes to prevent uptime disruptions.

  ## Change overview

  Within the previous behavior when events were consumed, opened item events were
  surfaced through the `ITEM_OPEN` event type for the owner of the content as
  well as any contributors assigned to the content. This meant that if a file with
  2000 collaborators on it was opened, say on Drive, the file owner plus all
  2000 collaborators would have an event created stating that the file was opened.

  With the new behavior, notification of an item being opened will only be created
  for the owner of the content and will not be produced for collaborators. This
  will help to reduce the noise of the event stream while preserving the ability
  to see when items are opened as a content owner.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-06-16">
  ## Box Python SDK v2.12.1 Released

  ### Bug Fixes

  * Fix bug when thumbnail representations are not found ([#597](https://github.com/box/box-python-sdk/pull/597))
</Update>

<Update label="2021-05-20">
  ## Box Node SDK v1.37.2 released

  ### Bug Fixes

  * Fix backwards compatibility issue by moving some TypeScript [`@types`](https://github.com/types) as direct dependencies ([#630](https://github.com/box/box-node-sdk/pull/630))
</Update>

<Update label="2021-05-19">
  ## Box Node SDK v1.37.1 released

  ### Bug Fixes

  * Insensitive language: replace `whitelist` with `allowlist` ([#625](https://github.com/box/box-node-sdk/pull/625))
</Update>

<Update label="2021-04-22">
  ## Box UI Elements v13.0.0 released

  ## [13.0.0](https://github.com/box/box-ui-elements/releases/tag/v13.0.0) (2021-04-22)

  ## Bug Fixes & Features

  This release fixes several bugs. For a full list, [please see the release notes](https://github.com/box/box-ui-elements/releases/tag/v13.0.0)
</Update>

<Update label="2021-04-20" description="Box iOS SDK v4.4.0 released">
  ## Box iOS SDK v4.4.0 released

  ## Breaking Changes

  ### New Features and Enhancements

  * Add support for search parameter to get shared link items ([#756](https://github.com/box/box-ios-sdk/pull/756))
  * Add support for folder lock functionality ([#759](https://github.com/box/box-ios-sdk/pull/759))
  * Add support for `copyInstanceOnItemCopy` field for metadata templates ([#763](https://github.com/box/box-ios-sdk/pull/763))
  * Add support for stream upload of new file versions and add support for 'If-Match' header when uploading new file versions ([#766](https://github.com/box/box-ios-sdk/pull/766))
  * Add additional details field for `Event` model ([#770](https://github.com/box/box-ios-sdk/pull/770))

  ### Bug Fixes:\*\*

  * Pass only a scheme to iOS Authentication APIs ([#755](https://github.com/box/box-ios-sdk/pull/755))
  * Update `listEnterpriseGroups()` to use documented parameter for filtering by name ([#757](https://github.com/box/box-ios-sdk/pull/757))
  * Fix bug for OAuth where the callback is not called if token has been revoked ([#762](https://github.com/box/box-ios-sdk/pull/762))
</Update>

<Update label="2021-04-16">
  ## Box Python SDK v2.12.0 released

  ### New Features and Enhancements

  * Add metadata query functionality ([#574](https://github.com/box/box-python-sdk/pull/574))
  * Add folder lock functionality ([#581](https://github.com/box/box-python-sdk/pull/581))
  * Add search query support for the `include_recent_shared_links` field  ([#582](https://github.com/box/box-python-sdk/pull/582))
  * Update `get_groups()` to use documented parameter to filter by name ([#586](https://github.com/box/box-python-sdk/pull/586))
</Update>

<Update label="2021-04-16">
  ## Box Node SDK v1.37.0 released

  ### New Features and Enhancements

  * Add support for `copyInstanceOnItemCopy` field for metadata templates ([#572](https://github.com/box/box-node-sdk/pull/572))

  ### Bug Fixes

  * Fix webhook signature validation ([#568](https://github.com/box/box-node-sdk/pull/568))
  * Update dependencies to patch security vulnerabilities ([#578](https://github.com/box/box-node-sdk/pull/578))
</Update>

<Update label="2021-04-15">
  ## Notice of behavior change for item download events

  Starting today, we will begin rolling out changes to the behavior
  of item download events when an application consumes those events from our
  [event API endpoints](https://developer.box.com/reference/get-events/).

  This change will only affect the
  `ITEM_DOWNLOAD` [user event](https://developer.box.com/guides/events/user-events/for-user/#event-types) and will not affect existing
  [enterprise events](https://developer.box.com/guides/events/enterprise-events/for-enterprise/). The new behavior will not cause
  downtime within existing applications or require any application changes to
  prevent uptime disruptions.

  ## Change overview

  Within the previous behavior when events were consumed, downloaded item
  events were surfaced through the `ITEM_DOWNLOAD` event type for the owner of
  the content as well as any contributors assigned to the content. This meant
  that if a file with 2000 collaborators on it was downloaded, the file owner
  plus all 2000 collaborators would have an event created stating that the file
  was downloaded.

  With the new behavior, notification of an item being downloaded will only be
  created for the owner of the content and will not be produced for
  collaborators. This will help to reduce the noise of the event stream while
  preserving the ability to see when items are downloaded as a content owner.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-04-13">
  ## New option for downscoping tokens using shared links

  When requesting an access token, you now have the ability to downscope that token to a file or folder using a shared link.

  This new parameter may be used instead of using the `resource` parameter, which allows you to supply a file or folder ID to perform the same action.

  ## Updates

  * Added new `box_shared_link` request parameter to [downscoping documentation](https://developer.box.com/guides/authentication/access-tokens/downscope/#downscoping-in-practice). A shared link may be supplied to downscope an access token in the below way.

  ```bash theme={null}
  {
    curl -i -X POST "https://api.box.com/oauth2/token" \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d "subject_token=[ACCESS_TOKEN]" \
       -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
       -d "scope=item_upload item_preview base_explorer" \
       -d "box_shared_link=https://cloud.box.com/s/123456" \
       -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange"
  }
  ```

  * Added `box_shared_link` request parameter to [request access token API reference](https://developer.box.com/reference/post-oauth2-token/#request).
</Update>

<Update label="2021-04-01">
  ## Box Java SDK v2.54.0 released

  ### New Features and Enhancements

  * Add file request support ([#869](https://github.com/box/box-java-sdk/pull/869))

  ### Bug Fixes

  * Fix `BoxWeblink` deserialization ([#881](https://github.com/box/box-java-sdk/pull/881))
</Update>

<Update label="2021-03-25">
  ## Service Account email added to Developer Console

  Upon Admin authorization of an application leveraging server authentication,
  the auto-generated email address of the Service Account is now surfaced in the
  General tab of the Developer Console. This email address can then be used to
  collaborate the user on Box content. The format will always be
  `AutomationUser_AppServiceID_RandomString@boxdevedition.com`. For example,
  `AutomationUser_123456_6jCo6Pqwo@boxdevedition.com`.

  To learn more, see our guide on [User Types](https://developer.box.com/platform/user-types) and [Service Accounts](https://developer.box.com/platform/user-types#service-account).

  ## Features

  * Added auto-generated email address of Service Account user to Developer
    Console
</Update>

<Update label="2021-03-25">
  ## New Metadata Query Indices Endpoint

  A new API endpoint has been introduced to get a list of metadata query indices
  for a given template and scope.

  Metadata queries provide a way to find files and folders by searching for the
  metadata attached to them.

  When performing metadata queries on 10,000 or more files or folders,
  non-performant queries may produce an `HTTP 403` error.
  Creating a search index delivers the ability to run
  these queries at scale to bypass this error state, and are automatically applied
  during the querying process.

  The new endpoint permits the lookup of these created search indices.

  ## Features

  This release has introduced the following new content and features.

  * New API endpoint to get a list of metadata query
    indices by scope and template.
  * New metadata query index [response object](https://developer.box.com/reference/resources/metadata-query-indices/).
  * New metadata query indices [response object](https://developer.box.com/reference/resources/metadata-query-index/).

  ## Updates

  This release includes the following updated content.

  * Updated metadata query indices guide to include details
    on how to get a list of metadata query indices.
</Update>

<Update label="2021-03-16">
  ## New Collection Events

  External collection events are now available via the
  [enterprise events](/guides/events/enterprise-events/for-enterprise/) stream.

  [Collections](/guides/collections/) in Box are a way to group files, folders, and web
  links without putting them all into a folder together. These new events provide
  a method for monitoring when collection actions are taken within an enterprise.

  The events follow the standard event object schema, and include the
  following:

  * `COLLECTION_CREATE`: A collection was created
  * `COLLECTION_DELETE`: A collection was deleted
  * `COLLECTION_UPDATE`: A collection was updated
  * `COLLECTION_ITEM_CREATE`: An item was added to a collection
  * `COLLECTION_ITEM_DELETE`: An item was removed from a collection
  * `COLLECTION_ITEM_UPDATE`: An item in a collection was updated
</Update>

<Update label="2021-02-26">
  ## Box Shield Smart Access events

  External collaboration restriction and justification approval events are now
  available via the [enterprise events](/guides/events/enterprise-events/for-enterprise/) stream.

  [Box Shield](https://www.box.com/shield) must be purchased and enabled on a Box enterprise in
  order to take advantage of these advanced security offerings.

  These events follow the standard [event object](/reference/resources/event/) schema, with the
  `event_type` value set of:
  `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED_MISSING_JUSTIFICATION`,
  `SHIELD_EXTERNAL_COLLAB_INVITE_JUSTIFIED`,
  `SHIELD_EXTERNAL_COLLAB_INVITE_BLOCKED`
  `SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED_MISSING_JUSTIFICATION`,
  `SHIELD_EXTERNAL_COLLAB_ACCESS_BLOCKED`, or
  `SHIELD_JUSTIFICATION_APPROVAL`.

  The `additional_details` payload of each event provides more information. Full
  details can be found in our \[Shield Events [guide](/guides/events/event-triggers/shield-alert-events/#smart-access).

  ## Features

  * Add support for Box Shield external collaboration and justification approval
    events to the enterprise events stream
</Update>

<Update label="2021-02-26">
  ## Box CLI v2.9.0 released

  ## New Features and Enhancements

  * Add ability to add an option to a metadata template multi select field ([#230](https://github.com/box/boxcli/pull/230))
  * Add folder lock functionality ([#232](https://github.com/box/boxcli/pull/232))
  * Add support for search parameter to get shared link items ([#233](https://github.com/box/boxcli/pull/233))

  ## Bug Fixes

  * Fix events command bug when there is no stream position flag ([#234](https://github.com/box/boxcli/pull/234))
  * Fix bug with folders:upload command not uploading folder contents ([#231](https://github.com/box/boxcli/issues/231))
</Update>

<Update label="2021-05-10">
  ## Box API response header changes that may impact your applications

  On May 10th, 2021, as part of our continued infrastructure upgrade, Box's API
  response headers will standardize to always return in a case-insensitive
  manner, in line with industry best practices and our API documentation.

  This change has the following potential impact:

  * [Salesforce SDK `v1`](https://github.com/box/box-salesforce-sdk/releases/tag/1.0.0) users will be impacted and will need
    to upgrade to a recent SDK version. Not doing so will cause your Box
    Salesforce integration to cease functioning after May 10th, 2021.
  * Box API consumers who do not use one of the [Box SDKs](https://developer.box.com/sdks-and-tools/) may be
    impacted and will need to verify header usage through their code. Depending on
    your header usage, not making adjustments may cause disruptions in your
    Box API integration.

  All customers and application admins who are potentially impacted have been
  notified directly via email.

  ## Change overview

  Applications that are using the return headers described above, such as
  `location` and `retry-after`, will need to verify that their applications are
  checking for these headers in a case-insensitive fashion. Over the past 12
  months Box has been upgrading its networking and observability infrastructure.
  These upgrades aim to improve reliability and availability of Box's products
  for our customers. This specific change allows Box to deploy an updated service
  proxy, enabling Box to better monitor service traffic, quickly find
  problem areas, and tune application performance.

  ## API Consumers: Verifying application impact

  Verifying whether your application(s) will be impacted will require a review of
  your code. If you are solely using one of the official Box SDKs to connect to
  Box APIs, you will not be impacted as the SDKs handle response headers in a
  case-insensitive manner.

  You may verify whether you are impacted with the following steps:

  * Locate the code in your application which handles the responses from Box API
    requests. If you are not extracting the response headers from these responses,
    you are not impacted.
  * If you are extracting those response headers, you may be impacted if you are
    expecting those headers in a case-sensitive fashion.

  For instance, if you are expecting the `Location` header to be returned with a
  starting capital `L`, a direct string comparison with a specific case, then
  your code will need to be altered to prevent it from breaking after the change
  is made.

  ## API Consumers: How to make the change

  To update the impacted application(s), ensure that you are checking these
  response headers in a case-insensitive manner. Specifically, your code should
  be built in a defensive way to ensure that if a header, such as `Location`, is
  sent with an initial capital `L` or a lowercase `l`, it'll be handled in the
  same way. For example, forcing all headers to lowercase before checking, or
  using a case-insensitive regex string check, are two viable methods for
  handling this process.

  ## Salesforce SDK `v1` users: Verifying application impact

  If you are unsure whether you are using `v1.0` of the Box Salesforce SDK, go to
  the application code location where you have stored the Box Salesforce SDK and
  do the following:

  Load the following Salesforce SDK file: `src/classes/BoxApiRequest.cls`

  Look for the following lines ([should be lines 6-7](https://github.com/box/box-salesforce-sdk/compare/1.0.0...v1.1.0#diff-1855f83ffd4977e5b9e4bfc167154f2e11b0161fd6c380502c48082b6837b0af)):

  ```apex theme={null}
  public final static String HEADER_LOCATION_LOWER_CASE = 'location';
  public final static String HEADER_LOCATION_CAPITALIZED = 'Location';
  ```

  If those lines are present then you are using `v1.1.0` or later of the
  Salesforce SDK, which is not impacted and no changes are needed. If those lines
  are not present then you are using `v1.0` of the Salesforce SDK, which will be
  impacted and will need to be updated.

  ## Salesforce SDK `v1` users: How to make the change

  To update the impacted application(s), you will need to update the version of
  the Salesforce SDK that you are using. It is recommended that you upgrade to
  the [most recent version](https://github.com/box/box-salesforce-sdk) of the SDK, but anything from
  [`v1.1.0` or later](https://github.com/box/box-salesforce-sdk/releases) will be adequate to ensure that
  there is no impact to your application(s).

  ## Where to get support

  Should you have any issues or need further guidance, please
  [file a ticket](https://support.box.com/hc/en-us/requests/new) with our support team or post a request to our
  [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-02-01">
  ## Box iOS SDK v4.3.0 released

  ## Breaking Changes

  ### New Features and Enhancements

  * Add support for OAuth 2 custom callback URL ([#746](https://github.com/box/box-ios-sdk/pull/746))
  * Add support for zip download ([#749](https://github.com/box/box-ios-sdk/pull/749))

  ### Bug Fixes

  * Update gems to patch `kramdown` vulnerability ([#742](https://github.com/box/box-ios-sdk/pull/742))
  * Update gems to patch `activesupport` vulnerability ([#745](https://github.com/box/box-ios-sdk/pull/745))
</Update>

<Update label="2021-01-28">
  ## Box Node SDK v1.36.0 released

  ### New Features and Enhancements

  * Add folder lock functionality ([#560](https://github.com/box/box-node-sdk/pull/560))
  * Add support for filtering groups by name ([#561](https://github.com/box/box-node-sdk/pull/561))

  ### Bug Fixes

  * Update proxy-agent to patch proxy support issue ([#563](https://github.com/box/box-node-sdk/pull/563))
  * Update dependencies to patch security vulnerabilities ([#566](https://github.com/box/box-node-sdk/pull/566))
</Update>

<Update label="2021-01-25">
  ## Maximum upload file size limit increases

  The maximum file size that may be uploaded via the API has been increased for
  the following Box account plans.

  * Business Plus
  * Enterprise
  * Digital Workplace Suite
  * Digital Workplace Global Suite

  The prior maximum upload file size for these account types was **5 GB**. This
  update increases the maximum file size to **15 GB**, effective immediately.

  For more information on the maximum file sizes for all account plans, please
  refer to the [direct uploads](/guides/uploads/direct/) documentation.
</Update>

<Update label="2021-01-15">
  ## Metadata Query index changes

  When making file / folder [metadata query](/guides/metadata/queries/) requests, a
  search index needs to be created for queries where more than
  10,000 files / folders are being searched.

  To improve the efficiency and simplicity of this process, we have changed the
  way in which indexes are used by removing the explicit requirement to supply an
  index through the `use_index` key in a metadata query API request.

  There is no impact to existing applications that are currently supplying an
  index through the `use_index` key. The supplied index will be ignored in
  the request and the most efficient index will be automatically applied.

  ## Previous Indexing Process

  The following was the previous process for creating and using an index for a
  metadata query request involving 10,000+ files / folders in the search. This is
  the process being replaced.

  * Contact the metadata query team to request an index.
  * The metadata query team would create the index and supply back the name of
    the newly created index.
  * When making metadata query requests this index name was
    supplied as the value for the `use_index` key in the API request.

  ## New Indexing Process

  The following is the new process for creating and using an index.

  * Contact the metadata query team to request an index.

  The `use_index` key within the metadata query API request has been removed.
  Instead, the most efficient query will be automatically applied during the
  search process.

  Indexes that are currently supplied in the `use_index` key will be ignored, and
  instead the most efficient index will be used.

  Application owners may safely remove the `use_index` key and value from their
  metadata query requests at their discretion.
</Update>

<Update label="2021-01-15">
  ## Developer Console Updates

  A new **Authorization** tab is now available in the Developer Console. In
  addition, clarifying UI changes were made to the **Application Access** and
  **Scope** settings within the **Configuration** tab to ease these decisions.
  These changes do not impact the functionality of the settings.

  Now, developers will navigate to the  **Authorization** tab to submit the
  application directly to their Box Admin for authorization approval.

  As for the **Configuration** tab, helpful tips were added to the JWT
  **Application Access** settings to facilitate a clear decision
  between **App Only Access** or **App Access + Enterprise Access**.
  The **Scope** section is now grouped by action type: content, administrative,
  and developer.

  * **App Approval Process**: [Guide](/guides/authorization/platform-app-approval)
  * **Scopes**: [Guide](/guides/api-calls/permissions-and-errors/scopes)
  * **Application Access**:
    [Guide](/guides/authentication/jwt/jwt-setup/#application-access)

  ## Updates

  * Added Authorization tab to the Developer Console
  * Updated the UI for JWT Application Access settings under the Configuration tab
  * Updated the UI grouping of Scopes under the Configuration tab
</Update>

<Update label="2021-01-11">
  ## Box Python SDK v2.11.0 released

  ### New Features and Enhancements

  * Deprecate and add method for getting a thumbnail ([#572](https://github.com/box/box-python-sdk/pull/572))
</Update>

<Update label="2021-01-09">
  ## Box Java SDK v2.53.0 released

  ### New Features and Enhancements

  * Add offset and limit parameters to `BoxFolder.getChildren` ([#861](https://github.com/box/box-java-sdk/pull/861))
</Update>


# 2022
Source: https://developer.box.com/changelog/2022

Box Platform changelog: API, SDK, and product updates from 2022.

<Update label="2022-12-21">
  ## Box Node SDK v2.8.0 released

  ### New Features and Enhancements

  * Session termination ([#782](https://github.com/box/box-node-sdk/issues/782)) ([`7fb56c6`](https://github.com/box/box-node-sdk/commit/7fb56c625f8eb03e6a5354b67a0debfd9e4ad7c8))
</Update>

<Update label="2022-12-19" description="Announcing major releases of Box SDKs">
  ## Announcing major releases of Box SDKs

  In January 2023, we plan two major releases of Box Windows V2 SDK and Box Java SDK.

  For Box Windows V2 SDK, we are changing the minimum supported version of .NET Framework from 4.5 to 4.6.2+.
  For Box Java SDK, we are replacing networking library and introducing [OkHttp](https://square.github.io/okhttp/) which will give SDK support of HTTP2 protocol and
  allow users to use proxies beyond basic authentication.

  For both SDKs, we are removing deprecated APIs.

  * Read more about changes to [Box Windows V2 SDK](https://github.com/box/box-windows-sdk-v2/releases/tag/v5.0.0-prerelease).
  * Read more about changes to [Box Java SDK](https://github.com/box/box-java-sdk/releases/tag/v4.0.0-prerelease).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-12-19">
  ## Box Java SDK v3.8.1 released

  ### Bug Fixes

  * Restoring state from previous `SDK` version works. ([#1134](https://github.com/box/box-java-sdk/issues/1134)) ([`b6d97dd`](https://github.com/box/box-java-sdk/commit/b6d97dd5b0cc91eb2e4c922ff217e0878e0f63ec))
</Update>

<Update label="2022-12-01">
  ## Server-side actions no longer supported in Web App Integrations

  On December 1st, the options to create a preliminary callback URL or a server-side integration will no longer be available for OAuth 2.0 web app integration.

  ## Next steps

  If you have the server-side integration already configured for your applications, it will still be working.
  If you wish to stop using the feature or perform adjustments in your settings, see [this document](https://cloud.app.box.com/file/958463673555?s=uwk4jvanbofom2ckvk9q0wcnkc2vxqdy) for workaround options and support.

  For more information about web app integrations, see the [documentation](/guides/applications/web-app-integrations/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-11-30">
  ## Box Python SDK v3.5.1 released

  ### Bug Fixes

  * Renew connection when Connection reset error occurs ([#771](https://github.com/box/box-python-sdk/issues/771)) ([`bcaab27`](https://github.com/box/box-python-sdk/commit/bcaab277c3cabba498076d066366abbaa5507904)), closes [#756](https://github.com/box/box-python-sdk/issues/756) [#757](https://github.com/box/box-python-sdk/issues/757) [#763](https://github.com/box/box-python-sdk/issues/763) [#765](https://github.com/box/box-python-sdk/issues/765) [#766](https://github.com/box/box-python-sdk/issues/766) [#770](https://github.com/box/box-python-sdk/issues/770)
  * Retry JWT auth when got error: required unique `jti` claim. ([#768](https://github.com/box/box-python-sdk/issues/768)) ([`878e958`](https://github.com/box/box-python-sdk/commit/878e958abfb01740656aaff42492777753e4c8ea))
  * Update `pyjtw` dependency to work with Python 3.10 ([#772](https://github.com/box/box-python-sdk/issues/772)) ([`b13c5cd`](https://github.com/box/box-python-sdk/commit/b13c5cd34105d3f774d3f6d35db7aaf51dd3e247))
</Update>

<Update label="2022-11-22">
  ## Box CLI v3.6.0 released

  ### New Features and Enhancements

  * Add `id` and `type` field to shared-links:create response ([#427](https://github.com/box/boxcli/issues/427)) ([`5ea4cb8`](https://github.com/box/boxcli/commit/5ea4cb82294188dd30563ef9cea2c8e0b76bbfae))
  * Add fields `disposition_at` field for files under retention ([#429](https://github.com/box/boxcli/issues/429)) ([`db824ef`](https://github.com/box/boxcli/commit/db824ef0b4111810b7902896062c950ef9ac01b3))

  ### Bug Fixes

  * Fix `event:poll` polling-interval ([#430](https://github.com/box/boxcli/issues/430)) ([`9ada74b`](https://github.com/box/boxcli/commit/9ada74b09eb5aa0e09881946a4f7f30e2d68e037))
</Update>

<Update label="2022-11-16">
  ## Box Java SDK v3.8.0 released

  ### New Features and Enhancements

  * Added Box Sign webhooks ([#1109](https://github.com/box/box-java-sdk/issues/1109)) ([`99051a5`](https://github.com/box/box-java-sdk/commit/99051a575f120a8c0939359c1f4875b16b98b7f0))

  ### Bug Fixes

  * `NullPointerException` when using `BoxSignRequestPrefillTag` ([#1121](https://github.com/box/box-java-sdk/issues/1121)) ([`73fd5b6`](https://github.com/box/box-java-sdk/commit/73fd5b6e6e40f7e79b385edf46b8eee5ff612ace)), closes [#1120](https://github.com/box/box-java-sdk/issues/1120)
  * Regenerate JWT ID and retry auth request when JTI claim is rejected ([#1110](https://github.com/box/box-java-sdk/issues/1110)) ([`420da0f`](https://github.com/box/box-java-sdk/commit/420da0f2c80bfe8cfbaba4fa8dec4826c4cb6337))

  ### Dependency Upgrades

  * Bumped `org.bitbucket.b_c:jose4j:0.9.0` ([#1111](https://github.com/box/box-java-sdk/issues/1111)) ([`349694d`](https://github.com/box/box-java-sdk/commit/349694ddcfeb701a9ecdfd5ae555d49bea4d1030))
</Update>

<Update label="2022-11-10">
  ## Box Node SDK v2.7.2 released

  ### Bug Fixes

  * Add `fields` query parameter to file and folder update ([#776](https://github.com/box/box-node-sdk/issues/776)) ([`a327deb`](https://github.com/box/box-node-sdk/commit/a327debc83d98a4190a5a16cf848417ea5714db9))
</Update>

<Update label="2022-11-08">
  ## Box iOS SDK v5.4.0 released

  ### New Features and Enhancements

  * Add `content_type` field to Sign Requests signer ([#871](https://github.com/box/box-ios-sdk/issues/871)) ([`1ec5b01`](https://github.com/box/box-ios-sdk/commit/1ec5b0149f01cd3a18f5cba39b77e01678655932))
  * Add `redirect_url` and `declined_redirect_url` to Sign Request ([#870](https://github.com/box/box-ios-sdk/issues/870)) ([`f94d988`](https://github.com/box/box-ios-sdk/commit/f94d98862d2fdb2603f4684b963d29d04e0fdb3d))
  * Add support for `sign` webhook triggers ([#875](https://github.com/box/box-ios-sdk/issues/875)) ([`994bfaf`](https://github.com/box/box-ios-sdk/commit/994bfaf3ead983f5014808f6c9e5ffe167ab8e42))
  * Added method to remove retention policy assignment ([#873](https://github.com/box/box-ios-sdk/issues/873)) ([`c5f146c`](https://github.com/box/box-ios-sdk/commit/c5f146c960bb1f940418975078d83fb63ff3bdec))
  * Added support for Modifiable Retention Policies ([#872](https://github.com/box/box-ios-sdk/issues/872)) ([`e2b7a17`](https://github.com/box/box-ios-sdk/commit/e2b7a178c6592c9f7d1e7ce691c215680b3f45d0))
</Update>

<Update label="2022-11-02">
  ## Box CLI v3.5.0 released

  ### New Features and Enhancements

  * Add option to change name of downloaded file in `save-as`parameter ([#415](https://github.com/box/boxcli/issues/415)) ([`81fe64e`](https://github.com/box/boxcli/commit/81fe64eb2891e7ab55564e2428f64f1129b468e8))
  * Add support for modifiable retention policies & enable deleting retention policy assignment ([#420](https://github.com/box/boxcli/issues/420)) ([`26ab5b4`](https://github.com/box/boxcli/commit/26ab5b4d7ec49576fdac48abc025903622f8efe0))
</Update>

<Update label="2022-10-28">
  ## Introducing Shield Information Barrier

  Shield information barrier prevents communication that could lead to conflicts of interest or potential legal issues.
  For example, admins can use information barrier to separate teams working on
  different projects to prevent collaboration on content restricted to specific groups.

  ## Shield Information Barrier API

  Shield information barrier comes along with the new API that you can use to:

  * Create, manage, and list [Shield information barriers](/reference/resources/shield-information-barrier)
  * Create, update, delete, and list [Shield information barrier segments](/reference/resources/shield-information-barrier-segment)
  * Create, delete, and list [Shield information barrier segment restrictions](/reference/resources/shield-information-barrier-segment-restriction)
  * Create, delete, and list [Shield information barrier segment members](/reference/resources/shield-information-barrier-segment-member)
  * Create and list [Shield information barrier reports](/reference/resources/shield-information-barrier-report)

  ## Shield Information Barrier Events

  Setting up the information barrier produces the following events:

  * Events triggered when the user configures the information barrier, for example activates or deactivates the barrier.
  * Events triggered when the user performs restricted actions, for example attempts to move an item to a restricted folder or add a user to a restricted group.

  For a list of all events, see the [Shield information barrier event triggers](/guides/events/event-triggers/shield-information-barrier-events) reference.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-10-28">
  ## Box Node SDK v2.7.1 released

  ### Bug Fixes

  * Export missing `RetentionType` ([#774](https://github.com/box/box-node-sdk/issues/774)) ([`7e6b244`](https://github.com/box/box-node-sdk/commit/7e6b244ba63d363ecc921be570140c9e1ed1d032))
</Update>

<Update label="2022-10-27">
  ## Box Node SDK v2.7.0 released

  ### New Features and Enhancements

  * Add support for modifiable retention policies & enable deleting retention policy assignment ([#769](https://github.com/box/box-node-sdk/issues/769)) ([`5e8c776`](https://github.com/box/box-node-sdk/commit/5e8c776fc94e9dcf313cc15c96e42fbffaf36b74))
</Update>

<Update label="2022-10-20">
  ## Box UI Elements v16.0.0 released

  ## [16.0.0](https://github.com/box/box-ui-elements/releases/tag/v16.0.0) (2022-10-20)

  ## Bug Fixes & Features

  This release fixes several bugs and adds new features.
  For a full list of changes, [see the release notes](https://github.com/box/box-ui-elements/releases/tag/v16.0.0).
</Update>

<Update label="2022-10-19">
  ## Manage webhooks V2 in the developer console

  Managing webhooks in your applications is now easier and more streamlined.
  In one single-stop UI - the **Webhooks** tab in the
  [Developer Console](https://app.box.com/developers/console) - you can review all webhooks in an
  application. You can now [create](/guides/webhooks/v2/create-v2), [update](/guides/webhooks/v2/update-v2), or [delete](/guides/webhooks/v2/delete-v2) V2 webhooks
  using the user interface in the [Developer Console](https://app.box.com/developers/console).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-10-19">
  ## New annotations in the Content Preview UI Element

  To improve the content previewing experience, we have added support for new
  annotations types in the Preview UI Element.
  End users previewing content in custom applications can now utilize additional
  annotation types, such as text highlight, drawing, and more. All the annotations
  sync in real time.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-10-18">
  ## Box Windows SDK v4.6.0 released

  ### New Features and Enhancements

  * Add `redirect_url` and `declined_redirect_url` to Sign Request ([#853](https://github.com/box/box-windows-sdk-v2/issues/853)) ([`5ef2f18`](https://github.com/box/box-windows-sdk-v2/commit/5ef2f18985d8c3b8e7c0cdba5709785bfb1d5f34))
  * Add support for modifiable retention policies & enable deleting retention policy assignment ([#856](https://github.com/box/box-windows-sdk-v2/issues/856)) ([`564904f`](https://github.com/box/box-windows-sdk-v2/commit/564904fa2ce0b1881a2f07b80cc3bb3e648310d0))

  - [https://www.nuget.org/packages/Box.V2/4.6.0>](https://www.nuget.org/packages/Box.V2/4.6.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/4.6.0>](https://www.nuget.org/packages/Box.V2.Core/4.6.0>)
</Update>

<Update label="2022-10-05">
  ## Extract metadata with the new Box CLI script

  [Box CLI](/guides/cli) now features a new script that allows you to [extract metadata](/guides/cli/scripts/metadata-extraction) details for all Box files and folders and save it in a CSV file.

  ## Where to get support

  Should you have any issues or need further guidance, post a request to
  our [developer forum](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) for any help needed.
</Update>

<Update label="2022-09-30">
  ## Box Java SDK v3.7.1 released

  ### Bug Fixes

  * Better logging when JSON cannot be parsed ([#1106](https://github.com/box/box-java-sdk/issues/1106)) ([`5e66ef8`](https://github.com/box/box-java-sdk/commit/5e66ef8cc983a6cff34995efc75e9effd3195d48))
</Update>

<Update label="2022-09-26">
  ## Box CLI v3.4.0 released

  ### New Features and Enhancements

  * Add `DryRun` mode in `User Deprovision` example script ([#392](https://github.com/box/boxcli/issues/392)) ([`584a30e`](https://github.com/box/boxcli/commit/584a30ef33446a6687ce558c810804202650299f))
  * Add `redirect_url` and `declined_redirect_url` to Sign Request ([#395](https://github.com/box/boxcli/issues/395)) ([`261b7d2`](https://github.com/box/boxcli/commit/261b7d22a5e5adf3647276cbf59454cca9bf607f))
  * Add progress bar for file download and bulk command ([#376](https://github.com/box/boxcli/issues/376)) ([`68359c7`](https://github.com/box/boxcli/commit/68359c7e97ce2b606184426cbbaac73914ceb81a))
  * create destination path during download ([#393](https://github.com/box/boxcli/issues/393)) ([`40881dd`](https://github.com/box/boxcli/commit/40881ddbd2c86e80f19689f012736fb19f18d945))
  * native credentials storage for Windows with a new library ([#385](https://github.com/box/boxcli/issues/385)) ([`a6918aa`](https://github.com/box/boxcli/commit/a6918aaa6e28bd29619bea31c97b845d8d429fec))

  ### Bug Fixes

  * correctly resolve home `dir` in folders download ([#398](https://github.com/box/boxcli/issues/398)) ([`86d3230`](https://github.com/box/boxcli/commit/86d3230456827a042be04f5ef372b15d83fd6a10))
  * Fix logs in `Users Deprovisioning` script ([#381](https://github.com/box/boxcli/issues/381)) ([`c85f77b`](https://github.com/box/boxcli/commit/c85f77b3042dfc3ddfe54b2acd94b220f6ee0e9b))
  * Fix problem with `keytar` library ([#394](https://github.com/box/boxcli/issues/394)) ([`1979f01`](https://github.com/box/boxcli/commit/1979f01758a30cd1dbf9d32c19ce2f3a00c0d5ec))

  ### Note

  * To migrate storing Box CLI environments to the system credential storage, execute the following command in the terminal ([#295](https://github.com/box/boxcli/issues/295))

    `box configure:environments:update`
</Update>

<Update label="2022-09-23">
  ## Box Python SDK v3.5.0 released

  ### New Features and Enhancements

  * Add `redirect_url` and `declined_redirect_url` fields to Sign Request ([#752](https://github.com/box/box-python-sdk/issues/752)) ([`5d1f609`](https://github.com/box/box-python-sdk/commit/5d1f609ed4c2ddb24bd88ffac256a2809a012698))
  * Add support for modifiable retention policies & enable deleting retention policy assignment ([#759](https://github.com/box/box-python-sdk/issues/759)) ([`847301b`](https://github.com/box/box-python-sdk/commit/847301b43be335365858a80420459dffaada4302))
  * Support file request APIs ([#747](https://github.com/box/box-python-sdk/issues/747)) ([`71895e3`](https://github.com/box/box-python-sdk/commit/71895e33ff7cf339fd8e095a5393f04b86791d5a))

  ### Bug Fixes

  * Do not log the content of downloaded file ([#760](https://github.com/box/box-python-sdk/issues/760)) ([`5d26431`](https://github.com/box/box-python-sdk/commit/5d264314f949c1f4d9136efd5cf8f13dd5897c05))
  * Fix closing file after chunked upload ([#761](https://github.com/box/box-python-sdk/issues/761)) ([`b433692`](https://github.com/box/box-python-sdk/commit/b433692ecc07d62d011785a557128c1780ea1647))
</Update>

<Update label="2022-09-23">
  ## Box Node SDK v2.6.0 released

  ### New Features and Enhancements

  * Add `content_type`, `redirect_url` field to Sign Request ([#758](https://github.com/box/box-node-sdk/issues/758)) ([`8abb9b6`](https://github.com/box/box-node-sdk/commit/8abb9b602b13cd72c6c8de549d19756ae147b403))
  * Add sign request webhook ([#760](https://github.com/box/box-node-sdk/issues/760)) ([`e92d1ab`](https://github.com/box/box-node-sdk/commit/e92d1abee5faf58166f4892d7b2e6bc3c6480ac6))
  * Added support for Access Only Collaboration  ([#759](https://github.com/box/box-node-sdk/issues/759)) ([`dd8261f`](https://github.com/box/box-node-sdk/commit/dd8261f970c207854058c3ed86ccabf9bec05ea8))
</Update>

<Update label="2022-09-21">
  ## Box Java SDK v3.7.0 released

  ### New Features and Enhancements

  * Add `is_accessible_via_shared_link` field to File and Folder ([#1103](https://github.com/box/box-java-sdk/issues/1103)) ([`45e9906`](https://github.com/box/box-java-sdk/commit/45e9906efca6a7f2d4d738914dc804de12d3646e))

  ### Bug Fixes

  * `BoxCollaboration.getItem()` returns `BoxItem.Info` not `BoxFolder.Info` ([#1102](https://github.com/box/box-java-sdk/issues/1102)) ([`135850d`](https://github.com/box/box-java-sdk/commit/135850d97164ee5f6d74708d74c531f7fa8bee26)), closes [#1101](https://github.com/box/box-java-sdk/issues/1101) [#1100](https://github.com/box/box-java-sdk/issues/1100). `BoxCollaboration.getItem()` used to return `BoxFolder.Info`. However, if collaboration was added on a file it would still return `BoxFolder.Info` which will end with throwing `BoxAPIException` when doing any API call. If you are getting collaboration item it is best to store it as `BoxItem.Info` or check its type and store it as `BoxFile.Info` or `BoxFolder.Info`.
  * Add missing constructor to `BoxNotificationEmail` class ([#1098](https://github.com/box/box-java-sdk/issues/1098)) ([`2534f34`](https://github.com/box/box-java-sdk/commit/2534f34133f9554abd1e80fc1555659a2c52b23f))
</Update>

<Update label="2022-09-12">
  ## Improved Guides on Chunked Uploads

  To improve your experience with uploading large files in chunks,
  our guides now provide additional details on the process
  and support each step with examples.

  Check out the [Upload Part guide](/guides/uploads/chunked/upload-part) a to get the details on how to
  effectively split files and upload them in several parts using [Box API](/reference/put-files-upload-sessions-id).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-09-07">
  ## Box Java SDK v3.6.0 released

  ### New Features and Enhancements

  * Add support for modifiable retention policies & enable deleting retention policy assignment ([#1093](https://github.com/box/box-java-sdk/issues/1093)) ([`30e2fcb`](https://github.com/box/box-java-sdk/commit/30e2fcb74c12867fd3859c3490539557b47ab006))

  ### Bug Fixes

  * Stop sending not specified optional fields when creating a user ([#1095](https://github.com/box/box-java-sdk/issues/1095)) ([`b7d894d`](https://github.com/box/box-java-sdk/commit/b7d894d3f134137f3a5925f09accfd4334837f81))
</Update>

<Update label="2022-09-06">
  ## Box CLI Advanced Features YouTube Video Released

  Back in February, we [launched](/changelog/2022) the OAuth 2.0 version of the Box CLI, alongside
  new YouTube content. Today, we released [video 3](https://youtu.be/WXkBctPosLE) of the series. It shows
  using the as-user header and bulk command options.

  You can find the Box Platform and Developer Playlist on [YouTube](https://www.youtube.com/playlist?list=PL0F3BD5B64D6A39F1). We have one
  more video planned for this series: CLI Automation using PowerShell.

  Make sure to [subscribe](https://www.youtube.com/user/box/featured) to the Box Channel to get all the latest content!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-08-29">
  ## Box Sign available for Starter plans

  [Box Sign](/guides/box-sign) is now available for Free, Personal Pro, and Starter plans.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) for any help needed.
</Update>

<Update label="2022-08-26">
  ## Box Java SDK v3.5.0 released

  ### New Features and Enhancements

  * Add `content-type` sign request and response ([#1087](https://github.com/box/box-java-sdk/issues/1087)) ([`49411aa`](https://github.com/box/box-java-sdk/commit/49411aaeea6d3ff8de10e3fbc3c60bba1bc54748))
  * Add `notification_email` to `BoxUser` ([#1088](https://github.com/box/box-java-sdk/issues/1088)) ([`5477223`](https://github.com/box/box-java-sdk/commit/547722347a920ba11e5fff7a8df5201720af815a))
  * Add `redirect_url` and `declined_redirect_url` to sign request response ([#1089](https://github.com/box/box-java-sdk/issues/1089)) ([`3921fe1`](https://github.com/box/box-java-sdk/commit/3921fe1a4a6249146a8dd2f22e15801846bc073b))

  ### Bug Fixes

  * Fixed canceling sign request fails because of empty body ([#1085](https://github.com/box/box-java-sdk/issues/1085)) ([`32b8e79`](https://github.com/box/box-java-sdk/commit/32b8e79ebc8995ab933c32d28c3e2f17d9627a70))
</Update>

<Update label="2022-08-24">
  ## Updates to Box CLI

  The recent additions to the [Box CLI script library](/guides/cli/scripts) and [Box CLI with JWT Authentication](/guides/cli/cli-with-jwt-authentication)
  improve automation even further and simplify handling repetitive tasks.

  ## New CLI scripts

  The sample scripts library now includes the following scripts for you to use:

  * [Provision users and folders](/guides/cli/scripts/powershell-script-templates) builds an
    onboarding folder structure and adds users.
  * [Manage groups and collaborations](/guides/cli/scripts/manage-groups-collaborations) creates or updates groups, add users to them, and finally add groups to folders as collaborators.
  * [Report inactive users](/guides/cli/scripts/report-inactive-users) generates a CSV file with a list of users who have been inactive for a specific number of days.
  * [Update user zones](/guides/cli/scripts/user-zones-mass-update) provisions users to a specific
    data residency zone within a Multizone Box tenant.
  * [Deprovision users](/guides/cli/scripts/deprovision-users) removes users.

  ## Bulk commands guide

  The [bulk commands guide](/guides/cli/cli-with-jwt-authentication/jwt-cli) explains how you can use a single command to perform actions involving multiple items.

  ## Developer Resources

  Are you interested in creating applications for the Box App Center or becoming a Box Partner? Check out the
  [Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) guides for more information!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-08-24">
  ## Box Windows SDK v4.5.0 released

  ### New Features and Enhancements

  * Add `content-type` field to sign request ([#850](https://github.com/box/box-windows-sdk-v2/issues/850)) ([`054d3e1`](https://github.com/box/box-windows-sdk-v2/commit/054d3e1a5f44b6a4a0292e8f9444266b2de0fff0))
  * expose `effective_access` in `BoxSharedLink` [#843](https://github.com/box/box-windows-sdk-v2/issues/843) ([`d84ddd4`](https://github.com/box/box-windows-sdk-v2/commit/d84ddd48aac489ecdd1d9dc740a7672cb064b0ca))

  ### Bug Fixes

  * fix null reference exception when it's not possible to get `runtime` version from the assembly ([#851](https://github.com/box/box-windows-sdk-v2/issues/851)) ([`77046fb`](https://github.com/box/box-windows-sdk-v2/commit/77046fb0c1ce80b6e7e2dc30058ed275e46e990c))
  * replace infinite retries with exponential backoff strategy in file representations ([#835](https://github.com/box/box-windows-sdk-v2/issues/835)) ([`f2a5713`](https://github.com/box/box-windows-sdk-v2/commit/f2a57136078de8b1fc59ec2c4a9e98c062d9d19b))

  - [https://www.nuget.org/packages/Box.V2/4.5.0>](https://www.nuget.org/packages/Box.V2/4.5.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/4.5.0>](https://www.nuget.org/packages/Box.V2.Core/4.5.0>)
</Update>

<Update label="2022-08-19">
  ## Box iOS SDK v5.3.0 released

  ### New Features and Enhancements

  * add `version_number` to `FileVersion` ([#853](https://github.com/box/box-ios-sdk/issues/853)) ([`ac81667`](https://github.com/box/box-ios-sdk/commit/ac81667ea409cbbe3de9be0c316c630ec6fbc2f5))
  * Add support for async API in `FoldersModule` ([#851](https://github.com/box/box-ios-sdk/issues/851)) ([`58b9dde`](https://github.com/box/box-ios-sdk/commit/58b9dde412eddc76915c99b960702f4af95b62a4))
  * Add support for file request API ([#867](https://github.com/box/box-ios-sdk/issues/867)) ([`ec7813e`](https://github.com/box/box-ios-sdk/commit/ec7813e31706c08aaaeac75debdba8d7802786cb))
  * Add support for upload and delete Avatar API ([#863](https://github.com/box/box-ios-sdk/issues/863)) ([`1e967f5`](https://github.com/box/box-ios-sdk/commit/1e967f5a3eaafbeb894cf8289032ad8ce8664266))
  * Add support of Editable Shared Link ([#861](https://github.com/box/box-ios-sdk/issues/861)) ([`bc6ea18`](https://github.com/box/box-ios-sdk/commit/bc6ea18bf2e10bebeb62401a55001139f05c76df))
  * Expose `send()` method public in `BoxClient` ([#843](https://github.com/box/box-ios-sdk/issues/843)) ([`23caaca`](https://github.com/box/box-ios-sdk/commit/23caaca5b6fe8ec1b23470193bc011a62c66d49f))

  ### Bug Fixes

  * Respect Content-Type coming from custom headers ([#841](https://github.com/box/box-ios-sdk/issues/841)) ([`a7c69a7`](https://github.com/box/box-ios-sdk/commit/a7c69a73c6142d4b82c718d2d311098dd2b70250))
</Update>

<Update label="2022-08-11">
  ## Box Java SDK v3.4.0 released

  ### New Features and Enhancements

  * Added pagination for getting items in trash with new `BoxTrash#items` API ([#1072](https://github.com/box/box-java-sdk/issues/1072)) ([`9cd411d`](https://github.com/box/box-java-sdk/commit/9cd411d20af1bc76ae815905396d72008af62539))

  ### Bug Fixes

  * buffered body write and fixed SDK logging ([#1079](https://github.com/box/box-java-sdk/issues/1079)) ([`bc35ef3`](https://github.com/box/box-java-sdk/commit/bc35ef3279e68a3d794de454f506ba41d14c3b16))
</Update>

<Update label="2022-08-09">
  ## Box Node SDK v2.5.0 released

  ### New Features and Enhancements

  * Added support update and remove user avatar ([#744](https://github.com/box/box-node-sdk/issues/744)) ([`aaf6175`](https://github.com/box/box-node-sdk/commit/aaf617528de5c61e19cfb25e28fe77c01532b9fa))

  ### Bug Fixes

  * Fix error while generate token using OAuth ([#750](https://github.com/box/box-node-sdk/issues/750)) ([`f826291`](https://github.com/box/box-node-sdk/commit/f82629108a1af6c4d160de1976fd01fdf0d8dde3)), closes [#286](https://github.com/box/box-node-sdk/issues/286)
  * Fix lint error in test file ([#747](https://github.com/box/box-node-sdk/issues/747)) ([`3b1e10d`](https://github.com/box/box-node-sdk/commit/3b1e10d206aa88a8bf99989bb7ff85776a9864a4))
</Update>

<Update label="2022-07-29">
  ## Box CLI v3.3.2 released

  ### Bug Fixes

  * Fix request command when calling without body ([#369](https://github.com/box/boxcli/issues/369)) ([`9317888`](https://github.com/box/boxcli/commit/9317888c3f1bff56ef784d7319f1b8ccf12239ef))
</Update>

<Update label="2022-07-25">
  ## Box CLI v3.3.1 released

  ### Bug Fixes

  * Fix OAuth login ([#364](https://github.com/box/boxcli/issues/364)) ([`579b44b`](https://github.com/box/boxcli/commit/579b44b83c60f6568c98cb5f1417effbac26c58c))
</Update>

<Update label="2022-07-23">
  ## Retention policy API improvements

  Recent changes to the API for retention policies and retention policy assignments allow you to remove retention policy assignments and specify the retention length and type for your policies.

  ## Updates

  * Use the new [`DELETE`](/reference/delete-retention-policy-assignments-id) endpoint to remove an existing retention policy assignment:

  ```bash theme={null}
  curl -i -X DELETE -L https://api.box.net/2.0/retention_policy_assignments/123456/
      -H 'Authorization: Bearer <ACCESS_TOKEN>' 
  ```

  * Specify the following parameters when [creating](/reference/post-retention-policies) or [updating](/reference/put-retention-policies-id) retention policies:

    * `retention_length`: Specifies the duration in days that the retention policy will be active for after being assigned to content.
    * `retention_type`: Specifies if the policy is `modifiable` or `non-modifiable`. This means you can either modify the retention policy in full or in a limited way depending on the need to comply with specific regulatory requirements.

  ## Developer Resources

  Are you interested in creating applications for the Box App Center or becoming a Box Partner? Check out the
  [Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) guides for more information!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-07-19">
  ## Box CLI v3.3.0 released

  ### New Features and Enhancements

  * add editable shared link support ([#350](https://github.com/box/boxcli/issues/350)) ([`ab639e7`](https://github.com/box/boxcli/commit/ab639e7e9336e8745ef84dd6dfc646c987638ec3))
  * add file requests API support ([#355](https://github.com/box/boxcli/issues/355)) ([`73f0490`](https://github.com/box/boxcli/commit/73f0490ff3c3dfefb89e14dde933d3a3ffc4113f))
  * add possibility to set custom analytics header ([#348](https://github.com/box/boxcli/issues/348)) ([`5a3387f`](https://github.com/box/boxcli/commit/5a3387fb687bcbd5d8441117c497312ac1d20f27))
  * support --copy-instance-on-item-copy flag for update metadata template ([#357](https://github.com/box/boxcli/issues/357)) ([`5d8272a`](https://github.com/box/boxcli/commit/5d8272a0559ec97a345a2032456998383e7a6716))
  * support Client Credentials Grant as authentication method ([#335](https://github.com/box/boxcli/issues/335)) ([`4649d8a`](https://github.com/box/boxcli/commit/4649d8adf39f64c8292b70c35b7bffa96e462edc))
</Update>

<Update label="2022-07-13">
  ## Box Node SDK v2.4.0 released

  ### New Features and Enhancements

  * Added support for file requests ([#742](https://github.com/box/box-node-sdk/issues/742)) ([`30b2e76`](https://github.com/box/box-node-sdk/commit/30b2e767c6c3af68e1463cc801914f9889dc593c))
  * Added support of `admin_logs_streaming` stream type ([#740](https://github.com/box/box-node-sdk/issues/740)) ([`406950a`](https://github.com/box/box-node-sdk/commit/406950a03af54a022427e0532e889a61e0d25152))

  ### Bug Fixes

  * properly handle client errors in streams ([#736](https://github.com/box/box-node-sdk/issues/736)) ([`12378d6`](https://github.com/box/box-node-sdk/commit/12378d6755c2e3cddcb79439cdcbbe8e1e61df13))
</Update>

<Update label="2021-06-24">
  ## New Box Sign webhook triggers

  The [Webhook Event Triggers](/guides/webhooks/triggers) now include the following Box Sign events you can use to trigger a version 2 webhook:

  * `SIGN_REQUEST.COMPLETED`
  * `SIGN_REQUEST.DECLINED`
  * `SIGN_REQUEST.EXPIRED`

  For details on creating webhooks read [this guide](/guides/webhooks/v2/create-v2).

  ## Developer Resources

  Are you interested in creating applications for the Box App Center or becoming a Box Partner? Check out the
  [Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) guides for more information!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-07-06">
  ## Updated Cross-Origin Resource Sharing (CORS) documentation

  We updated the documentation on [Cross-Origin Resource Sharing
  (CORS)](/guides/security/cors).

  ## Updates

  Added information on what to do in case of the `Access-Control-Allow-Origin` header issues.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum).
</Update>

<Update label="2022-07-06">
  ## Box Python SDK v3.4.0 released

  ### New Features and Enhancements

  * Add support for editable shared links for files ([#737](https://github.com/box/box-python-sdk/issues/737)) ([`1396200`](https://github.com/box/box-python-sdk/commit/1396200c24bf62de63f9cb7949af5997593b9fac))
  * Support uploading and deleting user avatar ([#743](https://github.com/box/box-python-sdk/issues/743)) ([`fe00a9e`](https://github.com/box/box-python-sdk/commit/fe00a9eb3434ee14bc4f01332d54c0272ed5f2d3))
</Update>

<Update label="2022-07-04">
  ## Box Java SDK v3.3.0 released

  ### New Features and Enhancements

  * Added support of Editable Shared Links ([#1064](https://github.com/box/box-java-sdk/issues/1064)) ([`9b7d60c`](https://github.com/box/box-java-sdk/commit/9b7d60c41fbd481465bf3f2a5877746f10849712))

  ### Bug Fixes

  * Fix closed stream exception in `canUpload` method ([#1067](https://github.com/box/box-java-sdk/issues/1067)) ([`543f91c`](https://github.com/box/box-java-sdk/commit/543f91c46dfcc9de7e61ce11cd93d472916533ac))
</Update>

<Update label="2021-06-30">
  ## Improvements in Web App Integrations documentation

  We updated documentation on creating [Web App Integrations](/guides/applications/web-app-integrations/configure) with Custom Apps to reflect all the information from the developer console.

  ## Updates

  * Added description of all elements in the **App Info** section.
  * Expanded the **Callback Parameters** section with information about parameter syntax.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum).
</Update>

<Update label="2022-06-30">
  ## Box CLI v3.2.0 released

  ### New Features and Enhancements

  * Added support for stream type `admin_logs_streaming` ([#337](https://github.com/box/boxcli/issues/337)) ([`7596157`](https://github.com/box/boxcli/commit/7596157e3a72ef152be44a04198e38d6c57de250))

  ### Bug Fixes

  * Fix native storage errors ([#345](https://github.com/box/boxcli/issues/345)) ([`b73b841`](https://github.com/box/boxcli/commit/b73b841224ad7f5bb543c92962adb7fc5960bb8c))
</Update>

<Update label="2021-06-24">
  ## Box Sign API supports setting redirect URLs

  The [Box Sign API](https://developer.box.com/reference/post-sign-requests/) now offers new parameters to set up custom redirect URLs
  for users who sign or decline a sign request. This way, when integrating your application
  with Box Sign, you can redirect the signers
  back to your application or display a custom landing page.

  ## Updates

  Box Sign API provides optional parameters to pass in the request body of the [Create Sign Request](https://developer.box.com/guides/box-sign/create-sign-request/) call:

  * `redirect_url` that redirects the user to a specific page after signing a request
  * `declined_redirect_url` that redirects the user to a specific page after declining a request

  You can define redirect URLs globally for all signers and for specific signers only.
  For details, see the [Create Sign Request](https://developer.box.com/guides/box-sign/create-sign-request/) guide.

  ## Developer Resources

  Are you interested in creating applications for the Box App Center or becoming a Box Partner? Check out the
  [Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) guides for more information!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-06-24">
  ## Automate tasks with Box CLI and scripts library

  The [Box CLI](/guides/cli) now features a sample scripts library with templates you can use to automate your tasks.
  For starters, we wanted to provide you with a PowerShell script that allows you to:

  * set up a folder structure,
  * create managed users,
  * add the users to the folder structure as collaborators.

  ## Updates

  * The Box CLI [quick start guide](/guides/cli/scripts/powershell-script-templates) now provides instructions on using a PowerShell script to create a folder structure and collaborators.
  * The [scripts library](https://github.com/box/boxcli/tree/main/examples) is where you can find all sample scripts. Currently, it includes the PowerShell script but more samples are on the way!

  ## Developer Resources

  Are you interested in creating applications for the Box App Center or becoming a Box Partner? Check out the
  [Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) guides for more information!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-06-17">
  ## Box CLI v3.1.0 released

  ### New Features and Enhancements

  * Add --all flag for search to return all results ([#336](https://github.com/box/boxcli/issues/336)) ([`23ea0a5`](https://github.com/box/boxcli/commit/23ea0a5c5b065ea3b91b73b64bb7b267a6ff0a18))
  * add unique state parameter to `OAuth2` login ([#292](https://github.com/box/boxcli/issues/292)) ([`5ce6a40`](https://github.com/box/boxcli/commit/5ce6a40b4c6e2fc78b2b598a8b1529200c63902e))
  * allow changing base URLs ([#303](https://github.com/box/boxcli/issues/303)) ([`e284059`](https://github.com/box/boxcli/commit/e28405971ebcf2c2284bb875b40ceb7eaebb41c4))
  * obtain `oauth` authorization from command line ([#299](https://github.com/box/boxcli/issues/299)) ([`18c88bb`](https://github.com/box/boxcli/commit/18c88bb6835509394b92eb0685e3a9306ede8984))
  * use native credential storage for MacOS and Windows ([#295](https://github.com/box/boxcli/issues/295)) ([`74c4922`](https://github.com/box/boxcli/commit/74c492271ebc54e15500abbaaa2c7aac32be5070))

  ### Bug Fixes

  * `users:transfer-content` to respect quiet flag ([#288](https://github.com/box/boxcli/issues/288)) ([`1d0bbab`](https://github.com/box/boxcli/commit/1d0bbab652bf74a59c8486fc4d5eac415161254c))
  * correctly pass `copy-instance-on-item-copy` flag ([#285](https://github.com/box/boxcli/issues/285)) ([`cd4fbf4`](https://github.com/box/boxcli/commit/cd4fbf4f746b83c2b066efb31b2e2952dba1312d))
  * Fix updating webhook triggers ([#297](https://github.com/box/boxcli/issues/297)) ([`09e94c3`](https://github.com/box/boxcli/commit/09e94c32ed8e4243e76dd19e67b6d1c17c2cdc04))
  * support large output when using `json` flag by replacing `json.stringify` ([#328](https://github.com/box/boxcli/issues/328)) ([`1204f2c`](https://github.com/box/boxcli/commit/1204f2c146c713124060730e0554ab2f2dde27fa))
  * Support limit flag for Box Search ([#323](https://github.com/box/boxcli/issues/323)) ([`0009a77`](https://github.com/box/boxcli/commit/0009a77ee3fc4b72ef01bbbeff0ea588c10a6f89)), closes [#322](https://github.com/box/boxcli/issues/322)
  * Support OAuth with multiple redirect URIs ([#302](https://github.com/box/boxcli/issues/302)) ([`9fe216e`](https://github.com/box/boxcli/commit/9fe216e8d2f59e4375a4b7c766844366f7166a0a))
</Update>

<Update label="2022-06-14">
  ## Box Windows SDK v4.4.0 released

  ### New Features and Enhancements

  * add `can_edit` field to `SharedLink` ([#831](https://github.com/box/box-windows-sdk-v2/issues/831)) ([`e0d4197`](https://github.com/box/box-windows-sdk-v2/commit/e0d4197070db0dbd947f4a51a6bbb1e01c0b0cdf))
  * add `version_number` to `BoxFileVersion` ([#820](https://github.com/box/box-windows-sdk-v2/issues/820)) ([`f174358`](https://github.com/box/box-windows-sdk-v2/commit/f174358973caefc9262df480208341fd8233dc7f))
  * add upload and delete support for Avatar API ([#829](https://github.com/box/box-windows-sdk-v2/issues/829)) ([`4dcb84a`](https://github.com/box/box-windows-sdk-v2/commit/4dcb84ade78d6bd0bc621ff2ed7f5f886486858a))

  ### Bug Fixes

  * Fix initialization of `BoxAPIException` object ([#828](https://github.com/box/box-windows-sdk-v2/issues/828)) ([`a298f01`](https://github.com/box/box-windows-sdk-v2/commit/a298f01187f84200825ec6ed4748fe8bbd717d11))
  * properly dispose response on exception ([#819](https://github.com/box/box-windows-sdk-v2/issues/819)) ([`8415bd3`](https://github.com/box/box-windows-sdk-v2/commit/8415bd3dbe42910b99f99535247a26f8d8e645c1))

  - [https://www.nuget.org/packages/Box.V2/4.4.0>](https://www.nuget.org/packages/Box.V2/4.4.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/4.4.0>](https://www.nuget.org/packages/Box.V2.Core/4.4.0>)
</Update>

<Update label="2022-06-11">
  ## Box Java SDK v3.2.1 released

  ### Bug Fixes

  * Fix getting proper URL to authenticate with OAuth ([#1059](https://github.com/box/box-java-sdk/issues/1059)) ([`42876b4`](https://github.com/box/box-java-sdk/commit/42876b45ccdb7fa6f357186cecaba051abf1c269)), closes [#1057](https://github.com/box/box-java-sdk/issues/1057)
</Update>

<Update label="2021-05-24">
  ## New Box App Center (formally App Gallery)

  You can now visit the completely updated [Box App Center](https://app.box.com/app-center) to find the over 1500+ integrations you already know and love.
  [Box App Center](https://app.box.com/app-center) provides a modernized catalog of apps and integrations and will be accessible from the Box Web app.

  For end-users, the Box App Center makes it smoother to work the way you want to, thanks to the comprehensive selection of ready-to-use integrations from partners such
  as Microsoft, Zoom, Salesforce, and Slack, to name a few.

  For IT leaders and admins, the Box App Center gives your users choice, without sacrificing security or user experience. And it eliminates shadow IT by providing a
  list of enterprise-approved options.

  Box App Center will be part of the Core Box package; The Box App Center is available to **all** customers today!

  ## Developer Resources

  Are you interested in creating applications for the Box App Center or becoming a Box Partner? Check out the
  [Box Partner Resources](https://support.box.com/hc/en-us/sections/360009473734-Box-Partner-Resources) guides for more information!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-05-24">
  ## Box Java SDK v3.2.0 released

  ### New Features and Enhancements

  * Revamped setting base URLs ([#1042](https://github.com/box/box-java-sdk/issues/1042)) ([`129baf7`](https://github.com/box/box-java-sdk/commit/129baf704ced127788bb0f62ef9f4fb6a50fdc63))
  * support for Avatar V2 API ([#1044](https://github.com/box/box-java-sdk/issues/1044)) ([`18651d7`](https://github.com/box/box-java-sdk/commit/18651d7a5b419796e3733c7582ae471d7af7ed5c))
</Update>

<Update label="2022-05-18">
  ## OAuth 2.0 Redirect URL Strict Checking Enabled

  Today, we turned on strict checking for all OAuth 2.0 applications.

  On November 29, 2021, we [announced](/changelog/2021) new applications using OAuth 2.0 will require the
  URIs set in the configuration tab of the Developer Console to strictly match the
  one used during redirect.

  This change has now been completed. If your enterprise had applications that were not following this standard,
  you should have received four emails over the past few months describing how to update your applications.

  ## How to solve redirect errors

  If you did not receive the email or missed the communication, below you will find the steps to mitigate any issues.

  1. You can change the redirect URL in the Box Developer Console configuration tab for your application. If the URLs are
     static, then you can update the Developer console to add multiple URLs. If the URLs are dynamic, then update your
     application to use a static URL or use the state parameter.
  2. You can change the redirect URL used in your application code to strictly match the URL in the developer console.

  For option #1, please use these steps:

  * Login to Box as the application owner and navigate to the Box Developer Console
  * Click on the application and navigate to the configuration tab
  * Scroll down to the "OAuth 2.0 Redirect URI" section
  * Update the current URL listed

  For option #2, please modify your application code to replace the impacted used URLs to strictly match the URL in the Developer Console.

  ## Updates

  * Redirect URIs now force strict checking to match the URI passed in and URIs configured in the OAuth 2.0 application configuration

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) or file a ticket
  with [Box Support](https://support.box.com/hc/en-us/requests/new).
</Update>

<Update label="2022-05-18">
  ## New Endpoints to Manage User Avatars

  Starting today, the User Avatar APIs supports adding, updating, and deleting user avatars.

  To create or update a user avatar, call the [`POST /users-id-avatar`](/reference/post-users-id-avatar) endpoint. Remember to include the path to the file you want to upload. If an avatar already exists, it will be replaced with the new photo uploaded.

  ```sh theme={null}
  curl -i -X POST -L https://api.box.net/2.0/users/userID/avatar 
      -H 'Authorization: Bearer <ACCESS_TOKEN>' 
      --form 'pic=@"path/to/file/file.jpeg"'
  ```

  The response includes the [user avatar](/reference/resources/user-avatar) object with URLs to the file location.

  To delete a user avatar, call the [`DELETE /users-id-avatar`](/reference/delete-users-id-avatar) endpoint:

  ```sh theme={null}
  curl -i -X DELETE -L https://api.box.net/2.0/users/userID/avatar 
      -H 'Authorization: Bearer <ACCESS_TOKEN>'
  ```

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-05-16">
  ## Box UI Elements v15.0.0 released

  ## [15.0.0](https://github.com/box/box-ui-elements/releases/tag/v15.0.0) (2022-05-16)

  ## Bug Fixes & Features

  This release fixes several bugs and adds new features.
  For a full list of changes, [please see the release notes](https://github.com/box/box-ui-elements/releases/tag/v15.0.0).
</Update>

<Update label="2022-05-12">
  ## New Field Added to Sign Requests

  Box Sign request response objects now include a new field - `content_type`. This field identifies the type of content expected for the `type` of `input` selected for the signer to complete.

  ## Updates

  * Added new field `content_type` to the [sign request response object](/reference/resources/sign-request/#param-signers-inputs-content_type)

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum).
</Update>

<Update label="2022-05-11">
  ## New Fields Added to Event Specification

  The Event resource specification now includes two new fields:

  * `created_at` specifying when an event was created
  * `recorded_at` specifying when an event was registered in the database

  ## Updates

  * Added new fields `created_at` and `recorded_at` to the \[Event] resource specification [2](/reference/resources/event).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-05-06">
  ## New Field Added to Sign Events Payload

  The `additional_details` Sign Events payload now includes the `batch_send` field identifying a sign request sent to multiple recipients at once. If such a batch send request exists, the payload also provides its `id`.

  ## Updates

  * Added new field `batch_send` to `additional_details` payload for [Sign Events](/guides/events/event-triggers/sign-events).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2021-05-06">
  ## New Editable Shared Links API

  Now, developers can make files editable via shared links using the API.

  ## Documentation Updates

  * Added a new `can_edit` value to the `permissions` object for the [file](/reference/resources/file--full#param-shared_link-permissions), [folder](/reference/resources/folder--full#param-shared_link-permissions), and [web link](/reference/resources/web-link/#param-shared_link-permissions) resources
  * Added a new `shared_link_permission_options` field to the [`file--full`](/reference/resources/file--full/#param-shared_link_permission_options) resource
  * Added a [shared link section for web links](/reference/get-shared-items--web-links) in the reference documentation
  * Added a [permissions page](/guides/shared-links/permissions) to the shared links guide documentation
  * Combined the [update and add shared link](/guides/shared-links/create-or-update) guide page since they utilize the same PUT endpoint
  * Updated code snippets across several shared link pages

  ## Enhancement Details

  * Instead of having to collaborate a user into a file to give edit access, you can set the `shared_link.permissions.can_edit` field to `true`.
  * The `can_edit` field will be returned for all shared link objects on files, folders, and web links; however, you can only set it to true for a file.
  * Our SDK libraries will gain this feature in the coming quarters.
  * If an admin has turned off editable shared links in the admin console, you will not be able to use this feature.

  ### cURL Example

  ```curl theme={null}
  curl -i -X PUT 'https://api.box.com/2.0/files/123456789?fields=shared_link' \
          -H 'Content-Type: application/json' \
          -H 'Authorization: Bearer [ACCESS TOKEN]' \
          -d '{
            "shared_link": {
              "permissions": {
                "can_preview": true,
                "can_download": true,
                "can_edit": true
              }
            }
          }'
  ```

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-04-28">
  ## Box Python SDK v3.3.0 released

  ### New Features and Enhancements

  * Add support for multiple date time formats ([#722](https://github.com/box/box-python-sdk/issues/722)) ([`92364de`](https://github.com/box/box-python-sdk/commit/92364de1e7c1eee1e85857546af65c307ca863a0))

  ### Bug Fixes

  * Add missing fields to metadata template field ([#719](https://github.com/box/box-python-sdk/issues/719)) ([`9e574a3`](https://github.com/box/box-python-sdk/commit/9e574a3e56f72c0e78a31ddda78bc11d36ff3516)), closes [#717](https://github.com/box/box-python-sdk/issues/717)
  * Upload session commit return None on 202 ([#718](https://github.com/box/box-python-sdk/issues/718)) ([`86a1856`](https://github.com/box/box-python-sdk/commit/86a185630e6cce8f742123c7340da08267621313)), closes [#715](https://github.com/box/box-python-sdk/issues/715)
</Update>

<Update label="2022-04-28">
  ## Box Node SDK v2.3.0 released

  ### New Features and Enhancements

  * Add `description` parameter to `uploadFile` methods ([#730](https://github.com/box/box-node-sdk/issues/730)) ([`2596584`](https://github.com/box/box-node-sdk/commit/2596584dffb44c1995c8b6b3faa67564f4d32499))

  ### Bug Fixes

  * added missing `js-docs` on shared links ([#731](https://github.com/box/box-node-sdk/issues/731)) ([`3554d41`](https://github.com/box/box-node-sdk/commit/3554d41d9050e7a81224c35e3e2e257604a0b41b))
</Update>

<Update label="2022-04-22">
  ## Box iOS SDK v5.2.1 Released

  ### Bug Fixes

  * Expose fields from `BoxResponse` for custom API calls ([#833](https://github.com/box/box-ios-sdk/issues/833)) ([`bae1536`](https://github.com/box/box-ios-sdk/commit/bae1536236a22de198281012b0ee43c84b0e3485))
</Update>

<Update label="2022-04-21">
  ## Improvements In Platform Apps Approval Flow

  Today we added further improvements to the platform apps approval flow. As a result, you can now use a new **Enablement** tab in Developer Console to directly request a Box Admin to enable OAuth 2.0 platform apps.

  Additionally, Box Admins can use Platform Apps Manager to view and enable platform apps in Admin Console.

  ## Updates

  * **Enablement** tab was added for OAuth 2.0 platform apps.
  * Information on enabling OAuth 2.0 platform applications has been added to the [platform app approval](/guides/authorization/platform-app-approval) guide page.
  * Screenshots have been updated on the [platform app approval](/guides/authorization/platform-app-approval) and [setup with OAuth 2.0](/guides/authentication/oauth2/oauth2-setup) guide pages.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-04-20">
  ## Box Node SDK v2.2.0 released

  ### New Features and Enhancements

  * editable shared links ([#722](https://github.com/box/box-node-sdk/issues/722)) ([`f0c0135`](https://github.com/box/box-node-sdk/commit/f0c0135511fde46144e6c496432104321af443f6))
</Update>

<Update label="2022-04-19">
  ## Box Windows SDK v4.3.1 released

  ### Bug Fixes

  * simplify base `urls` usage ([#815](https://github.com/box/box-windows-sdk-v2/issues/815)) ([`f8e7344`](https://github.com/box/box-windows-sdk-v2/commit/f8e73447afa5c0a893c3c4ace922fc360a376f66))

  - [https://www.nuget.org/packages/Box.V2/4.3.1](https://www.nuget.org/packages/Box.V2/4.3.1)
  - [https://www.nuget.org/packages/Box.V2.Core/4.3.1](https://www.nuget.org/packages/Box.V2.Core/4.3.1)
</Update>

<Update label="2022-04-06">
  ## Notice of behavior change for collaboration events on the changes stream

  Starting today, we will begin rolling out changes to the behavior of
  collaboration events when an application consumes those events from our
  [event API endpoints](https://developer.box.com/reference/get-events/).

  This change will only affect `COLLAB_INVITE_COLLABORATOR`,
  `COLLAB_ADD_COLLABORATOR`, `COLLAB_ROLE_CHANGE`, and
  `COLLAB_REMOVE_COLLABORATOR` [user events](https://developer.box.com/guides/events/user-events/for-user/#event-types)
  with the query parameter `stream_type` set to `changes`.
  This will not affect existing [enterprise events](https://developer.box.com/guides/events/enterprise-events/for-enterprise/).
  The new behavior will not cause downtime within existing applications
  or require any application changes to prevent uptime disruptions.

  ## Change overview

  Previously, events of type `COLLAB_INVITE_COLLABORATOR`,
  `COLLAB_ADD_COLLABORATOR`, `COLLAB_ROLE_CHANGE`, and
  `COLLAB_REMOVE_COLLABORATOR` created notifications
  for the acted upon users that were listening to the `changes` stream.
  Owners of the collaborated item would not receive these events unless
  they were listening to the `all` stream as well.

  We are cleaning up this discrepancy by establishing parity
  between the `all` and `changes` stream. With this new behavior,
  notifications of a collaboration will be created for the content owner
  on the `changes` stream as well. Collaboration owners will now see an
  additional event that matches what they see on the `all` stream.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-04-01">
  ## Box Windows SDK v4.3.0 released

  ### New Features and Enhancements

  * add `SourceLink` support for Core project ([#795](https://github.com/box/box-windows-sdk-v2/issues/795)) ([`a9cbede`](https://github.com/box/box-windows-sdk-v2/commit/a9cbedece2ffb4f832be880bebf35b715c9cb28b))

  ### Bug Fixes

  * add missing enum to string parsing in several places ([#813](https://github.com/box/box-windows-sdk-v2/issues/813)) ([`e370282`](https://github.com/box/box-windows-sdk-v2/commit/e3702826216132dfe1fb061af95a8d9700f114d4))
  * properly cast response when uploading a new file version using session ([#810](https://github.com/box/box-windows-sdk-v2/issues/810)) ([`73d877f`](https://github.com/box/box-windows-sdk-v2/commit/73d877ff679b5999ea50cdfa68f14b0e2169ea65))

  - [https://www.nuget.org/packages/Box.V2/4.3.0](https://www.nuget.org/packages/Box.V2/4.3.0)
  - [https://www.nuget.org/packages/Box.V2.Core/4.3.0](https://www.nuget.org/packages/Box.V2.Core/4.3.0)
</Update>

<Update label="2022-03-28">
  ## Box Node SDK v2.1.0 released

  ### New Features and Enhancements

  * Client Credentials Grant authentication method ([#709](https://github.com/box/box-node-sdk/issues/709)) ([`fbf4e80`](https://github.com/box/box-node-sdk/commit/fbf4e80648821e38479b24bf489e7d222ae6c18f))
  * Deprecating `index_name` when executing metadata query ([#686](https://github.com/box/box-node-sdk/issues/686)) ([`e01cc65`](https://github.com/box/box-node-sdk/commit/e01cc650e4e793955be543e93928ad82a3254492))
  * **test:** add support for testing with Jest ([#676](https://github.com/box/box-node-sdk/issues/676)) ([`1a11759`](https://github.com/box/box-node-sdk/commit/1a11759db999510c69d6a27f7becd565620bb000))

  ### Bug Fixes

  * Client Credentials Grant authentication method supports token down-scoping ([#710](https://github.com/box/box-node-sdk/issues/710)) ([`730368f`](https://github.com/box/box-node-sdk/commit/730368f410ff56e9a8c90feea2192b29c08df198))
  * Fix JWT expiration field being float instead of integer ([#715](https://github.com/box/box-node-sdk/issues/715)) ([`7e950f1`](https://github.com/box/box-node-sdk/commit/7e950f1265a52ce251c42a186c8196089a9ed858)), closes [#713](https://github.com/box/box-node-sdk/issues/713)
</Update>

<Update label="2021-03-24">
  ## New Search API Query Parameter

  Now, you can filter searching for content in the API using the new field `recent_updater_user_ids`.

  ## Updates

  * Added new query parameter `recent_updater_user_ids` to the [`GET /get-search`](/reference/get-search/#param-recent_updater_user_ids) API endpoint

  ## Features

  * Limits the search results to any items that have been updated by the given list of users, defined as a list of comma separated user IDs.
  * This feature only searches back to the last 10 versions of an item.

  ### cURL Example

  ```curl theme={null}
  curl -i -X GET "https://api.box.com/2.0/search?query=sales&recent_updater_user_ids=1234567890,2314567890" \
       -H "Authorization: Bearer <ACCESS_TOKEN>"
  ```

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-03-22">
  ## Box Java SDK v3.1.2 Released

  ### Bug Fixes

  * Allow using `As-User` header with CCG Authentication ([#1031](https://github.com/box/box-java-sdk/issues/1031)) ([`b0c2389`](https://github.com/box/box-java-sdk/commit/b0c238913cc1dbcecfd546a5eae68277c3c76d42))
  * Fix retry logic when `Retry-After` header is present ([#1033](https://github.com/box/box-java-sdk/issues/1033)) ([`05224c4`](https://github.com/box/box-java-sdk/commit/05224c433d2a101a01959644674153df9542b711))
</Update>

<Update label="2022-03-18">
  ## Box iOS SDK v5.2.0 released

  ### New Features and Enhancements

  * Add `disposition_at` field to the `File` object ([#814](https://github.com/box/box-ios-sdk/issues/814)) ([`3c90df0`](https://github.com/box/box-ios-sdk/commit/3c90df038b9f490a9d38af85404fa1d6ddcd5d0d))
  * Add support for Client Credentials Grant authentication method ([#821](https://github.com/box/box-ios-sdk/issues/821)) ([`f6d7542`](https://github.com/box/box-ios-sdk/commit/f6d75424e8c0d91517e3ffb8df67f77ad3f2374b))
</Update>

<Update label="2022-03-17">
  ## New Box CLI YouTube Video

  Back in February, we [launched](/changelog/2022) the OAuth 2.0 version of the Box CLI, alongside
  new YouTube content. Today, we released [video 2](https://www.youtube.com/watch?v=66wlIyS07Aw\&list=PL0F3BD5B64D6A39F1\&index=2) of the series. It shows
  using the built in help functionality to create a folder with the CLI.

  You can find the Box Platform and Developer Playlist on [YouTube](https://www.youtube.com/playlist?list=PL0F3BD5B64D6A39F1). We have two
  more videos planned: Advanced Topics (including as-user) and CLI Automation
  using PowerShell.

  Make sure to [subscribe](https://www.youtube.com/user/box/featured) to the Box Channel to get all the latest content!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-03-16">
  ## Announcing SDK Supported Versions

  Starting July 30 2022, only the current **major** version of a SDK will be supported. New features,
  functionality, bug fixes, and security updates will only be added to the
  current **major** version.

  A current release is on the leading edge of our SDK development, and is intended for customers who are in active development and want the latest and greatest features.
  Instead of stating a release date for a new feature, we set a fixed minor or patch release cadence of maximum 2-3 months (while we may release more often). At the same
  time, there is no schedule for major or breaking release. Instead, we will communicate one quarter in advance the upcoming breaking change to allow customers to plan for
  the upgrade. We always recommend that all users run the latest available minor release for whatever major version is in use. We highly recommend upgrading to the latest
  SDK major release at the earliest convenient time and before the EOL date.

  We use a modified version of [Semantic Versioning](https://semver.org/) for all changes. See
  [version strategy](https://github.com/box/box-windows-sdk-v2/blob/main/VERSIONS.md) for details.

  ## Supported version for each SDK

  Below find links to the charts of supported versions for all SDKs.

  * [Python](https://github.com/box/box-python-sdk#version-schedule)
  * [.NET](https://github.com/box/box-windows-sdk-v2#supported-version)
  * [Java](https://github.com/box/box-java-sdk#version-schedule)
  * [node](https://github.com/box/box-node-sdk#supported-version)
  * [CLI](https://github.com/box/boxcli#supported-version)
  * [iOS](https://github.com/box/box-ios-sdk#supported-version)

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-03-11">
  ## Box Python SDK v3.2.0 released

  ### New Features and Enhancements

  * Add setting `disposition_at` field for files under retention ([#710](https://github.com/box/box-python-sdk/issues/710)) ([`91b1373`](https://github.com/box/box-python-sdk/commit/91b13730a0beef2cf2a8a8c71087b11557fa5982))
  * Add support for Client Credentials Grant authentication method ([#705](https://github.com/box/box-python-sdk/issues/705)) ([`d33d16d`](https://github.com/box/box-python-sdk/commit/d33d16db656cb5578f057a7e24f5396d635b5361))

  ### Bug Fixes

  * Add missing `box_sign` object to `__all__` list ([#708](https://github.com/box/box-python-sdk/issues/708)) ([`5d80481`](https://github.com/box/box-python-sdk/commit/5d8048116640fa672d6a1d700a6c1111faf87bb9))
  * Fix `jwt` import errors ([#711](https://github.com/box/box-python-sdk/issues/711)) ([`ee7bb6f`](https://github.com/box/box-python-sdk/commit/ee7bb6f1dc5aa65dbf6ffeb18ee130f765f7b49b))
</Update>

<Update label="2022-03-03">
  ## Developer Documentation Updates

  Today, we released several updates and bug fixes to our developer documentation. Click below to find out more information!

  ## Updates

  * Added additional trailing backslashes for [metadata query](/guides/metadata/queries/create) examples
  * Removed extra quotes from [metadata query](/guides/metadata/queries/create) examples
  * Updated and added examples for [Shield Smart Access](/guides/events/event-triggers/shield-alert-events/#smart-access) events
  * Added note to the `can_view_path` [field](/reference/post-collaborations/#param-can_view_path)
  * Corrected [trash](/reference/get-folders-id-trash) resources to represent the right responses returned by the API
  * Added an `iOS` filter to the changelog
  * Added note to folder lock [endpoint](/reference/resources/folder-lock)
  * Added note to [developer token](/guides/authentication/tokens/developer-tokens) guide that says revoking token removes webhook
  * Removed the `94x94` option from the [thumbnail](/reference/get-files-id-thumbnail-id) endpoint
  * Added note to the events [`limit` parameter](/reference/get-events/#param-limit)
  * Added note to the [user `login` parameter](/reference/put-users-id/#param-login)
  * Added app users to the PUT [`user`](/reference/put-users-id/#param-login) endpoint
  * Added `external_app_user_id` field to the PUT [`user`](/reference/put-users-id/#param-login) endpoint
  * Changed all references throughout documentation of `X-REF-HINTS` to `x-rep-hints`
  * Added new fields to all 11 Box Sign [events](/guides/events/event-triggers/sign-events)

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-02-28">
  ## Box Java SDK v3.1.1 released

  ### Bug Fixes

  * retry `jwt` auth when error code is in error field ([#1020](https://github.com/box/box-java-sdk/issues/1020)) ([`8c9d11d`](https://github.com/box/box-java-sdk/commit/8c9d11d1b3556552751c9f4ac99a0f7180af97f3)), closes [#1019](https://github.com/box/box-java-sdk/issues/1019)
</Update>

<Update label="2022-02-18">
  ## Box Java SDK v3.1.0 released

  ### New Features and Enhancements

  * Added support for Client Credentials Grant authentication method ([#1002](https://github.com/box/box-java-sdk/issues/1002)) ([`9cfcaff`](https://github.com/box/box-java-sdk/commit/9cfcaff243dbf0541409f91f9f863a207345dc47))
  * API to extend disposition date on a file ([#1001](https://github.com/box/box-java-sdk/issues/1001)) ([`f3f6b60`](https://github.com/box/box-java-sdk/commit/f3f6b6043eec362c5a8ad9a01d6588538ca34e71))
  * Deprecating `indexName` when executing metadata query ([#1000](https://github.com/box/box-java-sdk/issues/1000)) ([`c20dbbf`](https://github.com/box/box-java-sdk/commit/c20dbbf6a927e31cfdd7ffa71069c0897f7a0536))

  ### Dependency Upgrades

  * Upgrade Gradle to 7.3.3 ([#985](https://github.com/box/box-java-sdk/issues/985)) ([`e4acbb1`](https://github.com/box/box-java-sdk/commit/e4acbb1f0c10ccdeeee139e2566b344052680010))
</Update>

<Update label="2022-02-10">
  ## Client Credentials support in the SDKs

  Our [`.NET`](https://github.com/box/box-windows-sdk-v2) and [`Java`](https://github.com/box/box-java-sdk) SDKs now support Client Credentials Grant
  authentication. We plan to release the support for the other SDKs in the
  coming weeks.

  Back in November 2020, we released a new authentication type for custom
  applications called Client Credentials. Today, we have started releasing SDK
  support for the new type.

  ## Updates

  * Added new sample tags and examples on our [Client Credentials guide page](/guides/authentication/client-credentials/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-02-16">
  ## Box Python SDK v3.1.0 released

  ### New Features and Enhancements

  * Add support for Python 3.10 ([#692](https://github.com/box/box-python-sdk/issues/692)) ([`d4aed82`](https://github.com/box/box-python-sdk/commit/d4aed82831af97305bace9a4588d27b23856c306))
  * Add support for Python 3.8, Python 3.9, `pypy-3.7` and `pypy-3.8`. ([#689](https://github.com/box/box-python-sdk/issues/689)) ([`0aa94cc`](https://github.com/box/box-python-sdk/commit/0aa94cc8a5c4db0fc204b27a60690b73c98a89cb))
  * Deprecate `use_index` parameter from `MDQ` of files/folders ([#666](https://github.com/box/box-python-sdk/issues/666)) ([`2595720`](https://github.com/box/box-python-sdk/commit/25957204b82c878e15dc3d118505a741171e9772))
  * Replace external package `mock` with Python standard library `unittest.mock` ([#697](https://github.com/box/box-python-sdk/issues/697)) ([`6fd6366`](https://github.com/box/box-python-sdk/commit/6fd63667aa7da4c794b4fb880d5c2949efe0073f))
  * Upgrade cryptography library to the most recent version. ([#668](https://github.com/box/box-python-sdk/issues/668)) ([`9c94d08`](https://github.com/box/box-python-sdk/commit/9c94d0878515dc75c1f267e2fb1f189a852772b6)), closes [#667](https://github.com/box/box-python-sdk/issues/667)

  ### Bug Fixes

  * `UploadSession.commit` returns `None` when retry limit was reached ([#696](https://github.com/box/box-python-sdk/issues/696)) ([`9456fe0`](https://github.com/box/box-python-sdk/commit/9456fe0124f4ac4e9c8a7bcc49039f07f310c477))
  * Add missing `api_call` decorator for `create_upload_session` ([#686](https://github.com/box/box-python-sdk/issues/686)) ([`3510d3a`](https://github.com/box/box-python-sdk/commit/3510d3ac085767205854014ecef80fd078d71773))
  * Fix chunked upload ([#673](https://github.com/box/box-python-sdk/issues/673)) ([`2605fd7`](https://github.com/box/box-python-sdk/commit/2605fd782396ad6e42bd11c10f846e771634b7a0)), closes [#671](https://github.com/box/box-python-sdk/issues/671)
</Update>

<Update label="2022-01-25">
  ## New Box Shield Access Policy Monitoring Mode

  Recently, Box Shield added a [new feature](https://docs.box.com/en/box-shield/shield-smart-access-policies/about-smart-access#access-policy-enforcement-and-monitoring) that allows admins to test out Access Policies with a new monitoring mode.

  ## Updates

  * Added the new `controlMode` field to all events in the [Smart Access events section](/guides/events/event-triggers/shield-alert-events/#smart-access)
  * Added application and FTP restriction information in the Smart Access events section

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://community.box.com/box-platform-5) for any help needed.
</Update>

<Update label="2022-02-10">
  ## Box Windows SDK v4.2.0 released

  ### Bug Fixes

  * correctly pass null when rolling out user from the enterprise ([#792](https://github.com/box/box-windows-sdk-v2/issues/792)) ([`c85c573`](https://github.com/box/box-windows-sdk-v2/commit/c85c5735865b7dd97ffa1428a8f57d2edff6811b))
  * Creating `BoxAuthenticationFailedException` no longer throws an exception ([#790](https://github.com/box/box-windows-sdk-v2/issues/790)) ([`55a706e`](https://github.com/box/box-windows-sdk-v2/commit/55a706e4091271aa55208a260b2f4f96e1527698))
  * Null Argument Exception in `AutoPaginate` ([#666](https://github.com/box/box-windows-sdk-v2/issues/666)) ([`c61f08c`](https://github.com/box/box-windows-sdk-v2/commit/c61f08cc02d5c95ff71ef700e97393a0dc3dc890))

  ### New Features and Enhancements

  * add `admin_logs_streaming` support ([#797](https://github.com/box/box-windows-sdk-v2/issues/797)) ([`a775e1e`](https://github.com/box/box-windows-sdk-v2/commit/a775e1e5c7696a1e5f82b5dc7edbed8eb09f640d))
  * add Client Credentials Grant `auth` support ([#799](https://github.com/box/box-windows-sdk-v2/issues/799)) ([`b8a64ca`](https://github.com/box/box-windows-sdk-v2/commit/b8a64ca3887298feccef5185f6bfec4c3771b5a9))
  * add `disposition_at` field to the File object ([#793](https://github.com/box/box-windows-sdk-v2/issues/793)) ([`2766a91`](https://github.com/box/box-windows-sdk-v2/commit/2766a914fad1eb40371cd4430b3450360088b331))
  * add possibility to set `auth` token `uri` in `BoxConfig` ([#794](https://github.com/box/box-windows-sdk-v2/issues/794)) ([`ae8cd8b`](https://github.com/box/box-windows-sdk-v2/commit/ae8cd8b91dd91b8a786e53ff5b3501d2700686a4))
  * deprecate `index_name` in `ExecuteMetadataQuery` ([#800](https://github.com/box/box-windows-sdk-v2/issues/800)) ([`6a6a0e4`](https://github.com/box/box-windows-sdk-v2/commit/6a6a0e4a0e41ec70ec33acacba00bee6c7ee881f))

  - [https://www.nuget.org/packages/Box.V2/4.2.0](https://www.nuget.org/packages/Box.V2/4.2.0)
  - [https://www.nuget.org/packages/Box.V2.Core/4.2.0](https://www.nuget.org/packages/Box.V2.Core/4.2.0)
</Update>

<Update label="2021-12-31">
  ## EOL Notification For DICOM

  Box has retired (End of Life/EOL) our DICOM Uploader and turned off native previewing of `boxdicom` studies as of December 31, 2021.

  The developer documentation for DICOM has now been removed. For more information, please see the [product announcement](https://support.box.com/hc/en-us/articles/1500005724681-Box-DICOM-EOL-on-December-31-2021) for alternatives.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2022-02-01">
  ## Box CLI v3.0.0 released

  Today, we released `v3.0.0` of the [Box CLI](https://github.com/box/boxcli/releases).  This release has several enhancements, most notably - addition of OAuth 2.0 support.

  In addition to CLI enhancements and documentation changes, we also released a brand new [YouTube video](https://www.youtube.com/watch?v=whxT3Bdx3E0\&list=PL0F3BD5B64D6A39F1) that shows using our Box CLI Quick Start to get started with the CLI in less than
  five minutes!

  ## Developer Documentation Changes

  * Updated the [Box CLI Quick Start Guide](/guides/cli) to use the OAuth 2.0 Authentication method
  * Moved the [JWT setup steps](/guides/cli/cli-with-jwt-authentication/jwt-cli) to an appendix

  ## New Features and Enhancements

  * Add support for login with OAuth ([#240](https://github.com/box/boxcli/pull/240))
  * feat: support as-user flag for bulk files and when token is present ([#270](https://github.com/box/boxcli/pull/270))
  * Add support for `copyInstanceOnItemCopy` field for metadata templates  ([#239](https://github.com/box/boxcli/pull/239))
  * Add support note to the `mdfilter` equality check in search ([#253](https://github.com/box/boxcli/pull/253))
  * Add support for Box Sign API ([#258](https://github.com/box/boxcli/pull/258))
  * Add support Metadata Query API ([#259](https://github.com/box/boxcli/pull/259))
  * fix: `folder:collaborations:add` make `role` a required flag (`SDK-1070`) ([#261](https://github.com/box/boxcli/pull/261))
  * Minor dependencies upgrade
  * Add new API for files and file versions under retention ([#250](https://github.com/box/boxcli/issues/250))
  * Adding support for sign request ([#258](https://github.com/box/boxcli/issues/258))
  * Support Metadata Query API ([#259](https://github.com/box/boxcli/issues/259))
  * chore: enforce conventional commits ([#268](https://github.com/box/boxcli/issues/268))
  * feat: support as-user flag for bulk files and when token is present ([#270](https://github.com/box/boxcli/issues/270))

  ## Breaking Changes

  * Drop support for Node 10
  * Insensitive language changes ([#247](https://github.com/box/boxcli/issues/247), [#252](https://github.com/box/boxcli/issues/252))

  ## Bug Fixes

  * fix: folder:collaborations:add make role a required flag ([#261](https://github.com/box/boxcli/issues/261))
  * fix: Fixed shared-links delete example. ([#262](https://github.com/box/boxcli/issues/262))

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed. You can also connect with the SDK
  team on the respective GitHub repository.
</Update>

<Update label="2022-01-26">
  ## Box Python SDK v3.0.1 released

  ### Bug Fixes

  * Move sphinx to test requirements ([#662](https://github.com/box/box-python-sdk/pull/662))
</Update>

<Update label="2022-01-17">
  ## Box Python SDK v3.0.0 released

  ### Breaking Changes

  * Drop support for python 2.7 ([#645](https://github.com/box/box-python-sdk/pull/645))
  * Add missing parameter `stream_position to get_admin_events` method ([#648](https://github.com/box/box-python-sdk/pull/648))
  * Drop support for python 3.5 ([#654](https://github.com/box/box-python-sdk/pull/654))
  * Remove deprecated code using insensitive language ([#651](https://github.com/box/box-python-sdk/pull/651))
  * Enforcing usage of keyword-only arguments in some functions ([#656](https://github.com/box/box-python-sdk/pull/656))

  ### New Features and Enhancements

  * Remove `six` library and `__future__` imports ([#646](https://github.com/box/box-python-sdk/pull/646))
  * Add type hints to method parameters ([#650](https://github.com/box/box-python-sdk/pull/650))

  ### Bug Fixes

  * Add missing `api_call` decorators on `multi-input` calls ([#653](https://github.com/box/box-python-sdk/pull/653))
  * Added `py.typed` file for `mypy` to recognize type hints ([#657](https://github.com/box/box-python-sdk/pull/657))
</Update>

<Update label="2022-01-17">
  ## Box Java SDK v3.0.0 released

  ### Breaking changes

  * Changed `BoxFileVersion` class and removed `fileVersion` field ([#978](https://github.com/box/box-java-sdk/issues/978))
  * Removed deprecated API `BoxCollaborationWhitelist` replaced with `BoxCollaborationAllowlist`, `BoxCollaborationWhitelistExemptTarget` replaced with `BoxCollaborationAllowlistExemptTarget` ([#969](https://github.com/box/box-java-sdk/issues/969))
  * Dropping Java 7 support ([#962](https://github.com/box/box-java-sdk/issues/962))
  * Downgrading `bouncycastle` libraries to 1.57 ([#942](https://github.com/box/box-java-sdk/issues/942))

  ### New Features and Enhancements

  * Add `typeName` to `BoxEvent` that contains name of the event, even if it is not mapped to `BoxEvent.EventType` ([#979](https://github.com/box/box-java-sdk/issues/979)) ([`b30f61f`](https://github.com/box/box-java-sdk/commit/b30f61f8cc9c02a1fc4cd5eb35469749e1a16558)), closes [#968](https://github.com/box/box-java-sdk/issues/968)
  * Add new optional `description` parameter to the `retention_policies` endpoint and `start_date_field` to the `retention_policy_assignments endpoint`. ([#967](https://github.com/box/box-java-sdk/issues/967)) ([`0aa4ff4`](https://github.com/box/box-java-sdk/commit/0aa4ff48a1e035efc9ac6aaa42f18f4c92955b7b))
  * Adding `BoxFile#getVersions(String... fields)` to allow users to specify what information they want to extract. Fixes [#946](https://github.com/box/box-java-sdk/issues/946). ([#947](https://github.com/box/box-java-sdk/issues/947)) ([`a2eb638`](https://github.com/box/box-java-sdk/commit/a2eb63896606a6c00ccee6bd9745f4c51f8d89a2))
  * Missing `eventTypes` from `BoxAPI` Documents. Fixes [#974](https://github.com/box/box-java-sdk/issues/974) ([#975](https://github.com/box/box-java-sdk/issues/975)) ([`2c69360`](https://github.com/box/box-java-sdk/commit/2c69360e80b1bdd6213933cf2f4da195d52c92d4))
  * Removed deprecated API `BoxCollaborationWhitelist` replaced with `BoxCollaborationAllowlist`, `BoxCollaborationWhitelistExemptTarget` replaced with `BoxCollaborationAllowlistExemptTarget` ([#969](https://github.com/box/box-java-sdk/issues/969)) ([`2fd4d6f`](https://github.com/box/box-java-sdk/commit/2fd4d6f884410c8884c4c038687bfc8f32837b55))

  ### Bug Fixes

  * Changed `BoxFileVersion` class and removed `fileVersion` field ([#978](https://github.com/box/box-java-sdk/issues/978)) ([`8c39451`](https://github.com/box/box-java-sdk/commit/8c3945167581400043a070c2f6906ef05d3d7b85))
  * Changed SDK loggers name to `"com.box.sdk"`, fixes [#638](https://github.com/box/box-java-sdk/issues/638) ([#950](https://github.com/box/box-java-sdk/issues/950)) ([`443c230`](https://github.com/box/box-java-sdk/commit/443c23085e55bbcaa1524c5b9e1bf852a1e2a1ce))
  * Date parsing error when `BoxSignRequestPrefillTag` created with date value. ([#970](https://github.com/box/box-java-sdk/issues/970)) ([`cc2c8da`](https://github.com/box/box-java-sdk/commit/cc2c8da9ea7d066ae2c247c2de5ac8b8bbba9b99))
  * Fix sending limit parameter in `EventLog` ([#977](https://github.com/box/box-java-sdk/issues/977)) ([`96bdccc`](https://github.com/box/box-java-sdk/commit/96bdccc9ca40ed43a6028a2b0d055d9d9a8de525))
  * Fixed `NullPointerException` when empty metadata used on `BoxFile` or `BoxFolder` ([#918](https://github.com/box/box-java-sdk/issues/918)) ([#945](https://github.com/box/box-java-sdk/issues/945)) ([`68bc3c5`](https://github.com/box/box-java-sdk/commit/68bc3c578d760b7239f6d704fed9bb5a834bf52a))
  * Cannot deserialize sign request, fixes issue ([#951](https://github.com/box/box-java-sdk/issues/951)). ([#952](https://github.com/box/box-java-sdk/issues/952)) ([`070bdc5`](https://github.com/box/box-java-sdk/commit/070bdc56074a1533c41f9085943d09502c79a7f4))

  ### Dependency Upgrades

  * Dropping Java 7 support ([#962](https://github.com/box/box-java-sdk/issues/962)) ([`953ad78`](https://github.com/box/box-java-sdk/commit/953ad78ac84833082439d0def1dcc63dc11ac04a))
  * Downgrading `bouncycastle` libraries to 1.57 ([#942](https://github.com/box/box-java-sdk/issues/942)) ([`26aaed5`](https://github.com/box/box-java-sdk/commit/26aaed51fd914eaf2061da735f11830524e4cfe4))
</Update>

<Update label="2022-01-17">
  ## Box iOS SDK v5.1.0 Released

  ### New Features and Enhancements

  * Allow to customize URL for the `OAuth2` authorization page ([#811](https://github.com/box/box-ios-sdk/issues/811)) ([`1901d29`](https://github.com/box/box-ios-sdk/commit/1901d296a2be4b0f2eef25eda06928aebc81de9a))
  * **`Events`:** Add support for `admin_logs_streaming stream` type ([#800](https://github.com/box/box-ios-sdk/issues/800)) ([`0a3118e`](https://github.com/box/box-ios-sdk/commit/0a3118ef95c2eb42b0080d0352784849e85eb422))
  * **`RetentionPolicy`:** New API for get files and file versions under retention ([#807](https://github.com/box/box-ios-sdk/issues/807)) ([`38327f0`](https://github.com/box/box-ios-sdk/commit/38327f09a92dba7827e1866940a643d624757762))
  * **`SharedLink`:** add support for `vanity_name` ([#799](https://github.com/box/box-ios-sdk/issues/799)) ([`3ea6eb2`](https://github.com/box/box-ios-sdk/commit/3ea6eb2a1c2b713fd0769e93a2dc4ee51da695fd))

  ### Bug Fixes

  * **`SignRequest`:** Fix encoding `date_value` to `yyyy-mm-dd` format in `prefillTag` ([#806](https://github.com/box/box-ios-sdk/issues/806)) ([`4f902a4`](https://github.com/box/box-ios-sdk/commit/4f902a47482de55ec69b5522e6cf5affd653b4c8))
</Update>

<Update label="2022-01-06">
  ## New Features For Platform App Management

  Today, we released changes to the Platform Apps Manager section of the Box Admin Console. Now, you can more easily view and manage enablement of platform OAuth 2.0
  Applications.

  In addition to adding new functionality, we also made updates to the UI of the Platform Apps Manager. For more information on the changes and authorizing apps that
  use the Box API, check out the [blog post](https://medium.com/box-developer-blog/platform-apps-manager-updates-c79ccf8ebe97).

  ## Updates

  * Screenshots have been updated on the [authorization](/guides/authorization), [platform app approval](/guides/authorization/platform-app-approval), [limited access approval](/guides/authorization/limited-access-approval), and [security](/guides/security) guide pages
  * Information on the OAuth 2.0 platform application approval process has been added to the [platform app approval](/guides/authorization/platform-app-approval) guide page

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>


# 2023
Source: https://developer.box.com/changelog/2023

Box Platform changelog: API, SDK, and product updates from 2023.

<Update label="2023-12-11">
  ## Introducing enhanced My Apps view in Developer Console

  To improve application management experience even further, we introduce
  the [My Apps](/guides/applications) list view in the Developer Console.
  This view includes key information about your applications, giving you the possibility to:

  * view and copy the application client ID,
  * view the application description,
  * sort custom applications,
  * check the authorization and enablement status of the application,
  * access the configuration and generate developer tokens.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-11-30">
  ## Introducing the NEW Learn Box Platform section

  To improve the getting started experience, we have reorganized and added resource materials
  for you to use when coming on to the platform. Checkout the learn section [here](https://developer.box.com/platform/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-11-29">
  ## Box Windows SDK v5.6.1 released

  ### Bug Fixes

  * support object value in `BoxConflictErrorContextInfo` ([#930](https://github.com/box/box-windows-sdk-v2/issues/930)) ([`496f758`](https://github.com/box/box-windows-sdk-v2/commit/496f758c3436b1834188078027b7305ca6a98fce))

  - [https://www.nuget.org/packages/Box.V2/5.6.1>](https://www.nuget.org/packages/Box.V2/5.6.1>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.6.1>](https://www.nuget.org/packages/Box.V2.Core/5.6.1>)
</Update>

<Update label="2023-11-08">
  ## Box Node SDK v3.4.2 released

  ### Bug Fixes

  * Fix `proxy-agent` ([#867](https://github.com/box/box-node-sdk/issues/867)) ([`3de7586`](https://github.com/box/box-node-sdk/commit/3de7586e44dbb7c8e1bff8f34471964805c810f5))
</Update>

<Update label="2023-11-08">
  ## Box CLI v3.12.2 released

  ### Bug Fixes

  * Bump `box-node-sdk` ([#510](https://github.com/box/boxcli/issues/510)) ([`2621f41`](https://github.com/box/boxcli/commit/2621f4121999ff6e9d0cc0c391dfd3aa93aefe49))
</Update>

<Update label="2023-11-06">
  ## Box CLI v3.12.1 released

  ### Bug Fixes

  * force offset based pagination in get users ([#504](https://github.com/box/boxcli/issues/504)) ([`9bed083`](https://github.com/box/boxcli/commit/9bed083d59b2386d045619fdf2f3ea915e44d231))
</Update>

<Update label="2023-11-03">
  ## Box Node SDK v3.4.1 released

  ### Bug Fixes

  * Update `proxy-agent` usage, drop support Node 12 ([#865](https://github.com/box/box-node-sdk/issues/865)) ([`e229d3f`](https://github.com/box/box-node-sdk/commit/e229d3f93de350c00768528a1c0d3a6ecfc697a9))
</Update>

<Update label="2023-11-03">
  ## Box Node SDK v3.4.0 released

  ### New Features and Enhancements

  * Add request option to skip `PassThrough` ([#863](https://github.com/box/box-node-sdk/issues/863)) ([`726db45`](https://github.com/box/box-node-sdk/commit/726db45cfbb992e545fe2865283df63c898656ac))
</Update>

<Update label="2023-11-02">
  ## Box Java SDK v4.6.1 released

  ### Dependency Upgrades

  * Bumped `org.bitbucket.b_c:jose4j:0.9.3` ([#1212](https://github.com/box/box-java-sdk/issues/1212)) ([`f522a56`](https://github.com/box/box-java-sdk/commit/f522a5660f3522b11a0516774ba0cca69db3ec31))
</Update>

<Update label="2023-10-26">
  ## Box Node SDK v3.3.0 released

  ### New Features and Enhancements

  * Replace `request` library with `@cypress/request` ([#860](https://github.com/box/box-node-sdk/issues/860)) ([`d365ae8`](https://github.com/box/box-node-sdk/commit/d365ae8368c549ecdceb7dd5b928904fd3c58978))

  ### Bug Fixes

  * mark auth functions callbacks as optional ([#858](https://github.com/box/box-node-sdk/issues/858)) ([`55f22fe`](https://github.com/box/box-node-sdk/commit/55f22fec7d7d35e487f3fb51bc9bbd3e848842ab))
</Update>

<Update label="2023-10-18">
  ## Box Python SDK v3.9.2 released

  ### Bug Fixes

  * Remove restriction to version \<2 of `urllib3` library ([#851](https://github.com/box/box-python-sdk/issues/851)) ([`1dcd82e`](https://github.com/box/box-python-sdk/commit/1dcd82e93267bfc68e3a7f8068b3c45ab7e86daf))
</Update>

<Update label="2023-10-06">
  ## Introducing Box Platform Glossary

  To improve your experience with Box Platform and Box documentation, we created the [Box Platform Glossary](page/platform/box-glossary/).
  You can find there terms and concepts that are most important to start working with Box content- and cloud-based solutions.

  As we want this list of terms to be comprehensive and detailed, it will be regularly updated. Let us know if you have any suggestions!

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-10-06">
  ## Box Node SDK v3.2.1 released

  ### Bug Fixes

  * Overrides tough-cookie dependency ([#852](https://github.com/box/box-node-sdk/issues/852)) ([`99df873`](https://github.com/box/box-node-sdk/commit/99df873e1a1dad4a0073d53b4ed57c0eeb859401))
</Update>

<Update label="2023-10-03">
  ## Platform Insights for applications

  Admins and co-admins can now use the Platform Insights dashboard to get comprehensive view of the organization’s platform usage,
  including application-related information.
  With Platform Insights you can check the API call volume or the number of applications that are not enabled or approved yet.
  Additionally, you can see which apps are the most popular ones in you enterprise.

  For details, see [applications](/guides/applications) and [Platform Insights](https://support.box.com/hc/en-us/articles/20738406915219-Platform-Insights) documentation.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-10-02">
  ## Salesforce Toolkit - Integration Mappings

  You can now use [integration mappings](/guides/integration-mappings/slack-mappings) in Salesforce Toolkit with new [methods](/guides/tooling/salesforce-toolkit/methods/#salesforce_and_slack) and [flow actions](/guides/tooling/salesforce-toolkit/flow-actions).
  With [integration mappings](/reference/resources/integration-mapping-slack) you can map a Slack channel to any folder within your enterprise instead of the default one.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-09-29">
  ## Introducing Beta Release: New Generation Python SDc

  We are excited to introduce [the latest generation (currently in Beta) of Box Python SDK](https://github.com/box/box-python-sdk-gen), designed to elevate the developer experience and streamline your integration with the Box Content Cloud.

  With the [new generation of Python SDK](https://github.com/box/box-python-sdk-gen), you'll have access to:

  * **Full API Support**: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications.
  * **Rapid API Updates** Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
  * **Embedded Documentation**: We understand that access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process.
  * **Enhanced Convenience Methods**: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers which help to ensure that you’re using variables correctly, and much more.

  Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. Start building innovative solutions faster and more efficiently. Happy coding!
</Update>

<Update label="2023-09-29" description="">
  ## Box TypeScript SDK v10 released

  We are excited to introduce [the latest generation (currently in Beta) of Box TypeScript SDK](https://github.com/box/box-typescript-sdk-gen), designed to elevate the developer experience and streamline your integration with the Box Content Cloud.

  With the [new generation of Typescript SDK](https://github.com/box/box-typescript-sdk-gen), you’ll have access to:

  * **Full API Support**: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications.
  * **Rapid API Updates**: Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
  * **Embedded Documentation**: We understand that access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process.
  * **Enhanced Convenience Methods**: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers which help to ensure that you’re using variables correctly, and much more.

  Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. Start building innovative solutions faster and more efficiently. Happy coding!
</Update>

<Update label="2023-09-29">
  ## Box Java SDK v4.6.0 released

  ### New Features and Enhancements

  * Support search deleted filters ([#1207](https://github.com/box/box-java-sdk/issues/1207)) ([`5e0e9ed`](https://github.com/box/box-java-sdk/commit/5e0e9ed9aea2818da6fba0d562b56987c4948aaa))

  ### Bug Fixes

  * Added protected accessors for trust manager and hostname verifier. ([#1206](https://github.com/box/box-java-sdk/issues/1206)) ([`0c79d17`](https://github.com/box/box-java-sdk/commit/0c79d1754bffeb3f0487e10d55d716ba1cbed1aa))
  * fix not closing response body ([#1208](https://github.com/box/box-java-sdk/issues/1208)) ([`ab5e170`](https://github.com/box/box-java-sdk/commit/ab5e1702934607b258802b33f3663af3e9c56027))
</Update>

<Update label="2023-09-25" description="Box Windows SDK v5.6.0 released">
  ## Box Windows SDK v5.6.0 released

  ### New Features and Enhancements

  * Support `iframeable_embed_url` for sign request ([#925](https://github.com/box/box-windows-sdk-v2/issues/925)) ([`e9de994`](https://github.com/box/box-windows-sdk-v2/commit/e9de994cea97afcc1c3bc52ddf1cc023b9ee731c))

  - [https://www.nuget.org/packages/Box.V2/5.6.0>](https://www.nuget.org/packages/Box.V2/5.6.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.6.0>](https://www.nuget.org/packages/Box.V2.Core/5.6.0>)
</Update>

<Update label="2023-09-18">
  ## Box CLI v3.12.0 released

  ### New Features and Enhancements

  * Support sign templates ([#496](https://github.com/box/boxcli/issues/496)) ([`955106f`](https://github.com/box/boxcli/commit/955106ffa5d7938c567e5440868f2ec3c87045ce))
</Update>

<Update label="2023-09-14">
  ## Box Python SDK v3.9.1 released

  ### Bug Fixes

  * do not retry creating a ZIP when response code is 202 ([#845](https://github.com/box/box-python-sdk/issues/845)) ([`3f6ed4e`](https://github.com/box/box-python-sdk/commit/3f6ed4e1053a494ed9f2b79828850e059d0a1617)), closes [#844](https://github.com/box/box-python-sdk/issues/844)
</Update>

<Update label="2023-09-14">
  ## Box Java SDK v4.5.0 released

  ### New Features and Enhancements

  * Add `iframeable_embed_url` field to `BoxSignRequestSigner` class ([#1202](https://github.com/box/box-java-sdk/issues/1202)) ([`2e931d8`](https://github.com/box/box-java-sdk/commit/2e931d8c36694a665d1c6315d3bf2d226929b713))

  ### Bug Fixes

  * `SharedLinkAPIConnection` uses request interceptor ([#1203](https://github.com/box/box-java-sdk/issues/1203)) ([`b2b6a1d`](https://github.com/box/box-java-sdk/commit/b2b6a1dba316ba50a1e011250c320fca156c6708)), closes [#1200](https://github.com/box/box-java-sdk/issues/1200)
  * Update sign template missing enum ([#1201](https://github.com/box/box-java-sdk/issues/1201)) ([`fcb6657`](https://github.com/box/box-java-sdk/commit/fcb6657bb2375e32c3fb0f861e7ecaeb84503f2c))
</Update>

<Update label="2023-09-07">
  ## Box Windows SDK v5.4.0 released

  ### New Features and Enhancements

  * Support Sign Templates and new Sign Request statuses ([#920](https://github.com/box/box-windows-sdk-v2/issues/920)) ([`78580fb`](https://github.com/box/box-windows-sdk-v2/commit/78580fbd3de553273970376b96bc28c7c5614a97))

  - [https://www.nuget.org/packages/Box.V2/5.4.0>](https://www.nuget.org/packages/Box.V2/5.4.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.4.0>](https://www.nuget.org/packages/Box.V2.Core/5.4.0>)
</Update>

<Update label="2023-09-07">
  ## Box Node SDK v3.2.0 released

  ### New Features and Enhancements

  * Support sign template ([#848](https://github.com/box/box-node-sdk/issues/848)) ([`18d3413`](https://github.com/box/box-node-sdk/commit/18d3413afeddf43c62dfd0caf1279e61c99b6b83))
</Update>

<Update label="2023-09-06">
  ## Box Python SDK v3.9.0 released

  ### New Features and Enhancements

  * Support Sign Templates APIs ([#835](https://github.com/box/box-python-sdk/issues/835)) ([`fbc783d`](https://github.com/box/box-python-sdk/commit/fbc783d5af2e75f883f1a0051613c513139f68fb))
  * Support create sign request with template ID ([#834](https://github.com/box/box-python-sdk/issues/834)) ([`4f11d75`](https://github.com/box/box-python-sdk/commit/4f11d7596488194fc740936fe987f42864003d41))

  ### Bug Fixes

  * `ChunkedUploader` Resume Not Closing `ThreadPoolExecutor` Instances ([#840](https://github.com/box/box-python-sdk/issues/840)) ([`f210f00`](https://github.com/box/box-python-sdk/commit/f210f00ad823d7755309f2e8804641e0debf8197))
</Update>

<Update label="2023-09-04" description="Box Windows SDK v5.3.0 released">
  ## Box Windows SDK v5.3.0 released

  ### New Features and Enhancements

  * add `attachment` content type to `SignRequestSigner` ([#913](https://github.com/box/box-windows-sdk-v2/issues/913)) ([`ad612ff`](https://github.com/box/box-windows-sdk-v2/commit/ad612ffc7821a9ecbc180e3dbeefe16d3e397820))

  ### Bug Fixes

  * replace deprecated `BouncyCastle` library ([#909](https://github.com/box/box-windows-sdk-v2/issues/909)) ([`f00f2af`](https://github.com/box/box-windows-sdk-v2/commit/f00f2af9c5277b42e6a62060c1b0229ecff0203e))

  - [https://www.nuget.org/packages/Box.V2/5.3.0>](https://www.nuget.org/packages/Box.V2/5.3.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.3.0>](https://www.nuget.org/packages/Box.V2.Core/5.3.0>)
</Update>

<Update label="2023-08-29">
  ## Box Java SDK v4.4.0 released

  ### New Features and Enhancements

  * Support sign template and new sign status ([#1197](https://github.com/box/box-java-sdk/issues/1197)) ([`e37c0dc`](https://github.com/box/box-java-sdk/commit/e37c0dce86a422de5e8e6ed26fd93f1324f4b3e3))
</Update>

<Update label="2023-08-16">
  ## Introducing Embedded Box Sign Client

  You can now use [Box Embed](/guides/embed/box-embed) to [embed Box Sign
  features](/guides/box-sign/create-sign-request#embedded-sign-client) in your own website. This way, users
  don't have to leave the website, go to Box Sign
  to sign the document, and then come back to finish
  the process. Instead, Box Embed allows them
  to complete the signing process
  within the external website.

  To integrate Box Sign experience within your
  own website, you need the [`iframeable_embed_url`](/reference/resources/sign-request#param-signers-iframeable_embed_url)
  parameter that is specifically designed to allow
  signing documents within the HTML `iframe` tag.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-08-16">
  ## Box CLI v3.10.0 released

  ### New Features and Enhancements

  * Support update user tracking codes ([#489](https://github.com/box/boxcli/issues/489)) ([`159e6d0`](https://github.com/box/boxcli/commit/159e6d07fa91f2b199ca85207a4cad5cf4274f0e))
</Update>

<Update label="2023-08-11">
  ## Box Java SDK v4.3.0 released

  ### New Features and Enhancements

  * Support access only collaboration ([#1193](https://github.com/box/box-java-sdk/issues/1193)) ([`664c01f`](https://github.com/box/box-java-sdk/commit/664c01f80ca0647645c60920eb0ef1f9353a619f))
</Update>

<Update label="2023-08-08">
  ## Box iOS SDK v5.5.0 released

  ### New Features and Enhancements

  * Add missing values in `SignRequestSignerInputContentType` and `SignRequestStatus` along with the tests ([#907](https://github.com/box/box-ios-sdk/issues/907)) ([`56a8250`](https://github.com/box/box-ios-sdk/commit/56a82500c0abe648825d8300979601a25f792c84))

  ### Bug Fixes

  * Identify iPhone Simulator on Apple Silicon ([#902](https://github.com/box/box-ios-sdk/issues/902)) ([`7731a7f`](https://github.com/box/box-ios-sdk/commit/7731a7f434add74e163a76511fe1e2a3f26517f7))
  * Make code compatible with macOS. ([#900](https://github.com/box/box-ios-sdk/issues/900)) ([`3b0016e`](https://github.com/box/box-ios-sdk/commit/3b0016e44e674db0ea429273c03e5a29177372bf))
  * Remove use of deprecated string scanner API. ([#901](https://github.com/box/box-ios-sdk/issues/901)) ([`af5f0e5`](https://github.com/box/box-ios-sdk/commit/af5f0e52d184fbd27f56d972fb93b3e543547773))
</Update>

<Update label="2023-08-08">
  ## Box CLI v3.9.2 released

  ### Bug Fixes

  * Fix escaped slashes when passing an input to command ([#486](https://github.com/box/boxcli/issues/486)) ([`7670210`](https://github.com/box/boxcli/commit/7670210ffb5c38cef8dd153e823029d5237080b6))
</Update>

<Update label="2023-08-03">
  ## Box Java SDK v4.2.1 released

  ### Bug Fixes

  * Fixed upload when data are coming from a dynamic source ([#1189](https://github.com/box/box-java-sdk/issues/1189)) ([`77b39f2`](https://github.com/box/box-java-sdk/commit/77b39f2645d53bdab0ade23b637c211ea070fcf5)), closes [#1183](https://github.com/box/box-java-sdk/issues/1183) [#1190](https://github.com/box/box-java-sdk/issues/1190)
</Update>

<Update label="2023-08-01">
  ## Box Python SDK v3.8.1 released

  ### Bug Fixes

  * Fix JSON response validation retry strategy ([#831](https://github.com/box/box-python-sdk/issues/831)) ([`69834eb`](https://github.com/box/box-python-sdk/commit/69834eb4c91a5aa4bc294a9fa49ecf753979d029))
</Update>

<Update label="2023-07-25">
  ## Box Python SDK v3.8.0 released

  ### New Features and Enhancements

  * Support updating all fields of `collaboration` ([#829](https://github.com/box/box-python-sdk/issues/829)) ([`6dc7ecc`](https://github.com/box/box-python-sdk/commit/6dc7ecc6f9c94e7531c4147a3645927b85928b2c))
</Update>

<Update label="2023-07-26">
  ## Improvements in App Access Level for JWT authentication

  You can now ensure access to enterprise Managed Users **and groups** that were not created by [apps authenticated with JWT](/guides/authentication/jwt/jwt-setup). To do so, set **App Access Level** to **App + Enterprise Access** in the **Configuration** tab of the Developer console.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-07-19">
  ## Box Node SDK v3.1.1 released

  ### New Features and Enhancements

  * Bump proxy-agent to version 6.3.0 ([845](\(https://github.com/box/box-node-sdk/pull/845\))) ([`3f89f83`](\(https://github.com/box/box-node-sdk/commit/3f89f83e939de5c1e6e48abbfb56212b56e70526\)))
</Update>

<Update label="2023-07-19">
  ## Box CLI v3.9.1 released

  ### New Features and Enhancements

  * Bump version of `box-node-sdk` and `csv` libraries ([483](\(https://github.com/box/boxcli/pull/483\))) ([`fecb04b`](\(https://github.com/box/boxcli/pull/483/commits/fecb04b635980baf37a7fefc8860b5e07b0bc4e6\)))
</Update>

<Update label="2023-07-12">
  ## Sign Request API improvements

  [Sign Request status](/reference/resources/sign-request#param-status) parameter now has two additional values:

  * `finalizing` to reflect the state when all signers have signed the request, but the final document with signatures and the signing log has not been generated yet.
  * `error_finalizing` to reflect the state when the `finalizing` phase did not complete successfully.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2023-07-12">
  ## Box UI Elements v18.1.0 released

  ### [18.1.0](https://github.com/box/box-ui-elements/compare/v18.0.0...v18.1.0) (2023-07-12)

  ### Bug Fixes

  * **content-picker:** check share permission for default shared links ([#3371](https://github.com/box/box-ui-elements/issues/3371)) ([`2bb1ddb`](https://github.com/box/box-ui-elements/commit/2bb1ddb))
  * **i18n:** update translations ([#3372](https://github.com/box/box-ui-elements/issues/3372)) ([`f01fd6d`](https://github.com/box/box-ui-elements/commit/f01fd6d))
  * **readme:** fix `langauge` typo ([#3373](https://github.com/box/box-ui-elements/issues/3373)) ([`50e7fe0`](https://github.com/box/box-ui-elements/commit/50e7fe0))

  ### Features

  * **uaa-integration:** Filter activity types for UAA ([#3369](https://github.com/box/box-ui-elements/issues/3369)) ([`b9d196f`](https://github.com/box/box-ui-elements/commit/b9d196f))
</Update>

<Update label="2023-07-07">
  ## Box Python SDK v3.7.3 released

  ### Bug Fixes

  * Stop processing data for logging when logging is deactivated and cache response `json` ([#824](https://github.com/box/box-python-sdk/issues/824)) ([`3079171`](https://github.com/box/box-python-sdk/commit/3079171f8dfc1a4c85f8587e8ce90e8fbd826ee4))
</Update>

<Update label="2023-06-30">
  ## Updated sorting of folder items for shared folders

  Box Folder API allows you to [retrieve the items in the folder](/reference/get-folders-id-items) and [sort](/reference/get-folders-id-items#param-sort) this list based on the sort parameter.
  We have improved the way items are sorted for shared folders that have the path to the associated folder visible to the collaborators.

  Earlier, the items for such folders were sorted by `id` regardless of the sort parameter value.
  Currently, they are sorted based on the `sort` parameter.

  ## New place to get support

  From now on you can ask questions and seek for guidance in our new [Box Developer Community forum](https://forum.box.com/). Use this new space to directly speak to the Box Developer Relations team, as well as your peers and other subject matter experts from Box.
</Update>

<Update label="2023-06-27">
  ## Box UI Elements v18.0.0 released

  ### [18.0.0](https://github.com/box/box-ui-elements/compare/v17.1.0...v18.0.0) (2023-06-27)

  ### Bug Fixes

  * **ci:** remove blank space from release script var  ([#3355](https://github.com/box/box-ui-elements/issues/3355)) ([`2553ec1`](https://github.com/box/box-ui-elements/commit/2553ec1))
  * **content-explorer:** increase grid button style specificity ([#3328](https://github.com/box/box-ui-elements/issues/3328)) ([`b2c878a`](https://github.com/box/box-ui-elements/commit/b2c878a))
  * **content-explorer:** map called on undefined object ([#3341](https://github.com/box/box-ui-elements/issues/3341)) ([`da6ada0`](https://github.com/box/box-ui-elements/commit/da6ada0))
  * **content-picker:** trim name input when creating folder ([#3364](https://github.com/box/box-ui-elements/issues/3364)) ([`4629726`](https://github.com/box/box-ui-elements/commit/4629726))
  * **css:** remove IE7 CSS hack to fix Parcel support ([#3368](https://github.com/box/box-ui-elements/issues/3368)) ([`cbff7f1`](https://github.com/box/box-ui-elements/commit/cbff7f1))
  * **i18n:** update translations ([#3323](https://github.com/box/box-ui-elements/issues/3323)) ([`c810383`](https://github.com/box/box-ui-elements/commit/c810383))
  * **i18n:** update translations ([#3344](https://github.com/box/box-ui-elements/issues/3344)) ([`755d64b`](https://github.com/box/box-ui-elements/commit/755d64b))
  * **i18n:** update translations ([#3349](https://github.com/box/box-ui-elements/issues/3349)) ([`6ba9f27`](https://github.com/box/box-ui-elements/commit/6ba9f27))
  * **i18n:** update translations ([#3351](https://github.com/box/box-ui-elements/issues/3351)) ([`4ff75e8`](https://github.com/box/box-ui-elements/commit/4ff75e8))
  * **i18n:** update translations ([#3352](https://github.com/box/box-ui-elements/issues/3352)) ([`80c795a`](https://github.com/box/box-ui-elements/commit/80c795a))
  * **i18n:** update translations ([#3359](https://github.com/box/box-ui-elements/issues/3359)) ([`c94305c`](https://github.com/box/box-ui-elements/commit/c94305c))
  * **preview:** update thumbnail sidebar width ([#3363](https://github.com/box/box-ui-elements/issues/3363)) ([`33c8236`](https://github.com/box/box-ui-elements/commit/33c8236))
  * **sharing:** remove message for shared links for Canvas files ([#3337](https://github.com/box/box-ui-elements/issues/3337)) ([`9558474`](https://github.com/box/box-ui-elements/commit/9558474))
  * align viewer permissions for shared links ([#3335](https://github.com/box/box-ui-elements/issues/3335)) ([`5d78c11`](https://github.com/box/box-ui-elements/commit/5d78c11))
  * update dist path and react version for elements test pages ([#3350](https://github.com/box/box-ui-elements/issues/3350)) ([`38ff124`](https://github.com/box/box-ui-elements/commit/38ff124))
  * **pill-selector-dropdown:** pass `showAvatars` prop to `RoundPill` ([#3329](https://github.com/box/box-ui-elements/issues/3329)) ([`5632743`](https://github.com/box/box-ui-elements/commit/5632743))
  * **share-form:** map called on undefined object ([#3340](https://github.com/box/box-ui-elements/issues/3340)) ([`a24abb2`](https://github.com/box/box-ui-elements/commit/a24abb2))
  * **usm:** fix message for upgrade notice in share modal ([#3334](https://github.com/box/box-ui-elements/issues/3334)) ([`4a945ce`](https://github.com/box/box-ui-elements/commit/4a945ce))

  ### chore

  * **deps:** Bump `react-beautiful-dnd` to version 11.0.5 ([#3345](https://github.com/box/box-ui-elements/issues/3345)) ([`610c9d2`](https://github.com/box/box-ui-elements/commit/610c9d2))
  * **node:** Upgrade to node 18 ([#3347](https://github.com/box/box-ui-elements/issues/3347)) ([`cbb3840`](https://github.com/box/box-ui-elements/commit/cbb3840))

  ### Features

  * **cloud-game:** Adjust cloud game visual ([#3361](https://github.com/box/box-ui-elements/issues/3361)) ([`fe7fb51`](https://github.com/box/box-ui-elements/commit/fe7fb51))
  * **pill-selector-dropdown:** allow setting error tooltip position ([#3330](https://github.com/box/box-ui-elements/issues/3330)) ([`8df1551`](https://github.com/box/box-ui-elements/commit/8df1551))
  * **preview:** update default Preview SDK version ([#3366](https://github.com/box/box-ui-elements/issues/3366)) ([`aa7a875`](https://github.com/box/box-ui-elements/commit/aa7a875))
  * **security-controls:** Remove watermark learn more link ([#3353](https://github.com/box/box-ui-elements/issues/3353)) ([`379d055`](https://github.com/box/box-ui-elements/commit/379d055))
  * **threaded-replies:** reply to annotations ([#3331](https://github.com/box/box-ui-elements/issues/3331)) ([`4f65525`](https://github.com/box/box-ui-elements/commit/4f65525))
  * **uaa-integration:** Integrate UAA into `ActivitySidebar` ([#3316](https://github.com/box/box-ui-elements/issues/3316)) ([`b81e976`](https://github.com/box/box-ui-elements/commit/b81e976))

  ### BREAKING CHANGES

  * **deps:** You need to upgrade `react-beautiful-dnd` in the consuming project to version 11.0.5

  * **node:** Upgrade to node 18
</Update>

<Update label="2023-06-26">
  ## Integration mappings for Slack

  Learn how the Box Enterprise Admin (EA) can customize the upload folder of the Slack channel to any folder
  within the enterprise instead of relying on the default one with the [Integration Mappings for Slack](/guides/integration-mappings/slack-mappings) guide.

  Use Box API to [create](/reference/post-integration-mappings-slack), [list](/reference/get-integration-mappings-slack), [update](/reference/put-integration-mappings-slack-id), and [delete](/reference/delete-integration-mappings-slack-id) the Slack Integration Mappings.

  Using the [automation script](https://github.com/box/boxcli/tree/main/examples/Integration%20Mappings), an admin can create or update multiple mappings at once!

  Check the [Troubleshooting](/guides/integration-mappings/slack-mappings/troubleshooting) section to find out solutions to most common issues you can encounter.

  ## New place to get support

  From now on you can ask questions and seek for guidance in our new [Box Developer Community forum](https://forum.box.com/). Use this new space to directly speak to the Box Developer Relations team, as well as your peers and other subject matter experts from Box.
</Update>

<Update label="2023-06-21">
  ## Box Java SDK v4.2.0 released

  ### New Features and Enhancements

  * Getting collaborators allows to specify fields ([#1178](https://github.com/box/box-java-sdk/issues/1178)) ([`1694d75`](https://github.com/box/box-java-sdk/commit/1694d75fff0fbddb938426ef03ba24f360a344aa))
</Update>

<Update label="2023-06-15">
  ## Enhanced passwords for Shared Links

  We have enhanced our password policy for creating shared links with Box API, for example when [adding a shared link to a file](/reference/put-files-id--add-shared-link#param-shared_link-password).
  Passwords must now be at least eight characters long and include:

  * a number,
  * upper case letter, or
  * non-alphabetic or non-numeric character

  ## New place to get support

  From now on you can ask questions and seek guidance in our new [Box Developer Community forum](https://forum.box.com/). Use this new space to directly speak to the Box Developer Relations team, as well as your peers and other subject matter experts from Box.
</Update>

<Update label="2023-06-14">
  ## Box Java SDK v4.1.2 released

  ### Bug Fixes

  * Class cast exception when uploading large file ([#1174](https://github.com/box/box-java-sdk/issues/1174)) ([`e7d28bd`](https://github.com/box/box-java-sdk/commit/e7d28bddb706c8b4fd1328f0eebc50db19a8c656)), closes [#1173](https://github.com/box/box-java-sdk/issues/1173)
  * Make `SharedLinkAPIConnection` constructors public ([#1172](https://github.com/box/box-java-sdk/issues/1172)) ([`4d1616d`](https://github.com/box/box-java-sdk/commit/4d1616ddd2c39d1cb0d03af998d2c47efe607853))
  * Remove not valid Group membership role ([#1171](https://github.com/box/box-java-sdk/issues/1171)) ([`a5915f9`](https://github.com/box/box-java-sdk/commit/a5915f94114a8269287831280a57949ed203e4e8))
</Update>

<Update label="2023-06-13">
  ## Join Box Developer Community

  Exciting news for developers and admins! Box has launched the Box Developer Community site, where you can connect with peers and experts to build innovative applications on top of the Box cloud content management and collaboration platform. Join us today at [https://forum.box.com](https://forum.box.com)!

  # Join, connect and learn

  * Get support and provide feedback
  * Share knowledge and become a community leader
  * Connect and chat with other Box developers and admins
  * Learn from other community members and Box subject matter experts
  * Stay up to date with the newest features, updates, developer-focused events, blog posts, and more!

  ## New place to get support

  From now on you can ask questions and seek guidance in our new [Box Developer Community forum](https://forum.box.com/). Use this new space to directly speak to the Box Developer Relations team, as well as your peers and other subject matter experts from Box.
</Update>

<Update label="2023-06-02">
  ## Box CLI v3.9.0 released

  ### New Features and Enhancements

  * add `max-items`, improve list endpoints performance ([#470](https://github.com/box/boxcli/issues/470)) ([`8f386f3`](https://github.com/box/boxcli/commit/8f386f3b7c4ff4efbaa941321fd672694ce3c7a1))
  * Add support for Integration Mappings API ([#472](https://github.com/box/boxcli/issues/472)) ([`bbf2548`](https://github.com/box/boxcli/commit/bbf2548223e0d07ce2412c04991e7d8f00022fa7))
  * New fields in `retention-policy` and `retention-policy-assignment` ([#466](https://github.com/box/boxcli/issues/466)) ([`f960e59`](https://github.com/box/boxcli/commit/f960e59aaf55fe0a0507e9f4c9d867e7c3dd039a))
</Update>

<Update label="2023-06-01">
  ## Box Node SDK v3.1.0 released

  ### New Features and Enhancements

  * Added support for integration mappings API ([#831](https://github.com/box/box-node-sdk/issues/831)) ([`a525327`](https://github.com/box/box-node-sdk/commit/a525327c1362628a0ffdb36cb4bf3346ca0e0153))

  ### Bug Fixes

  * Correct types of `userId` and `groupId` for creating collaboration ([#833](https://github.com/box/box-node-sdk/issues/833)) ([`f803ff8`](https://github.com/box/box-node-sdk/commit/f803ff82330fd78a8dc4875452a21aab54686b2e)), closes [#832](https://github.com/box/box-node-sdk/issues/832)
</Update>

<Update label="2023-05-26">
  ## UI Elements in Box for Salesforce managed package

  With the [Box for Salesforce](/guides/tooling/salesforce-toolkit/) managed package you can use the following [UI Elements](/guides/embed/ui-elements/) as Lightning Components: [content picker](/guides/embed/ui-elements/picker/), [explorer](/guides/embed/ui-elements/explorer), [preview](/guides/embed/ui-elements/preview), and [uploader](/guides/embed/ui-elements/uploader). You can use them on Lightning Pages, or in Flows.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-05-26">
  ## Box Python SDK v3.7.2 released

  ### Bug Fixes

  * Use the older version of `urllib3` ([#815](https://github.com/box/box-python-sdk/issues/815)) ([`ee29aa3`](https://github.com/box/box-python-sdk/commit/ee29aa3fcf9ac71e9866913a87414cf625c0b805))
</Update>

<Update label="2023-05-24">
  ## Integration mappings API

  With [integration mappings](/reference/resources/integration-mapping-slack), you can manage where content from partner apps is stored in Box.

  This feature currently only supports [Box as Content layer for Slack](https://support.box.com/hc/en-us/articles/4415585987859-Box-as-the-Content-Layer-for-Slack).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-05-23">
  ## Box Windows SDK v5.2.2 released

  ### Bug Fixes

  * catch exception when .net core version cannot be determined ([#906](https://github.com/box/box-windows-sdk-v2/issues/906)) ([`e3be209`](https://github.com/box/box-windows-sdk-v2/commit/e3be209b20a5c323f547d7634663883613959180))

  - [https://www.nuget.org/packages/Box.V2/5.2.2>](https://www.nuget.org/packages/Box.V2/5.2.2>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.2.2>](https://www.nuget.org/packages/Box.V2.Core/5.2.2>)
</Update>

<Update label="2023-05-23" description="Box Node SDK v3.0.0 released">
  ## Box Node SDK v3.0.0 released

  ### Breaking Changes

  The most important change in this release is **dropping support for Node versions below 12** and changing the **support environments from Node 12 to Node 16**.

  * Removed `use_index` usage. ([#812](https://github.com/box/box-node-sdk/pull/812)) ([`d56799a`](https://github.com/box/box-node-sdk/commit/d56799a61f42265d7785f99e92a449c58d125aef))
  * Removed deprecated `BoxClient.batch()` and `BoxClient.batchExec()` method.
  * Removed deprecated `CollaborationWhitelist` class, use `CollaborationAllowlist` instead.
  * Removed deprecated `CollaborationAllowlist.getWhitelistedDomain()` method, use `CollaborationAllowlist.getAllowlistedDomain()` instead.
  * Removed deprecated `CollaborationAllowlist.getAllWhitelistedDomains()` method, use `CollaborationAllowlist.getAllAllowlistedDomains()` instead.
  * Remove deprecated `Files.getThumbnail(fileID: string, options?: Record<string, any>, callback?: Function)` method, use `Files.getRepresentationContent( fileID, representationType, options, callback)` instead.

  Migration details can be found [here](https://github.com/box/box-node-sdk/blob/v3.0.0/docs/upgrade/2.x.x%20to%203.x.x.md)

  ### Dependency Upgrades

  * Bumped `jsonwebtoken` from 8.5.1 to 9.0.0. ([#802](https://github.com/box/box-node-sdk/pull/802)) ([`5b1d4e9`](https://github.com/box/box-node-sdk/pull/828/commits/5b1d4e9ec557c14c1d27695733cc0bcae49061cb))
  * Bumped `vm2` from 3.9.11 to 3.9.19 ([#826](https://github.com/box/box-node-sdk/pull/826)) ([`220df76`](https://github.com/box/box-node-sdk/commit/220df765080bc27c91daed51ac46620f6bc8b9ed))
</Update>

<Update label="2023-05-16">
  ## Box Java SDK v4.1.1 released

  ### Bug Fixes

  * Allow users to disable adding authentication header. ([#1167](https://github.com/box/box-java-sdk/issues/1167)) ([`3433e5a`](https://github.com/box/box-java-sdk/commit/3433e5a405ceb9bc32791642518b1fd65c4b4032))
  * Logging headers when retrying request ([#1164](https://github.com/box/box-java-sdk/issues/1164)) ([`e0c3d8e`](https://github.com/box/box-java-sdk/commit/e0c3d8e730962ba5c97105ce506ee931a3bba362))
</Update>

<Update label="2023-05-11">
  ## Box Node SDK v2.10.0 released

  ### New Features and Enhancements

  * Added support for ethical wall API ([#822](https://github.com/box/box-node-sdk/issues/822)) ([`4814af3`](https://github.com/box/box-node-sdk/commit/4814af35c1741fbfe3fa03f8f0412ade8b38dfcc))
  * Added `name` and `signature_color` fields to `SignRequest` and `SignRequestCreateRequest` types and `login_required` field to `SignRequestCreateSigner` type ([#822](https://github.com/box/box-node-sdk/issues/822)) ([`4814af3`](https://github.com/box/box-node-sdk/commit/4814af35c1741fbfe3fa03f8f0412ade8b38dfcc))
</Update>

<Update label="2023-05-10">
  ## Box UI Elements v17.1.0 released

  ### [17.1.0](https://github.com/box/box-ui-elements/compare/v17.0.0...v17.1.0) (2023-05-10)

  ### Bug Fixes

  * **content-explorer:** select all checkbox in empty folder ([#3324](https://github.com/box/box-ui-elements/issues/3324)) ([`a193adb`](https://github.com/box/box-ui-elements/commit/a193adb))
  * **content-explorer:** select all checkbox state matches `selectedItems` ([#3319](https://github.com/box/box-ui-elements/issues/3319)) ([`7473dfd`](https://github.com/box/box-ui-elements/commit/7473dfd))
  * **i18n:** update translations ([#3313](https://github.com/box/box-ui-elements/issues/3313)) ([`dd9a1fd`](https://github.com/box/box-ui-elements/commit/dd9a1fd))
  * **i18n:** update translations ([#3317](https://github.com/box/box-ui-elements/issues/3317)) ([`95618cf`](https://github.com/box/box-ui-elements/commit/95618cf))
  * **pill-selector-dropdown:** remove default value for `isPositionDynamic` ([#3320](https://github.com/box/box-ui-elements/issues/3320)) ([`e74f824`](https://github.com/box/box-ui-elements/commit/e74f824))
  * **preview:** videos not loading on edge ([#3326](https://github.com/box/box-ui-elements/issues/3326)) ([`e5aa7e5`](https://github.com/box/box-ui-elements/commit/e5aa7e5))
  * **usm:** make item prop optional ([#3322](https://github.com/box/box-ui-elements/issues/3322)) ([`fe7c4bb`](https://github.com/box/box-ui-elements/commit/fe7c4bb))

  ### Features

  * **sharing:** Change message for shared links for Canvas files ([#3315](https://github.com/box/box-ui-elements/issues/3315)) ([`fa17afd`](https://github.com/box/box-ui-elements/commit/fa17afd))
  * **sharing:** Change message for shared links for Canvas files ([#3318](https://github.com/box/box-ui-elements/issues/3318)) ([`60a3a6e`](https://github.com/box/box-ui-elements/commit/60a3a6e))
</Update>

<Update label="2023-05-10">
  ## Box Sign template APIs

  The new Box Sign template APIs allow you to [get a list of Box Sign templates](/reference/get-sign-templates) or details of a
  [specific Box Sign template](/reference/get-sign-templates-id).
  You can then use this information to initiate template-based sign requests.

  ## Where to get support

  Should you have any issues or need further guidance, post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-05-26">
  ## Updates to File Upload API

  In response to a potential security vulnerability while uploading a file using [Upload File API](/guides/uploads/direct) and downscoped token,
  we’re updating the Upload File API to return a 404 error in scenarios where the parent Folder ID is found, but the requester does not have permissions to access it.

  # Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-04-24">
  ## Box Java SDK v4.1.0 released

  ### New Features and Enhancements

  * Add missing `fields` parameter to create and update `BoxUser` methods ([#1155](https://github.com/box/box-java-sdk/issues/1155)) ([`be3820d`](https://github.com/box/box-java-sdk/commit/be3820dc4df15e99dfc13602d4f7269841bd15b3)), closes [#1154](https://github.com/box/box-java-sdk/issues/1154)

  ### Bug Fixes

  * Allow registering custom logger handlers ([#1156](https://github.com/box/box-java-sdk/issues/1156)) ([`7373d5c`](https://github.com/box/box-java-sdk/commit/7373d5cc2bf49bc198cbca70d056e43f0dffdb3a))
  * Fallback to default value of `maxRetryAttempts` when restoring `BoxAPIConnection` ([#1161](https://github.com/box/box-java-sdk/issues/1161)) ([`2a10e5d`](https://github.com/box/box-java-sdk/commit/2a10e5d07497611e077a9207fe98c1d8146cfd22)), closes [#1160](https://github.com/box/box-java-sdk/issues/1160)
</Update>

<Update label="2023-04-20">
  ## Box UI Elements v17.0.0 released

  ### [17.0.0](https://github.com/box/box-ui-elements/compare/v16.0.0...v17.0.0) (2023-04-20)

  ### Bug Fixes

  * **aci-toggle:** info badge vertical alignment ([#3290](https://github.com/box/box-ui-elements/issues/3290)) ([`f73b9f9`](https://github.com/box/box-ui-elements/commit/f73b9f9))
  * **avatar:** Add `aria-label` to external user icon ([#3263](https://github.com/box/box-ui-elements/issues/3263)) ([`18cdf3f`](https://github.com/box/box-ui-elements/commit/18cdf3f))
  * **collaborator-list-item:** remove redundant titles ([#3255](https://github.com/box/box-ui-elements/issues/3255)) ([`d805249`](https://github.com/box/box-ui-elements/commit/d805249))
  * **content-explorer:** add arrow navigation ([#3219](https://github.com/box/box-ui-elements/issues/3219)) ([`35bf8de`](https://github.com/box/box-ui-elements/commit/35bf8de))
  * **content-explorer:** Add `svg` titles to icons ([#3227](https://github.com/box/box-ui-elements/issues/3227)) ([`506ca45`](https://github.com/box/box-ui-elements/commit/506ca45))
  * **content-explorer:** change color of folder tree breadcrumbs text ([#3268](https://github.com/box/box-ui-elements/issues/3268)) ([`fc95d4d`](https://github.com/box/box-ui-elements/commit/fc95d4d))
  * **content-explorer:** enable create folder with trailing space in name ([#3246](https://github.com/box/box-ui-elements/issues/3246)) ([`e0b03c7`](https://github.com/box/box-ui-elements/commit/e0b03c7))
  * **content-explorer:** Fix color contrast issue for item details ([#3273](https://github.com/box/box-ui-elements/issues/3273)) ([`4db0231`](https://github.com/box/box-ui-elements/commit/4db0231))
  * **content-explorer:** Fix color contrast issues ([#3221](https://github.com/box/box-ui-elements/issues/3221)) ([`b7ecaab`](https://github.com/box/box-ui-elements/commit/b7ecaab))
  * **content-explorer:** fix item list column header role ([#3232](https://github.com/box/box-ui-elements/issues/3232)) ([`718a71a`](https://github.com/box/box-ui-elements/commit/718a71a))
  * **content-explorer:** focus border on selected item row buttons ([#3314](https://github.com/box/box-ui-elements/issues/3314)) ([`a596557`](https://github.com/box/box-ui-elements/commit/a596557))
  * **content-explorer:** hide instead of deactivate breadcrumbs ([#3260](https://github.com/box/box-ui-elements/issues/3260)) ([`5b5fec1`](https://github.com/box/box-ui-elements/commit/5b5fec1))
  * **content-explorer:** Include subfolders sub-header fix ([#3259](https://github.com/box/box-ui-elements/issues/3259)) ([`6ec1512`](https://github.com/box/box-ui-elements/commit/6ec1512))
  * **content-explorer:** status message for include subfolders ([#3261](https://github.com/box/box-ui-elements/issues/3261)) ([`3ce688d`](https://github.com/box/box-ui-elements/commit/3ce688d))
  * **content-explorer:** Update Share button border on selected row ([#3278](https://github.com/box/box-ui-elements/issues/3278)) ([`28c79dd`](https://github.com/box/box-ui-elements/commit/28c79dd))
  * **content-picker:** add `disabled` attribute ([#3243](https://github.com/box/box-ui-elements/issues/3243)) ([`a88a96c`](https://github.com/box/box-ui-elements/commit/a88a96c))
  * **content-sharing:** removed API condition when constructing API ([#3251](https://github.com/box/box-ui-elements/issues/3251)) ([`24dcba2`](https://github.com/box/box-ui-elements/commit/24dcba2))
  * **content-uploader:** make deactivated buttons unfocusable ([#3248](https://github.com/box/box-ui-elements/issues/3248)) ([`2302712`](https://github.com/box/box-ui-elements/commit/2302712))
  * **flyout:** increase flyout overlay CSS specificity ([#3257](https://github.com/box/box-ui-elements/issues/3257)) ([`0933062`](https://github.com/box/box-ui-elements/commit/0933062))
  * **i18n:** update translations ([#3250](https://github.com/box/box-ui-elements/issues/3250)) ([`d84d1ca`](https://github.com/box/box-ui-elements/commit/d84d1ca))
  * **i18n:** update translations ([#3276](https://github.com/box/box-ui-elements/issues/3276)) ([`018a99c`](https://github.com/box/box-ui-elements/commit/018a99c))
  * **i18n:** update translations ([#3285](https://github.com/box/box-ui-elements/issues/3285)) ([`bfbcf55`](https://github.com/box/box-ui-elements/commit/bfbcf55))
  * **i18n:** update translations ([#3300](https://github.com/box/box-ui-elements/issues/3300)) ([`88116cb`](https://github.com/box/box-ui-elements/commit/88116cb))
  * **itemlist:** Remove header section when list is empty ([#3224](https://github.com/box/box-ui-elements/issues/3224)) ([`0274618`](https://github.com/box/box-ui-elements/commit/0274618))
  * **makeselectable:** Prevent arrow hotkeys on slider ([#3299](https://github.com/box/box-ui-elements/issues/3299)) ([`a893e5a`](https://github.com/box/box-ui-elements/commit/a893e5a))
  * **metadata:** fix template drop-down truncation issue ([#3265](https://github.com/box/box-ui-elements/issues/3265)) ([`c3ae099`](https://github.com/box/box-ui-elements/commit/c3ae099))
  * **select-field:** Add bottom margin when drop-down has top placement ([#3302](https://github.com/box/box-ui-elements/issues/3302)) ([`11e6979`](https://github.com/box/box-ui-elements/commit/11e6979))
  * **select-field:** add tether class for select drop-downs ([#3303](https://github.com/box/box-ui-elements/issues/3303)) ([`ce27f70`](https://github.com/box/box-ui-elements/commit/ce27f70))
  * **selector-dropdown:** add dynamic positioning to the drop-down overlay ([#3262](https://github.com/box/box-ui-elements/issues/3262)) ([`7f05653`](https://github.com/box/box-ui-elements/commit/7f05653))
  * **usm:** Order person before icon in collaborator list DOM ([#3306](https://github.com/box/box-ui-elements/issues/3306)) ([`32c656d`](https://github.com/box/box-ui-elements/commit/32c656d))
  * add props to omit to avoid console warnings ([#3286](https://github.com/box/box-ui-elements/issues/3286)) ([`11328fb`](https://github.com/box/box-ui-elements/commit/11328fb))
  * Align menu options in BE sort button ([#3231](https://github.com/box/box-ui-elements/issues/3231)) ([`dcc06e2`](https://github.com/box/box-ui-elements/commit/dcc06e2))
  * Fix `aria-label` for BE header search ([#3244](https://github.com/box/box-ui-elements/issues/3244)) ([`ca01965`](https://github.com/box/box-ui-elements/commit/ca01965))
  * Replace `bdl-gray-62` for USM and Shared Link components ([#3289](https://github.com/box/box-ui-elements/issues/3289)) ([`1f25b98`](https://github.com/box/box-ui-elements/commit/1f25b98))
  * **makeselectable:** shift and arrow selects first row ([#3223](https://github.com/box/box-ui-elements/issues/3223)) ([`9b209e5`](https://github.com/box/box-ui-elements/commit/9b209e5))
  * **scss:** Replace all division for dart-sass ([#3253](https://github.com/box/box-ui-elements/issues/3253)) ([`ac92e21`](https://github.com/box/box-ui-elements/commit/ac92e21))
  * **shared-link-section:** accessibility tooltip ([#3216](https://github.com/box/box-ui-elements/issues/3216)) ([`4ecdd81`](https://github.com/box/box-ui-elements/commit/4ecdd81))
  * **sub-header:** sort menu item accessibility ([#3230](https://github.com/box/box-ui-elements/issues/3230)) ([`20f4454`](https://github.com/box/box-ui-elements/commit/20f4454))
  * **sub-header:** update sort to use select component and update tests ([#3239](https://github.com/box/box-ui-elements/issues/3239)) ([`528a157`](https://github.com/box/box-ui-elements/commit/528a157))
  * **toggle:** add switch role ([#3254](https://github.com/box/box-ui-elements/issues/3254)) ([`cf0c894`](https://github.com/box/box-ui-elements/commit/cf0c894))
  * **tooltip:** Deactivate `aria-describedby` when `ariaHidden` is `true` ([#3233](https://github.com/box/box-ui-elements/issues/3233)) ([`d9108c4`](https://github.com/box/box-ui-elements/commit/d9108c4))
  * **tooltip:** tooltip should be dialog ([#3226](https://github.com/box/box-ui-elements/issues/3226))" ([#3264](https://github.com/box/box-ui-elements/issues/3264)) ([`fa68dd6`](https://github.com/box/box-ui-elements/commit/fa68dd6))
  * **usm:** Remove `aria-label` and add `aria-haspopup` ([#3281](https://github.com/box/box-ui-elements/issues/3281)) ([`fd1a82d`](https://github.com/box/box-ui-elements/commit/fd1a82d))
  * **usm:** Removing redundant button element ([#3282](https://github.com/box/box-ui-elements/issues/3282)) ([`a7005ff`](https://github.com/box/box-ui-elements/commit/a7005ff))
  * change type of buttons in Content Sharing from 'submit' to 'button' ([#3277](https://github.com/box/box-ui-elements/issues/3277)) ([`26b7e5f`](https://github.com/box/box-ui-elements/commit/26b7e5f))
  * Improve color contrast for input borders ([#3234](https://github.com/box/box-ui-elements/issues/3234)) ([`3917bee`](https://github.com/box/box-ui-elements/commit/3917bee))
  * Improve color contrast for placeholder text ([#3228](https://github.com/box/box-ui-elements/issues/3228)) ([`1f7b9f9`](https://github.com/box/box-ui-elements/commit/1f7b9f9))
  * Update `box-shadow` for inputs ([#3236](https://github.com/box/box-ui-elements/issues/3236)) ([`07cc347`](https://github.com/box/box-ui-elements/commit/07cc347))
  * **assets:** Use correct icons after icons were renamed ([#3138](https://github.com/box/box-ui-elements/issues/3138)) ([`2c80164`](https://github.com/box/box-ui-elements/commit/2c80164))
  * **content-explorer:** add `aria-label` for `MoreOptions` button ([#3197](https://github.com/box/box-ui-elements/issues/3197)) ([`f4b69f0`](https://github.com/box/box-ui-elements/commit/f4b69f0))
  * **content-explorer:** add `aria-label` to grid slider ([#3189](https://github.com/box/box-ui-elements/issues/3189)) ([`e3900b3`](https://github.com/box/box-ui-elements/commit/e3900b3))
  * **content-explorer:** create default shared link when none exists ([#3209](https://github.com/box/box-ui-elements/issues/3209)) ([`5d05a2b`](https://github.com/box/box-ui-elements/commit/5d05a2b))
  * **content-explorer:** Pass all props from `modalContainer` to `Modal` ([#3104](https://github.com/box/box-ui-elements/issues/3104)) ([`5d5b314`](https://github.com/box/box-ui-elements/commit/5d5b314))
  * **content-explorer:** Remove props from `styleguidist` examples ([#3146](https://github.com/box/box-ui-elements/issues/3146)) ([`1f0809b`](https://github.com/box/box-ui-elements/commit/1f0809b))
  * **content-picker:** add accessible names to Footer ([#3177](https://github.com/box/box-ui-elements/issues/3177)) ([`bd8e1e6`](https://github.com/box/box-ui-elements/commit/bd8e1e6))
  * **content-sidebar:** reply operations interactions ([#3103](https://github.com/box/box-ui-elements/issues/3103)) ([`9400f5a`](https://github.com/box/box-ui-elements/commit/9400f5a))
  * **content-sidebar:** reply operations interactions ([#3123](https://github.com/box/box-ui-elements/issues/3123)) ([`8d2c3f1`](https://github.com/box/box-ui-elements/commit/8d2c3f1))
  * **content-sidebar:** select and hover state for threaded feed items ([#3173](https://github.com/box/box-ui-elements/issues/3173)) ([`a7dc6a9`](https://github.com/box/box-ui-elements/commit/a7dc6a9))
  * **content-uploader:** fix `UploadInput` keyboard accessibility ([#3205](https://github.com/box/box-ui-elements/issues/3205)) ([`e918b5f`](https://github.com/box/box-ui-elements/commit/e918b5f))
  * **dropdown-menu:** fix positioning for responsive drop-down menu ([#3149](https://github.com/box/box-ui-elements/issues/3149)) ([`729f6f1`](https://github.com/box/box-ui-elements/commit/729f6f1))
  * **grid-view:** unhide focus outline for grid view slider ([#3212](https://github.com/box/box-ui-elements/issues/3212)) ([`b35e977`](https://github.com/box/box-ui-elements/commit/b35e977))
  * **i18n:** update translations ([#3105](https://github.com/box/box-ui-elements/issues/3105)) ([`b8521e4`](https://github.com/box/box-ui-elements/commit/b8521e4))
  * **i18n:** update translations ([#3111](https://github.com/box/box-ui-elements/issues/3111)) ([`29fc19c`](https://github.com/box/box-ui-elements/commit/29fc19c))
  * **i18n:** update translations ([#3121](https://github.com/box/box-ui-elements/issues/3121)) ([`16bc077`](https://github.com/box/box-ui-elements/commit/16bc077))
  * **i18n:** update translations ([#3130](https://github.com/box/box-ui-elements/issues/3130)) ([`8ca714b`](https://github.com/box/box-ui-elements/commit/8ca714b))
  * **i18n:** update translations ([#3135](https://github.com/box/box-ui-elements/issues/3135)) ([`53c0370`](https://github.com/box/box-ui-elements/commit/53c0370))
  * **i18n:** update translations ([#3137](https://github.com/box/box-ui-elements/issues/3137)) ([`7fe32a6`](https://github.com/box/box-ui-elements/commit/7fe32a6))
  * **i18n:** update translations ([#3139](https://github.com/box/box-ui-elements/issues/3139)) ([`82f414d`](https://github.com/box/box-ui-elements/commit/82f414d))
  * **i18n:** update translations ([#3150](https://github.com/box/box-ui-elements/issues/3150)) ([`d428a43`](https://github.com/box/box-ui-elements/commit/d428a43))
  * **i18n:** update translations ([#3158](https://github.com/box/box-ui-elements/issues/3158)) ([`02eb624`](https://github.com/box/box-ui-elements/commit/02eb624))
  * **i18n:** update translations ([#3159](https://github.com/box/box-ui-elements/issues/3159)) ([`6df6f0d`](https://github.com/box/box-ui-elements/commit/6df6f0d))
  * **i18n:** update translations ([#3174](https://github.com/box/box-ui-elements/issues/3174)) ([`0e9ea9d`](https://github.com/box/box-ui-elements/commit/0e9ea9d))
  * **i18n:** update translations ([#3183](https://github.com/box/box-ui-elements/issues/3183)) ([`c32bbae`](https://github.com/box/box-ui-elements/commit/c32bbae))
  * **i18n:** update translations ([#3199](https://github.com/box/box-ui-elements/issues/3199)) ([`eb1acee`](https://github.com/box/box-ui-elements/commit/eb1acee))
  * **i18n:** update translations ([#3207](https://github.com/box/box-ui-elements/issues/3207)) ([`d9d571d`](https://github.com/box/box-ui-elements/commit/d9d571d))
  * **i18n:** update translations ([#3213](https://github.com/box/box-ui-elements/issues/3213)) ([`64364c3`](https://github.com/box/box-ui-elements/commit/64364c3))
  * **i18n:** update translations ([#3220](https://github.com/box/box-ui-elements/issues/3220)) ([`39739ab`](https://github.com/box/box-ui-elements/commit/39739ab))
  * **i18n:** update translations ([#3222](https://github.com/box/box-ui-elements/issues/3222)) ([`429c856`](https://github.com/box/box-ui-elements/commit/429c856))
  * **item-action:** add `aria-label` to `PlainButton` ([#3180](https://github.com/box/box-ui-elements/issues/3180)) ([`2553713`](https://github.com/box/box-ui-elements/commit/2553713))
  * **item-remove:** add `aria-label` ([#3181](https://github.com/box/box-ui-elements/issues/3181)) ([`0fce635`](https://github.com/box/box-ui-elements/commit/0fce635))
  * **menu:** fix long title in menu header ([#3125](https://github.com/box/box-ui-elements/issues/3125)) ([`79420f2`](https://github.com/box/box-ui-elements/commit/79420f2))
  * **modal:** Modal header for long file names was displaying incorrectly ([#3108](https://github.com/box/box-ui-elements/issues/3108)) ([`d8321aa`](https://github.com/box/box-ui-elements/commit/d8321aa))
  * **react-virtualized:** Bumped `react-virtualized` ([#3160](https://github.com/box/box-ui-elements/issues/3160)) ([`b256b07`](https://github.com/box/box-ui-elements/commit/b256b07))
  * **react-virtualized:** remove duplicate `a11y` label ([#3204](https://github.com/box/box-ui-elements/issues/3204)) ([`c67a4dd`](https://github.com/box/box-ui-elements/commit/c67a4dd))
  * **react-virtualized:** Remove role for `Table_Grid_innerScrollContainer` ([#3218](https://github.com/box/box-ui-elements/issues/3218)) ([`cabb4a8`](https://github.com/box/box-ui-elements/commit/cabb4a8))
  * **replies:** fix `total_replies_count` value update after delete reply ([#3147](https://github.com/box/box-ui-elements/issues/3147)) ([`8f75827`](https://github.com/box/box-ui-elements/commit/8f75827))
  * **sharedlinksettings:** fix expiration timestamp ([#3179](https://github.com/box/box-ui-elements/issues/3179)) ([`1a698c5`](https://github.com/box/box-ui-elements/commit/1a698c5))
  * **sub-header:** add accessibility label to `SortButton` ([#3178](https://github.com/box/box-ui-elements/issues/3178)) ([`ba66a34`](https://github.com/box/box-ui-elements/commit/ba66a34))
  * **threaded-replies:** deactivate reply button for pending status ([#3186](https://github.com/box/box-ui-elements/issues/3186)) ([`efbc532`](https://github.com/box/box-ui-elements/commit/efbc532))
  * **threaded-replies:** fix styling for replies ([#3110](https://github.com/box/box-ui-elements/issues/3110)) ([`f78e36b`](https://github.com/box/box-ui-elements/commit/f78e36b))
  * **tooltips:** Error tooltips were being truncated on smaller screens ([#3107](https://github.com/box/box-ui-elements/issues/3107)) ([`7e12d88`](https://github.com/box/box-ui-elements/commit/7e12d88))
  * **usm:** add `aria label` ([#3191](https://github.com/box/box-ui-elements/issues/3191)) ([`f1f5c81`](https://github.com/box/box-ui-elements/commit/f1f5c81))
  * **usm:** add `aria-label` to expiration icon ([#3193](https://github.com/box/box-ui-elements/issues/3193)) ([`af3c567`](https://github.com/box/box-ui-elements/commit/af3c567))
  * **usm:** add `aria-label` to tooltip close button ([#3211](https://github.com/box/box-ui-elements/issues/3211)) ([`529bf10`](https://github.com/box/box-ui-elements/commit/529bf10))
  * **usm:** add role `img` to shared link expiration tooltip icon ([#3195](https://github.com/box/box-ui-elements/issues/3195)) ([`a79e193`](https://github.com/box/box-ui-elements/commit/a79e193))
  * **usm:** tooltip should be dialog ([#3226](https://github.com/box/box-ui-elements/issues/3226)) ([`f52ad0e`](https://github.com/box/box-ui-elements/commit/f52ad0e))
  * remove warning when passing `initialSelectedItems` to `ContentExplorer` ([#3151](https://github.com/box/box-ui-elements/issues/3151)) ([`bf3256a`](https://github.com/box/box-ui-elements/commit/bf3256a))

  ### Code Refactoring

  * deprecate `bdl-gray-62` color ([#3312](https://github.com/box/box-ui-elements/issues/3312)) ([`93720ce`](https://github.com/box/box-ui-elements/commit/93720ce))

  ### Features

  * **aci-toggle:** add separate prop for description ([#3307](https://github.com/box/box-ui-elements/issues/3307)) ([`cadab1d`](https://github.com/box/box-ui-elements/commit/cadab1d))
  * **aci-toggle:** UI adjustments ([#3297](https://github.com/box/box-ui-elements/issues/3297)) ([`84f9abb`](https://github.com/box/box-ui-elements/commit/84f9abb))
  * **annotation:** Add icon indicator for `AnnotationActivity` ([#3176](https://github.com/box/box-ui-elements/issues/3176)) ([`f773aa3`](https://github.com/box/box-ui-elements/commit/f773aa3))
  * **annotation-activity:** hide `AnnotationActivityLink` ([#3089](https://github.com/box/box-ui-elements/issues/3089)) ([`dc3642e`](https://github.com/box/box-ui-elements/commit/dc3642e))
  * **annotation-thread:** added reply form, UI and other minor fixes ([#3157](https://github.com/box/box-ui-elements/issues/3157)) ([`55ca058`](https://github.com/box/box-ui-elements/commit/55ca058))
  * **annotation-thread:** Annotation thread comments visual fixes ([#3128](https://github.com/box/box-ui-elements/issues/3128)) ([`fac5133`](https://github.com/box/box-ui-elements/commit/fac5133))
  * **annotation-thread:** annotation thread events handling ([#3196](https://github.com/box/box-ui-elements/issues/3196)) ([`1c07b41`](https://github.com/box/box-ui-elements/commit/1c07b41))
  * **annotation-thread:** annotation thread related hooks refactoring ([#3192](https://github.com/box/box-ui-elements/issues/3192)) ([`0168f1a`](https://github.com/box/box-ui-elements/commit/0168f1a))
  * **annotation-thread:** annotation thread replies events handling ([#3201](https://github.com/box/box-ui-elements/issues/3201)) ([`3df222a`](https://github.com/box/box-ui-elements/commit/3df222a))
  * **annotation-thread:** introduce `useAnnotationThread` and handle `useAnnotatorEvents` ([#3097](https://github.com/box/box-ui-elements/issues/3097)) ([`a8d1985`](https://github.com/box/box-ui-elements/commit/a8d1985))
  * **annotation-thread:** use of event emitter and hooks refactoring ([#3184](https://github.com/box/box-ui-elements/issues/3184)) ([`cfed356`](https://github.com/box/box-ui-elements/commit/cfed356))
  * **annotations:** hide `AnnotationActivityLink` based on `hasVersions` prop ([#3132](https://github.com/box/box-ui-elements/issues/3132)) ([`3469413`](https://github.com/box/box-ui-elements/commit/3469413))
  * **assets:** update cancellation flow assets ([#3117](https://github.com/box/box-ui-elements/issues/3117)) ([`42e1122`](https://github.com/box/box-ui-elements/commit/42e1122))
  * **checkbox:** allow `stopPropagation` on `onClick` events ([#3122](https://github.com/box/box-ui-elements/issues/3122)) ([`9c25858`](https://github.com/box/box-ui-elements/commit/9c25858))
  * **checkbox:** make focus behavior configurable ([#3214](https://github.com/box/box-ui-elements/issues/3214)) ([`18b8ea6`](https://github.com/box/box-ui-elements/commit/18b8ea6))
  * **checkbox:** prop to add class to input ([#3194](https://github.com/box/box-ui-elements/issues/3194)) ([`e0cc12d`](https://github.com/box/box-ui-elements/commit/e0cc12d))
  * **checkbox:** revert allow `stopPropagation` on `onClick` events ([#3127](https://github.com/box/box-ui-elements/issues/3127)) ([`e37de34`](https://github.com/box/box-ui-elements/commit/e37de34)), closes [#3122](https://github.com/box/box-ui-elements/issues/3122)
  * **cloud-game:** Add accessibility to security cloud game ([#3086](https://github.com/box/box-ui-elements/issues/3086)) ([`684e9f6`](https://github.com/box/box-ui-elements/commit/684e9f6))
  * **collapsible-sidebar:** add prop to hide Box logo ([#3256](https://github.com/box/box-ui-elements/issues/3256)) ([`43279c0`](https://github.com/box/box-ui-elements/commit/43279c0))
  * **collapsible-sidebar:** add `wrapperClassName` prop ([#3295](https://github.com/box/box-ui-elements/issues/3295)) ([`2cde065`](https://github.com/box/box-ui-elements/commit/2cde065))
  * **content-explorer:** adding folder tree ([#3240](https://github.com/box/box-ui-elements/issues/3240)) ([`03b0dea`](https://github.com/box/box-ui-elements/commit/03b0dea))
  * **content-explorer:** Allow selecting empty selection in `ContentExplorer` ([#3175](https://github.com/box/box-ui-elements/issues/3175)) ([`fead6e4`](https://github.com/box/box-ui-elements/commit/fead6e4))
  * **content-explorer:** clickable status message for include subfolders ([#3266](https://github.com/box/box-ui-elements/issues/3266)) ([`3d8eaf8`](https://github.com/box/box-ui-elements/commit/3d8eaf8))
  * **content-explorer:** include subfolders toggle ([#3242](https://github.com/box/box-ui-elements/issues/3242)) ([`b75c7ee`](https://github.com/box/box-ui-elements/commit/b75c7ee))
  * **content-sidebar:** add on fetch file callback function ([#3118](https://github.com/box/box-ui-elements/issues/3118)) ([`5373031`](https://github.com/box/box-ui-elements/commit/5373031))
  * **content-sidebar:** added support for active comment reply ([#3134](https://github.com/box/box-ui-elements/issues/3134)) ([`3ef81e1`](https://github.com/box/box-ui-elements/commit/3ef81e1))
  * **content-sidebar:** hide "edited" for resolved comment/annotation ([#3152](https://github.com/box/box-ui-elements/issues/3152)) ([`07f5fc7`](https://github.com/box/box-ui-elements/commit/07f5fc7))
  * **content-sidebar:** select and hover state for threaded feed items ([#3162](https://github.com/box/box-ui-elements/issues/3162)) ([`a6c125d`](https://github.com/box/box-ui-elements/commit/a6c125d))
  * **input-with-copy:** add node for settings button ([#3267](https://github.com/box/box-ui-elements/issues/3267)) ([`719b31f`](https://github.com/box/box-ui-elements/commit/719b31f))
  * **insights:** Added support for Advanced Content Insights ([#3116](https://github.com/box/box-ui-elements/issues/3116)) ([`a66ec89`](https://github.com/box/box-ui-elements/commit/a66ec89))
  * **left-nav:** Update medium width in `\_sizes.media.scss` ([#3131](https://github.com/box/box-ui-elements/issues/3131)) ([`aaf112d`](https://github.com/box/box-ui-elements/commit/aaf112d))
  * **list-view:** List View item hover state changes ([#3115](https://github.com/box/box-ui-elements/issues/3115)) ([`103a5d1`](https://github.com/box/box-ui-elements/commit/103a5d1))
  * **make-selectable:** Add select click functionality to on checkbox click ([#3112](https://github.com/box/box-ui-elements/issues/3112)) ([`ffc2e33`](https://github.com/box/box-ui-elements/commit/ffc2e33))
  * **make-selectable:** expose `selectToggle` function ([#3109](https://github.com/box/box-ui-elements/issues/3109)) ([`8d9fb90`](https://github.com/box/box-ui-elements/commit/8d9fb90))
  * **mediaquery:** add `isTouchScreen` logic ([#3269](https://github.com/box/box-ui-elements/issues/3269)) ([`3e80a06`](https://github.com/box/box-ui-elements/commit/3e80a06))
  * **modal:** add callback to check permission on shared link load ([#3188](https://github.com/box/box-ui-elements/issues/3188)) ([`2b316db`](https://github.com/box/box-ui-elements/commit/2b316db))
  * **preview:** add new sign drop-down under ff ([#3190](https://github.com/box/box-ui-elements/issues/3190)) ([`37e8a19`](https://github.com/box/box-ui-elements/commit/37e8a19))
  * **threaded-replies:** Create `Replies` component ([#3288](https://github.com/box/box-ui-elements/issues/3288)) ([`006e33c`](https://github.com/box/box-ui-elements/commit/006e33c))
  * **threaded-replies:** Create `RepliesToggle` component ([#3294](https://github.com/box/box-ui-elements/issues/3294)) ([`92d0ddb`](https://github.com/box/box-ui-elements/commit/92d0ddb))
  * **threaded-replies:** Create `Reply` button component ([#3298](https://github.com/box/box-ui-elements/issues/3298)) ([`f9d4130`](https://github.com/box/box-ui-elements/commit/f9d4130))
  * **threaded-replies:** Decouple `ActivityCard` from Comment ([#3279](https://github.com/box/box-ui-elements/issues/3279)) ([`7d1d3bf`](https://github.com/box/box-ui-elements/commit/7d1d3bf))
  * **threaded-replies:** Implement Create Replies and Replies Toggle ([#3304](https://github.com/box/box-ui-elements/issues/3304)) ([`044a336`](https://github.com/box/box-ui-elements/commit/044a336))
  * **threaded-replies:** Refactor Comment component to functional ([#3270](https://github.com/box/box-ui-elements/issues/3270)) ([`3900d1c`](https://github.com/box/box-ui-elements/commit/3900d1c))
  * **threaded-replies:** Update activity filter to support more options ([#3280](https://github.com/box/box-ui-elements/issues/3280)) ([`76e4010`](https://github.com/box/box-ui-elements/commit/76e4010))
  * add `additionalColumns` prop to `ContentExplorerModalContainer` ([#3143](https://github.com/box/box-ui-elements/issues/3143)) ([`d4eea59`](https://github.com/box/box-ui-elements/commit/d4eea59))
  * Add option to display header in `ContentExplorerModalContainer` ([#3144](https://github.com/box/box-ui-elements/issues/3144)) ([`5685142`](https://github.com/box/box-ui-elements/commit/5685142))
  * Add optional tether props to `DropdownMenu` ([#3245](https://github.com/box/box-ui-elements/issues/3245)) ([`9db75e7`](https://github.com/box/box-ui-elements/commit/9db75e7))
  * **threaded-replies:** fix styling for resolve ([#3129](https://github.com/box/box-ui-elements/issues/3129)) ([`b291c50`](https://github.com/box/box-ui-elements/commit/b291c50))
  * **threaded-replies:** keep replies visible when loading more replies ([#3133](https://github.com/box/box-ui-elements/issues/3133)) ([`295533c`](https://github.com/box/box-ui-elements/commit/295533c))
  * **tooltip:** support error tooltip position ([#3187](https://github.com/box/box-ui-elements/issues/3187)) ([`941e990`](https://github.com/box/box-ui-elements/commit/941e990))
  * add `rowHeight` prop to `ContentExplorerModal` ([#3140](https://github.com/box/box-ui-elements/issues/3140)) ([`476d739`](https://github.com/box/box-ui-elements/commit/476d739))

  ### Reverts

  * "chore(answers): added foundation for content-answers element … ([#3249](https://github.com/box/box-ui-elements/issues/3249)) ([`56f58a5`](https://github.com/box/box-ui-elements/commit/56f58a5)), closes [#3247](https://github.com/box/box-ui-elements/issues/3247)
  * **annotation-activity:** hide `AnnotationActivityLink` ([#3120](https://github.com/box/box-ui-elements/issues/3120)) ([`ba22807`](https://github.com/box/box-ui-elements/commit/ba22807)), closes [#3089](https://github.com/box/box-ui-elements/issues/3089)

  ### BREAKING CHANGES

  * `bdl-gray-62` is replaced with `bdl-gray-65`
</Update>

<Update label="2023-04-20">
  ## Updates to Box Embed guide

  With [Box Embed](/guides/embed/box-embed/) you can embed a Box webapp anywhere in your application. The updated webapp is responsive to any changes. For example, if an integration makes the embedded Box webapp smaller, all the UI components such as buttons and lists will also be resized to still be usable.

  The update also includes a description of the cloud game, a widget which increases security by preventing clickjacking.

  # Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-04-19">
  ## Box Node SDK v2.9.0 released

  ### New Features and Enhancements

  * New fields in `retention-policy` and `retention-policy-assignment` ([#803](https://github.com/box/box-node-sdk/issues/803)) ([`f14ba84`](https://github.com/box/box-node-sdk/commit/f14ba84013985513854ad396581d085d1d4f0255))

  ### Bug Fixes

  * return empty object when `tos` status is not present ([#797](https://github.com/box/box-node-sdk/issues/797)) ([`12fd9b0`](https://github.com/box/box-node-sdk/commit/12fd9b053707471722f53cd1760c8cf59451fe8d))
</Update>

<Update label="2023-04-19">
  ## Box iOS SDK v5.4.2 released

  ### Bug Fixes

  * An empty string `nextMarker` should be treated as end-of-paging. ([#893](https://github.com/box/box-ios-sdk/issues/893)) ([`49c17de`](https://github.com/box/box-ios-sdk/commit/49c17de588fcffcd2d151ce9047ebc09965f80ce))
</Update>

<Update label="2023-04-18">
  ## Box Windows SDK v5.2.1 released

  ### Bug Fixes

  * Catch all exceptions when getting User Agent header ([#901](https://github.com/box/box-windows-sdk-v2/issues/901)) ([`75d8874`](https://github.com/box/box-windows-sdk-v2/commit/75d887470698a5f312610cebd58be58aee7eaa9b))

  - [https://www.nuget.org/packages/Box.V2/5.2.1>](https://www.nuget.org/packages/Box.V2/5.2.1>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.2.1>](https://www.nuget.org/packages/Box.V2.Core/5.2.1>)
</Update>

<Update label="2023-04-18">
  ## Box Python SDK v3.7.1 released

  ### Bug Fixes

  * Rename filter date parameters in legal hold creation according to the documentation ([#810](https://github.com/box/box-python-sdk/issues/810)) ([`f52c66a`](https://github.com/box/box-python-sdk/commit/f52c66a8a8399a776493537f692460ace2995e40))
</Update>

<Update label="2023-04-17">
  ## Add more details to Custom Apps

  To clarify [Platform Apps](/guides/applications/platform-apps/index)' purpose and add the value for the enterprise, we now offer a possibility of describing the Custom App in a more granular way.

  When setting up a Custom App with [OAuth](/guides/authentication/oauth2/oauth2-setup), [JWT](/guides/authentication/jwt/jwt-setup) or [Client Credentials](/guides/authentication/client-credentials/client-credentials-setup), you can now specify the purpose of the app and the app's creator.
  Additionally, if you intend to integrate your app with an external system, you can define the integration category and provide details of the external system.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-03-28">
  ## Collaborations API - pending status

  We added more information about the `pending` status in our [collaborations API](/reference/resources/collaboration).

  If the collaboration is in [`pending` status](/reference/post-collaborations):

  * login and name return an empty string,
  * the following fields are redacted:
    * `login` and `name` are hidden if a collaboration was created using `user_id`,
    * `name` is hidden if a collaboration was created using `login`.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-03-14">
  ## Box Windows SDK v5.2.0 released

  ### New Features and Enhancements

  * add `Id` to `MetadataTemplateField` ([#890](https://github.com/box/box-windows-sdk-v2/issues/890)) ([`b7fe214`](https://github.com/box/box-windows-sdk-v2/commit/b7fe2149e1a0ade8573b497b7bb36e9f3c4f4a82))
  * add `start_date_field` and `description` to retention policies ([#888](https://github.com/box/box-windows-sdk-v2/issues/888)) ([`100b722`](https://github.com/box/box-windows-sdk-v2/commit/100b722ce4909395c00b527677564f37a61ec2cb))
  * add configurable `JWTAudience` claim ([#897](https://github.com/box/box-windows-sdk-v2/issues/897)) ([`50219fd`](https://github.com/box/box-windows-sdk-v2/commit/50219fdfd553d6335b6f0b4341719b09680c4ba0))
  * add shared link support to `GetFolderItemsAsync` ([#892](https://github.com/box/box-windows-sdk-v2/issues/892)) ([`0eba85c`](https://github.com/box/box-windows-sdk-v2/commit/0eba85c693763472c51fe81cbc43222305e9eefb))

  ### Bug Fixes

  * Use fixed value of `aud` field in `JWT` claim ([#896](https://github.com/box/box-windows-sdk-v2/issues/896)) ([`8c9982d`](https://github.com/box/box-windows-sdk-v2/commit/8c9982d160ec4806c796ee2621b1811232ea59c1))

  * add `Id` to `MetadataTemplateField` ([#890](https://github.com/box/box-windows-sdk-v2/issues/890)) ([`b7fe214`](https://github.com/box/box-windows-sdk-v2/commit/b7fe2149e1a0ade8573b497b7bb36e9f3c4f4a82))

  * add `start_date_field` and `description` to retention policies ([#888](https://github.com/box/box-windows-sdk-v2/issues/888)) ([`100b722`](https://github.com/box/box-windows-sdk-v2/commit/100b722ce4909395c00b527677564f37a61ec2cb))

  * add configurable `JWTAudience` claim ([#897](https://github.com/box/box-windows-sdk-v2/issues/897)) ([`50219fd`](https://github.com/box/box-windows-sdk-v2/commit/50219fdfd553d6335b6f0b4341719b09680c4ba0))

  * add shared link support to `GetFolderItemsAsync` ([#892](https://github.com/box/box-windows-sdk-v2/issues/892)) ([`0eba85c`](https://github.com/box/box-windows-sdk-v2/commit/0eba85c693763472c51fe81cbc43222305e9eefb))

  - [https://www.nuget.org/packages/Box.V2/5.2.0>](https://www.nuget.org/packages/Box.V2/5.2.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.2.0>](https://www.nuget.org/packages/Box.V2.Core/5.2.0>)
</Update>

<Update label="2023-03-08">
  ## Downloading ZIP Archives with Box API

  A recently released [guide](/guides/downloads/zip-archive) helps you to download large amount of data.
  Use Box API to [create](/reference/post-zip-downloads) and [download](/reference/get-zip-downloads-id-content) ZIP archives containing files, folders, or both.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-03-08">
  ## Box Python SDK v3.7.0 released

  ### New Features and Enhancements

  * Add new optional fields for `retention_policies` and `retention_policy_assignments` ([#803](https://github.com/box/box-python-sdk/issues/803)) ([`8b72f7e`](https://github.com/box/box-python-sdk/commit/8b72f7e992bce676723a40ac12bde06c8cca3bfb))
  * Use multiple threading for chunked upload ([#800](https://github.com/box/box-python-sdk/issues/800)) ([`506ce0d`](https://github.com/box/box-python-sdk/commit/506ce0d1e72ab4eeb6c5933a32c753e232a2f624))
</Update>

<Update label="2023-03-06">
  ## Box Java SDK v4.0.1 released

  ### Bug Fixes

  ### Bug Fixes

  * `OAUTH_SUFFIX` gets appended twice to `baseAuthorizationURL` ([#1148](https://github.com/box/box-java-sdk/issues/1148)) ([`3164770`](https://github.com/box/box-java-sdk/commit/3164770498e5115a43318640735317a896950f54)), closes [#1147](https://github.com/box/box-java-sdk/issues/1147)
  * Wrong progress reported to `ProgressListener` by `AbstractBoxMultipartRequest` ([#1151](https://github.com/box/box-java-sdk/issues/1151)) ([`947ded3`](https://github.com/box/box-java-sdk/commit/947ded394490fc840b8191bc7ad69ae0ea5f5c7d)), closes [#1149](https://github.com/box/box-java-sdk/issues/1149)
</Update>

<Update label="2023-03-03">
  ## Box CLI v3.8.0 released

  ### New Features and Enhancements

  * add alias for metadata cascade policy create ([#460](https://github.com/box/boxcli/issues/460)) ([`8d2f683`](https://github.com/box/boxcli/commit/8d2f683e092c036efe352e6fd70904083ad7c208))
  * Add support for `--reauthorize` flag in login command ([#457](https://github.com/box/boxcli/issues/457)) ([`f653a0d`](https://github.com/box/boxcli/commit/f653a0d526c7194f0a5e80dc837f0f16a9d4f27b))

  ### Bug Fixes

  * Fix `keychain` access by bumping `keychain` library to `1.4.0` ([#459](https://github.com/box/boxcli/issues/459)) ([`56919ce`](https://github.com/box/boxcli/commit/56919cefabef6de4d96a1f69f7c80740a680876c))
  * Fix unit tests ([#456](https://github.com/box/boxcli/issues/456)) ([`f89d9ef`](https://github.com/box/boxcli/commit/f89d9ef5c3c4e7bf00c0be40f128428b1e7e6983))
</Update>

<Update label="2023-02-24">
  ## Box iOS SDK v5.4.1 released

  ### Bug Fixes

  * Fix `listAssignments` and `assign` methods in `RetentionPolicyModule` ([#886](https://github.com/box/box-ios-sdk/issues/886)) ([`b668888`](https://github.com/box/box-ios-sdk/commit/b668888f35136dd1239526b70cc31a10bdd04744))
</Update>

<Update label="2023-02-24">
  ## Announcing End of Support for Android SDK on May 31st

  As of May 31, 2023 [Android SDK](https://github.com/box/box-android-sdk) will no longer be supported. You can still use your existing Android SDK applications with no impact, but you won't receive new features, updates, or bug fixes.
  If you would like to continue getting the latest and greatest Android features, we recommend using Java SDK to build apps on Android. Refer to [this](https://github.com/box/box-java-sdk/blob/main/doc/android.md) documentation for more details.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-02-23">
  ## Box Sign updates

  ## Multiple documents in one request

  The Box Sign [multiple documents](https://support.box.com/hc/en-us/sections/10302887198227-Multiple-documents-in-a-signature-request) in one request is now
  supported in our [public API](/reference/post-sign-requests).

  ## Signer attachments

  The [signer attachments](/reference/resources/sign-request#param-signers-inputs-content_type) feature allows users to request
  additional files from signers in a file attachment field.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-02-08">
  ## The Sample Code Catalog released

  We are happy to announce that [the Sample Code Catalog](https://developer.box.com/sample-code/) `v1.0.0`
  is now available on our Box Developer site. From now on you can browse
  code samples in various programming languages and filter them by category.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-02-07">
  ## Box Python SDK v3.6.2 released

  ### Bug Fixes

  * Retry `Connection broken` and `Connection reset` requests errors ([#794](https://github.com/box/box-python-sdk/issues/794)) ([`f1a0aa4`](https://github.com/box/box-python-sdk/commit/f1a0aa434369f06e80654a9f5c4b796100881aa6))
</Update>

<Update label="2023-01-19">
  ## Box CLI v3.7.0 released

  ### New Features and Enhancements

  * Add more flags for folder update collaborators ([#438](https://github.com/box/boxcli/issues/438)) ([`83ac6d7`](https://github.com/box/boxcli/commit/83ac6d7c8eeb7f3dc8562c8132cade4f5af80ee1))
  * Add support session termination ([#446](https://github.com/box/boxcli/issues/446)) ([`aef15a8`](https://github.com/box/boxcli/commit/aef15a8d2c7ee904db320d879deb6ebf0f934d22))

  ### Bug Fixes

  * Fix delete token cache from disk ([#445](https://github.com/box/boxcli/issues/445)) ([`aafb68a`](https://github.com/box/boxcli/commit/aafb68ae38a8280bd97cf978042a8df5b71b2f52))
  * Fix metadata template update when adding multiple options to enum ([#442](https://github.com/box/boxcli/issues/442)) ([`8779eec`](https://github.com/box/boxcli/commit/8779eecf24bda5b093bc891f5097879e1876b601))
  * single file upload on Node 16 ([#441](https://github.com/box/boxcli/issues/441)) ([`d94ab35`](https://github.com/box/boxcli/commit/d94ab35a38938daf4edbbd134774a3809facecbd))
</Update>

<Update label="2023-01-18">
  ## Box Java SDK v4.0.0 released

  The most important change this release includes is the replacement of the HTTP library from a native one to
  [OkHttp](https://square.github.io/okhttp/) which allows SDK to

  * Support the HTTP2 version of the HTTP protocol.
  * Support proxies that do not use only basic authentication method. For details on creating custom proxy authenticators and an example of
    [NTLM proxy authentication](https://github.com/box/box-java-sdk/blob/main/doc/configuration.md#example-ntlm-authenticator).

  ### Breaking Changes

  * `BatchAPIRequest` is no longer supported by the SDK
  * `BoxAPIConnection#DEFAULT_MAX_ATTEMPTS` is replaced with `BoxAPIConnection#DEFAULT_MAX_RETRIES`
  * `BoxRedirectResponse` was removed and will not be replaced
  * `BoxEvent.Type` is replaced with `EventType`
  * Removed deprecated methods from `BoxFile`, `BoxFileVersionRetention`, `BoxFolder`, `BoxGroup`, `BoxGroupMembership`,`BoxItem`, `BoxRetentionPolicy`, `BoxTask`, `BoxUser`, `BoxWebLink`, `EventLog`, `Metadata` and `MetadataTemplate`.

  Migration details can be found [here](https://github.com/box/box-java-sdk/blob/main/doc/upgrades/3.x.x%20to%204.x.x.md).

  ### New Features and Enhancements

  * Using `OkHttp` in Java SDK ([#1083](https://github.com/box/box-java-sdk/issues/1083)) ([`2656698`](https://github.com/box/box-java-sdk/commit/265669897100dd8f1757fc2c5f25665da42c2889))
</Update>

<Update label="2023-01-17">
  ## Box Windows SDK v5.1.0 released

  ### New Features and Enhancements

  * `BoxCCGAuth` add User and Admin clients factory methods without initial token ([#883](https://github.com/box/box-windows-sdk-v2/issues/883)) ([`c1337fc`](https://github.com/box/box-windows-sdk-v2/commit/c1337fc9d765bf7d4bc1757ea832bec92a602f76))

  - [https://www.nuget.org/packages/Box.V2/5.1.0>](https://www.nuget.org/packages/Box.V2/5.1.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.1.0>](https://www.nuget.org/packages/Box.V2.Core/5.1.0>)
</Update>

<Update label="2023-01-12">
  ## Box Windows SDK v5.0.0 released

  ### Breaking changes

  * upgrade .net framework to 4.6.2 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881))
  * remove deprecated methods ([#881](https://github.com/box/box-windows-sdk-v2/issues/881))
  * remove `use_index` references ([#881](https://github.com/box/box-windows-sdk-v2/issues/881))
  * return proper object from `GetFileVersionsUnderRetentionForAssignmentAsync`([#881](https://github.com/box/box-windows-sdk-v2/issues/881))

  ### New Features and Enhancements

  * upgrade .net framework to 4.6.2 ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#863](https://github.com/box/box-windows-sdk-v2/issues/863)
  * remove deprecated methods ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#874](https://github.com/box/box-windows-sdk-v2/issues/874)
  * remove `use_index` references ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#870](https://github.com/box/box-windows-sdk-v2/issues/870)

  ### Bug Fixes

  * Added pagination option to `IBoxFilesManager#ViewVersionsAsync` ([#869](https://github.com/box/box-windows-sdk-v2/issues/869)) ([`2324495`](https://github.com/box/box-windows-sdk-v2/commit/232449531440227a0c8b3489ceda813fe4f4a73f)), closes [#866](https://github.com/box/box-windows-sdk-v2/issues/866)
  * return proper object from `GetFileVersionsUnderRetentionForAssignmentAsync` ([#881](https://github.com/box/box-windows-sdk-v2/issues/881)) ([`f1989aa`](https://github.com/box/box-windows-sdk-v2/commit/f1989aa94cd085ad4bec04b4ebedb04f40455569)), closes [#875](https://github.com/box/box-windows-sdk-v2/issues/875)

  - [https://www.nuget.org/packages/Box.V2/5.0.0>](https://www.nuget.org/packages/Box.V2/5.0.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.0.0>](https://www.nuget.org/packages/Box.V2.Core/5.0.0>)
</Update>

<Update label="2023-01-11">
  ## Salesforce Toolkit - Flow Actions

  Salesforce toolkit includes wrappers that allow admins to invoke
  the [following methods](/guides/tooling/salesforce-toolkit/flow-actions). It allows Box for Salesforce users to
  build automated solutions, such as folder structure, using
  [Salesforce Flows](https://help.salesforce.com/s/articleView?id=sf.flow.htm\&type=5).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2023-01-09">
  ## Box Python SDK v3.6.1 released

  ### Bug Fixes

  * Retry CCG and JWT auth requests on connection reset error ([#790](https://github.com/box/box-python-sdk/issues/790)) ([`205997d`](https://github.com/box/box-python-sdk/commit/205997db9870395b9dd042854c4201338dcf925f)), closes [#789](https://github.com/box/box-python-sdk/issues/789)
</Update>

<Update label="2023-01-05">
  ## Box Node SDK v2.8.1 released

  ### Bug Fixes

  * Fix `getReadStream` delay reading ([#790](https://github.com/box/box-node-sdk/issues/790)) ([`6bfc1ee`](https://github.com/box/box-node-sdk/commit/6bfc1eebeb9a31606ff96127eeb1ad03d2f13d9c))
</Update>

<Update label="2023-01-04">
  ## Box Java SDK v3.8.2 released

  ### Bug Fixes

  * Fixed restoring state without refresh token. ([#1139](https://github.com/box/box-java-sdk/issues/1139)) ([`3544709`](https://github.com/box/box-java-sdk/commit/3544709480eb03e5bd50f5dc99be7409569304c4))
</Update>

<Update label="2023-01-03">
  ## Box Python SDK v3.6.0 released

  ### New Features and Enhancements

  * Add support marker in trash get items ([#781](https://github.com/box/box-python-sdk/issues/781)) ([`e2d1846`](https://github.com/box/box-python-sdk/commit/e2d1846818aeccfcba2a2f09a5cd924c9f6cd534))
  * Sanitize proxy credentials ([#782](https://github.com/box/box-python-sdk/issues/782)) ([`97fb5aa`](https://github.com/box/box-python-sdk/commit/97fb5aa2ed72008570abb327269ecec150632af9))

  ### Bug Fixes

  * Fix index error when getting an empty list of user term of service statuses ([#780](https://github.com/box/box-python-sdk/issues/780)) ([`23d763a`](https://github.com/box/box-python-sdk/commit/23d763ac4ba592131c43eb0319929db25d041c30))
  * Specify which exceptions should be retried ([#784](https://github.com/box/box-python-sdk/issues/784)) ([`833cd46`](https://github.com/box/box-python-sdk/commit/833cd46bafe774f19925f78600df90477bf07055))
</Update>


# 2024
Source: https://developer.box.com/changelog/2024

Box Platform changelog: API, SDK, and product updates from 2024.

<Update label="2024-12-30">
  ## Box TypeScript SDK Generated v1.10.0 released

  ### Bug Fixes

  * Remove unused parameter from `SignRequest` (box/box-openapi[#489](https://github.com/box/box-typescript-sdk-gen/issues/489)) ([#450](https://github.com/box/box-typescript-sdk-gen/issues/450)) ([`f5683b7`](https://github.com/box/box-typescript-sdk-gen/commit/f5683b703625dd8d504ca52100f692cb8440a474))

  ### New Features and Enhancements

  * Add support for replacing the network client implementation (box/box-codegen[#629](https://github.com/box/box-typescript-sdk-gen/issues/629)) ([#454](https://github.com/box/box-typescript-sdk-gen/issues/454)) ([`1cb7ddb`](https://github.com/box/box-typescript-sdk-gen/commit/1cb7ddb3ada79cebc27fbfce9df90cd8ebad353c))
  * Allow for customizing retry strategy (box/box-codegen[#635](https://github.com/box/box-typescript-sdk-gen/issues/635)) ([#457](https://github.com/box/box-typescript-sdk-gen/issues/457)) ([`530ca33`](https://github.com/box/box-typescript-sdk-gen/commit/530ca33ff3635581bd8ee91a82bc9f000b18812b))
  * Support webhook message validation (box/box-codegen[#631](https://github.com/box/box-typescript-sdk-gen/issues/631)) ([#455](https://github.com/box/box-typescript-sdk-gen/issues/455)) ([`09765a4`](https://github.com/box/box-typescript-sdk-gen/commit/09765a42fe25f15095bd1bd0d1377f2da222c9e4))
</Update>

<Update label="2024-12-30">
  ## Box Python SDK Generated v1.9.0 released

  ### Bug Fixes

  * Remove unused parameter from `SignRequest` (box/box-openapi[#489](https://github.com/box/box-python-sdk-gen/issues/489)) ([#411](https://github.com/box/box-python-sdk-gen/issues/411)) ([`578d9b4`](https://github.com/box/box-python-sdk-gen/commit/578d9b48da7e55d2e3e4736c871400dc90d826b1))

  ### New Features and Enhancements

  * Add `ai_agent` info to `AiResponse` (box/box-openapi[#485](https://github.com/box/box-python-sdk-gen/issues/485)) ([#402](https://github.com/box/box-python-sdk-gen/issues/402)) ([`351a5b8`](https://github.com/box/box-python-sdk-gen/commit/351a5b8dfbc8a0095bafbbf0245d8575217fc3c9))
  * Add support for replacing the network client implementation (box/box-codegen[#629](https://github.com/box/box-python-sdk-gen/issues/629)) ([#415](https://github.com/box/box-python-sdk-gen/issues/415)) ([`fb118dd`](https://github.com/box/box-python-sdk-gen/commit/fb118ddb1cbfb1d6a72e657bed57088fdff1ec02))
  * Allow for customizing retry strategy (box/box-codegen[#635](https://github.com/box/box-python-sdk-gen/issues/635)) ([#418](https://github.com/box/box-python-sdk-gen/issues/418)) ([`8dfb3ed`](https://github.com/box/box-python-sdk-gen/commit/8dfb3ed13196de37a78a53325079e284c7e921d5))
  * Support optional `userId` parameter for updating files, folders and web links (box/box-openapi[#488](https://github.com/box/box-python-sdk-gen/issues/488)) ([#406](https://github.com/box/box-python-sdk-gen/issues/406)) ([`d9cff4c`](https://github.com/box/box-python-sdk-gen/commit/d9cff4c6adc9c5cc9ce1edf73dffe8ac5979ce71))
  * Support webhook message validation (box/box-codegen[#631](https://github.com/box/box-python-sdk-gen/issues/631)) ([#416](https://github.com/box/box-python-sdk-gen/issues/416)) ([`0fec20b`](https://github.com/box/box-python-sdk-gen/commit/0fec20b281fe195f0dd6aaf8f164bdd414587fc4))
</Update>

<Update label="2024-12-10">
  ## Upcoming breaking change: Box AI API - Extract Structured

  We would like to announce a planned breaking change in the Box AI API - Extract Structured endpoint. This change will bring improvements to the response by introducing additional fields and nesting the metadata key-value pairs within the answer object. **This change is planned to be released mid-January**. Be sure to follow our [changelog](https://developer.box.com/changelog/) and announcements on our [Box Developer Blog](https://medium.com/box-developer-blog). Expand to see code snippets examples:

  Current response example:

  ```js theme={null}
  {
    "name": "Marie",
    "date": "10/2/23"
  }
  ```

  New response format example:

  ```js theme={null}
  {
    "answer": {
      "name": "Marie",
      "date": "10/2/23"
    },
    "completion_reason": "done",
    "created_at": "2012-12-12T10:53:43-08:00"
  }
  ```
</Update>

<Update label="2024-12-09">
  ## Box TypeScript SDK Generated v1.9.0 released

  ### Bug Fixes

  * Fix signature of `beforeRequest` method in `Interceptor` interface (box/box-codegen[#625](https://github.com/box/box-typescript-sdk-gen/issues/625)) ([#446](https://github.com/box/box-typescript-sdk-gen/issues/446)) ([`ef2e765`](https://github.com/box/box-typescript-sdk-gen/commit/ef2e7658cab705906325e40d6c7c6e96e5703201))

  ### New Features and Enhancements

  * Add `aiAgent` info to `AiResponse` (box/box-codegen[#624](https://github.com/box/box-typescript-sdk-gen/issues/624)) ([#440](https://github.com/box/box-typescript-sdk-gen/issues/440)) ([`24c2013`](https://github.com/box/box-typescript-sdk-gen/commit/24c20131b8275d43ecb02f3c94ac8e6116de3ea9))
  * Support optional `userId` parameter for updating files, folders and web links (box/box-openapi[#488](https://github.com/box/box-typescript-sdk-gen/issues/488)) ([#445](https://github.com/box/box-typescript-sdk-gen/issues/445)) ([`874f259`](https://github.com/box/box-typescript-sdk-gen/commit/874f259ce12e8440301ffb1b2b65a6765b87803f))
</Update>

<Update label="2024-12-05">
  ## CrowdStrike integration with Box

  CrowdStrike is an endpoint detection tool integrated with Box to monitor endpoint activity. This means, CrowdStrike monitors devices that connect to Box and your Box organization, analyzing data about the connection and the device to identify potential threat activity.

  The integration with CrowdStrike comes with additional [events in the event stream](/guides/events/enterprise-events/for-enterprise#event-types) that can be triggered for an enterprise.

  For example, the `EDR_CROWDSTRIKE_DEVICE_DETECTED` event is triggered when a new device is detected by the CrowdStrike Falcon platform.
  The full list includes the following events:

  * `EDR_CROWDSTRIKE_DEVICE_DETECTED`
  * `EDR_CROWDSTRIKE_NO_BOX_TOOLS`
  * `EDR_CROWDSTRIKE_BOX_TOOLS_OUTDATED`
  * `EDR_CROWDSTRIKE_DRIVE_OUTDATED`
  * `EDR_CROWDSTRIKE_ACCESS_ALLOWED_NO_CROWDSTRIKE_DEVICE`
  * `EDR_CROWDSTRIKE_ACCESS_REVOKED`

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-12-04">
  ## Box Dotnet SDK Generated v1.5.0 released

  ### Bug Fixes

  * Support status codes with no content (box/box-codegen[#604](https://github.com/box/box-dotnet-sdk-gen/issues/604)) ([#314](https://github.com/box/box-dotnet-sdk-gen/issues/314)) ([`57747d5`](https://github.com/box/box-dotnet-sdk-gen/commit/57747d50c48dd4c433dad342a5e2a20ac0b15952))
  * Update collaboration, metadata and collection resources (box/box-openapi[#483](https://github.com/box/box-dotnet-sdk-gen/issues/483)) ([#316](https://github.com/box/box-dotnet-sdk-gen/issues/316)) ([`d331f8a`](https://github.com/box/box-dotnet-sdk-gen/commit/d331f8a1f7110e5e00df170cedef85af682d58b4))

  ### New Features and Enhancements

  * Add optional URL parameter to `FetchResponse` (box/box-codegen[#617](https://github.com/box/box-dotnet-sdk-gen/issues/617)) ([#331](https://github.com/box/box-dotnet-sdk-gen/issues/331)) ([`61484ec`](https://github.com/box/box-dotnet-sdk-gen/commit/61484ec9fbf96c0ae62116ec1ee0cbb50aae7493))
  * Allow using default credentials for proxy (box/box-codegen[#623](https://github.com/box/box-dotnet-sdk-gen/issues/623)) ([#334](https://github.com/box/box-dotnet-sdk-gen/issues/334)) ([`bc4636e`](https://github.com/box/box-dotnet-sdk-gen/commit/bc4636e64859fd7d0b1449ec34b6144d0eb1a768)), closes [#333](https://github.com/box/box-dotnet-sdk-gen/issues/333)
  * Expose method for making custom HTTP requests (box/box-codegen[#622](https://github.com/box/box-dotnet-sdk-gen/issues/622)) ([#329](https://github.com/box/box-dotnet-sdk-gen/issues/329)) ([`e689140`](https://github.com/box/box-dotnet-sdk-gen/commit/e689140d6d3be772ff2370e7de5797707df7bdad))
  * Support get collection by ID endpoint (box/box-codegen[#595](https://github.com/box/box-dotnet-sdk-gen/issues/595)) ([#304](https://github.com/box/box-dotnet-sdk-gen/issues/304)) ([`9ebf59a`](https://github.com/box/box-dotnet-sdk-gen/commit/9ebf59ae388aa9aec5d8a0a3551f13e544c7571d))
</Update>

<Update label="2024-12-03">
  ## Box TypeScript SDK Generated v1.8.0 released

  ### Bug Fixes

  * Fix `additionalProperties` in `ClientError` (box/box-openapi[#477](https://github.com/box/box-typescript-sdk-gen/issues/477)) ([#385](https://github.com/box/box-typescript-sdk-gen/issues/385)) ([`4547148`](https://github.com/box/box-typescript-sdk-gen/commit/454714861019998b1fc6b7c44696b0178ffa022b))
  * Fix chunked uploads in browser (box/box-codegen[#619](https://github.com/box/box-typescript-sdk-gen/issues/619)) ([#436](https://github.com/box/box-typescript-sdk-gen/issues/436)) ([`0af2484`](https://github.com/box/box-typescript-sdk-gen/commit/0af2484dd8387cce1a8c235068ac3f834f8ecf42))
  * Support status codes with no content (box/box-codegen[#604](https://github.com/box/box-typescript-sdk-gen/issues/604)) ([#415](https://github.com/box/box-typescript-sdk-gen/issues/415)) ([`c3f14c6`](https://github.com/box/box-typescript-sdk-gen/commit/c3f14c6af55ab78ed5dc981909c67397b0d7219e))
  * Update client error schema to support schema errors (box/box-openapi[#467](https://github.com/box/box-typescript-sdk-gen/issues/467)) ([#381](https://github.com/box/box-typescript-sdk-gen/issues/381)) ([`b845f12`](https://github.com/box/box-typescript-sdk-gen/commit/b845f12d194d5f4e0cfd66db1db294e2f9a9bff8))
  * Update integration mapping response description (box/box-openapi[#463](https://github.com/box/box-typescript-sdk-gen/issues/463)) ([#379](https://github.com/box/box-typescript-sdk-gen/issues/379)) ([`e3d71e1`](https://github.com/box/box-typescript-sdk-gen/commit/e3d71e100500c5fa9e478b5228fd395f68242cf2))

  ### New Features and Enhancements

  * Add AI LLM endpoint AWS `params` (box/box-openapi[#478](https://github.com/box/box-typescript-sdk-gen/issues/478)) ([#388](https://github.com/box/box-typescript-sdk-gen/issues/388)) ([`d2fd1ec`](https://github.com/box/box-typescript-sdk-gen/commit/d2fd1ec4bddb19b353e286908c99477e08b90457))
  * Expose method for making custom HTTP requests, convert `FetchOptions` into a class (box/box-codegen[#610](https://github.com/box/box-typescript-sdk-gen/issues/610)) ([#431](https://github.com/box/box-typescript-sdk-gen/issues/431)) ([`9a9ea62`](https://github.com/box/box-typescript-sdk-gen/commit/9a9ea628fd21001437d92b32f1760d5ba14cb46b))
  * Support get collection by ID endpoint (box/box-codegen[#595](https://github.com/box/box-typescript-sdk-gen/issues/595)) ([#396](https://github.com/box/box-typescript-sdk-gen/issues/396)) ([`f1f47be`](https://github.com/box/box-typescript-sdk-gen/commit/f1f47bebfc0981a5e67f301b6fc2e3a8568d5845))
  * Support getting file download URL and file thumbnail URL (box/box-codegen[#617](https://github.com/box/box-typescript-sdk-gen/issues/617)) ([#435](https://github.com/box/box-typescript-sdk-gen/issues/435)) ([`1cb4d5d`](https://github.com/box/box-typescript-sdk-gen/commit/1cb4d5d93fbd94b952b876457008973a92d5aa23))
  * Support `nullable` fields in TypeScript (box/box-codegen[#612](https://github.com/box/box-typescript-sdk-gen/issues/612)) ([#425](https://github.com/box/box-typescript-sdk-gen/issues/425)) ([`991dc29`](https://github.com/box/box-typescript-sdk-gen/commit/991dc29bc805bf0c5198277142efb9a85de1dd42))
</Update>

<Update label="2024-12-02">
  ## Box Python SDK Generated v1.8.0 released

  ### Bug Fixes

  * Fix enums usage (box/box-codegen[#615](https://github.com/box/box-python-sdk-gen/issues/615)) ([#387](https://github.com/box/box-python-sdk-gen/issues/387)) ([`a9abccb`](https://github.com/box/box-python-sdk-gen/commit/a9abccb8e552c971774ea1a9fa2096395a40317b)), closes [#385](https://github.com/box/box-python-sdk-gen/issues/385)
  * Support status codes with no content (box/box-codegen[#604](https://github.com/box/box-python-sdk-gen/issues/604)) ([#378](https://github.com/box/box-python-sdk-gen/issues/378)) ([`051716c`](https://github.com/box/box-python-sdk-gen/commit/051716c84b4f0ab32b82608f94e3cf3ba09b390b))
  * Update collaboration, metadata and collection resources (box/box-openapi[#483](https://github.com/box/box-python-sdk-gen/issues/483)) ([#380](https://github.com/box/box-python-sdk-gen/issues/380)) ([`0d45fed`](https://github.com/box/box-python-sdk-gen/commit/0d45fedc0b7b96234ef3901f412f259b1cae4c1a))

  ### New Features and Enhancements

  * Expose method for making custom HTTP requests (box/box-codegen[#610](https://github.com/box/box-python-sdk-gen/issues/610)) ([#393](https://github.com/box/box-python-sdk-gen/issues/393)) ([`55a23d9`](https://github.com/box/box-python-sdk-gen/commit/55a23d9d6840642c248ab3b967ad5c2635484c8c))
  * Support getting file download URL and file thumbnail URL (box/box-codegen[#617](https://github.com/box/box-python-sdk-gen/issues/617)) ([#397](https://github.com/box/box-python-sdk-gen/issues/397)) ([`fd609ab`](https://github.com/box/box-python-sdk-gen/commit/fd609ab9fe94da43b1a71815597c49471e157bb8))
</Update>

<Update label="2024-11-29">
  ## Box Java SDK v4.13.1 released

  ### Bug Fixes

  * Correctly calculate `Content-Length` when reading from a stream ([#1277](https://github.com/box/box-java-sdk/issues/1277)) ([`b1d5371`](https://github.com/box/box-java-sdk/commit/b1d5371491abe1729a95eb9dc39d375135c8681d))
</Update>

<Update label="2024-11-12">
  ## Apps & Integrations naming convention changes

  We are changing the naming convention for apps & integrations to improve the clarity and consistency of our platform.

  ## Developers

  | Current name | Target name | Location |
  | - | - | - |
  | App Center | Publishing | A tab for submitting platform apps for publication in Box Integrations catalog |
  | Integrations | Box Web Integrations | A tab where you define the third-party application buttons within the Box Web app |
  | Custom apps | Platform apps | Developer Console |

  ## Admins

  | Current name | Target name | Location |
  | - | - | - |
  | Apps | Integrations | Admin Console |
  | Custom Apps Manager | Platform Apps Manager | Admin Console |
  | Custom apps | Platform Apps | Admin Console |

  ## Box Shield

  | Current name | Target name | Location |
  | - | - | - |
  | Application restriction policy | Integration restriction | Restriction policies |
  | Shield Application | Shield Integration | Shield integration lists |
  | Applications | Integrations | Detection Rules |

  ## Users

  | Current name | Target name | Location |
  | - | - | - |
  | Apps | Integrations | A tab in the Box web-app. |

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-11-04">
  ## Box Python SDK Generated v1.7.0 released

  ### New Features and Enhancements

  * Support get collection by ID endpoint (box/box-codegen[#595](https://github.com/box/box-codegen/issues/595)) ([#366](https://github.com/box/box-codegen/issues/366)) ([`1db5722`](https://github.com/box/box-codegen/commit/1db5722f7d02694739f1a52a6b2ebe0c406960b0)), closes [#355](https://github.com/box/box-codegen/issues/355)
</Update>

<Update label="2024-10-31">
  ## Box Dotnet SDK Generated v1.4.0 released

  ### Bug Fixes

  * Change `QueryParams` type in `MetadataQuery` from `Dictionary<string, string>` to `Dictionary<string, object>` (box/box-openapi[#479](https://github.com/box/box-codegen/issues/479)) ([#298](https://github.com/box/box-codegen/issues/298)) ([`656b495`](https://github.com/box/box-codegen/commit/656b495bea779879bb82b2cda0cca5a30a8ad8ca))
  * Fix conversion to `RSAKey` (box/box-codegen[#591](https://github.com/box/box-codegen/issues/591)) ([#297](https://github.com/box/box-codegen/issues/297)) ([`068b1f7`](https://github.com/box/box-codegen/commit/068b1f7b3ea3c62647e03e0e17176bde049949db))

  ### New Features and Enhancements

  * add AI LLM endpoint AWS `params`. Change the type from `AiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi` to `AiLlmEndpointParamsAwsOrAiLlmEndpointParamsGoogleOrAiLlmEndpointParamsOpenAi` (box/box-openapi[#478](https://github.com/box/box-codegen/issues/478)) ([#291](https://github.com/box/box-codegen/issues/291)) ([`dcb8a20`](https://github.com/box/box-codegen/commit/dcb8a201577be08b644266c157db45cd6797c71c))
</Update>

<Update label="2024-10-30">
  ## Box Python SDK Generated v1.6.0 released

  ### Bug Fixes

  * Set stream position to 0 for multipart requests (box/box-codegen[#581](https://github.com/box/box-codegen/issues/581)) ([#348](https://github.com/box/box-codegen/issues/348)) ([`fa6942c`](https://github.com/box/box-codegen/commit/fa6942c231024947250955ccc52f352744ab5f38))
  * Update client error schema (box/box-openapi[#467](https://github.com/box/box-codegen/issues/467)) ([#347](https://github.com/box/box-codegen/issues/347)) ([`a42a253`](https://github.com/box/box-codegen/commit/a42a2532337c79d20b6524fda0acf717d9ccbd5f))
  * Use original stream position when retrying requests (box/box-codegen[#583](https://github.com/box/box-codegen/issues/583)) ([#358](https://github.com/box/box-codegen/issues/358)) ([`060b4dc`](https://github.com/box/box-codegen/commit/060b4dc2b8bbbc1e17cce0fc049394e0527952b7))
  * use raw `docstrings` when comments contain backslash (box/box-codegen[#571](https://github.com/box/box-codegen/issues/571)) ([#330](https://github.com/box/box-codegen/issues/330)) ([`8dd8cb7`](https://github.com/box/box-codegen/commit/8dd8cb71105c200bd03f5f894a4dbfb42baf0865))

  ### New Features and Enhancements

  * Add `download_file_to_output_stream` method to `DownloadsManager` (box/box-codegen[#575](https://github.com/box/box-codegen/issues/575)) ([#334](https://github.com/box/box-codegen/issues/334)) ([`6820d08`](https://github.com/box/box-codegen/commit/6820d08f37c5c0605a580391bef2dc4f2a384c00))
  * add AI LLM endpoint AWS `params` (box/box-openapi[#478](https://github.com/box/box-codegen/issues/478)) ([#354](https://github.com/box/box-codegen/issues/354)) ([`c8fa2c1`](https://github.com/box/box-codegen/commit/c8fa2c1131154d07a500290db6a7b34b06005c2b))
</Update>

<Update label="2024-10-24">
  ## Box Dotnet SDK Generated v1.3.1 released

  ### Bug Fixes

  * properly serialize `StringEnum` list when inside query `params` ([#288](https://github.com/box/box-codegen/issues/288)) ([`dac8392`](https://github.com/box/box-codegen/commit/dac839280b43f4bd954d3966032ff4925150c061))
  * update client error schema to support schema errors (box/box-openapi[#467](https://github.com/box/box-codegen/issues/467)) ([#281](https://github.com/box/box-codegen/issues/281)) ([`bef2632`](https://github.com/box/box-codegen/commit/bef2632af99f0477bd009bcb91248c678b4e1bab))
  * update integration mapping response description (box/box-openapi[#463](https://github.com/box/box-codegen/issues/463)) ([#279](https://github.com/box/box-codegen/issues/279)) ([`05e07b0`](https://github.com/box/box-codegen/commit/05e07b025c234de4c4161e567c0919748d24f804))
</Update>

<Update label="2024-10-24">
  ## Box AI API - AWS AI models now available

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with the following AWS models:

  * AWS Claude 3 Sonnet
  * AWS Claude 3.5 Sonnet
  * AWS Claude 3 Haiku
  * AWS Titan Text Lite

  Models offered in **Preview** mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-models) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-10-22">
  ## Box AI API — Document Q\&A and Box AI API — Text Generation generally available

  We are excited to announce that [Box AI API — Document Q\&A](/guides/box-ai/ai-tutorials/ask-questions/) and [Box AI API — Text Generation](/guides/box-ai/ai-tutorials/generate-text/) features are now available to all **Enterprise Plus** customers.

  [Box AI API](https://developer.box.com/guides/box-ai) allows you to use Box AI functionality in your custom applications. For example, you can implement Box AI question and answer functionality in your third party applications,or generate content right in your product’s content editor. You can also extract metadata from the provided documents.

  *Endpoints related to metadata extraction are currently a beta feature offered subject to Box’s Main Beta Agreement, and the available capabilities may change.*

  Currently, Box AI functionality allows you to:

  * Get responses to your questions.
  * Get a summary of a document.
  * Generate text you can use in your documents.
  * Extract metadata from the provided file in a flexible way, meaning you have more freedom when using the prompt.
  * Extract metadata from the provided file using a [metadata template](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or the `fields` structure.
  * Fetch and override the default API model configuration.

  Check the [Box AI API developer guides](https://developer.box.com/guides/box-ai) to learn more about Box AI and check the [API Reference](/reference/post-ai-ask) for Box AI API details.

  ## Box AI for UI Elements

  [Box AI for UI Elements](/guides/embed/ui-elements/preview#box-ai-ui-element) enhances [Content Preview](/guides/embed/ui-elements/preview) with Box AI - Document Q\&A and Text Generation functionality.
  The enhanced Box AI for UI Elements allows the users to embed AI functionality in their custom applications to facilitate answering questions, summarizing a document, adding citations and using dialogue history, and formatting support.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-10-21">
  ## Box UI Elements v22.0.0 released

  ### [22.0.0](https://github.com/box/box-ui-elements/compare/v21.0.0...v22.0.0) (2024-10-21)

  ### Bug Fixes

  * resolve missing exports for `esbuild` ([#3719](https://github.com/box/box-ui-elements/issues/3719)) ([`495f19e`](https://github.com/box/box-ui-elements/commit/495f19e20c8e3d6b7ab9fe8b6f5c3f833d1c5c46))
  * **content-answers:** Bump content-answers ([#3713](https://github.com/box/box-ui-elements/issues/3713)) ([`21c2de1`](https://github.com/box/box-ui-elements/commit/21c2de1b3e64ff4766c36ed18a1e720ff79ae5b6))
  * **content-uploader:** resolve `ItemAction` issues ([#3631](https://github.com/box/box-ui-elements/issues/3631)) ([`ba299b1`](https://github.com/box/box-ui-elements/commit/ba299b1dcee18d3197e5f7df0f15823070a071cb))
  * **docgen-sidebar:** add collapsible component to hide nested tags ([#3626](https://github.com/box/box-ui-elements/issues/3626)) ([`3480efb`](https://github.com/box/box-ui-elements/commit/3480efb5a03ee73f4d78a5b26f626f059aa31115))
  * **draft-js:** Upgraded to 0.11.7 ([#3580](https://github.com/box/box-ui-elements/issues/3580)) ([`179ff9f`](https://github.com/box/box-ui-elements/commit/179ff9f718845500ddc76a56e06129e06b386886))
  * **hubs:** fix shared link text ([#3657](https://github.com/box/box-ui-elements/issues/3657)) ([`a938524`](https://github.com/box/box-ui-elements/commit/a9385240dc53a9efe5277956a2d81ec1c253716a))
  * **i18n:** update translations ([#3603](https://github.com/box/box-ui-elements/issues/3603)) ([`a467823`](https://github.com/box/box-ui-elements/commit/a4678232af14c2220ce8c7125a55bb6714781b7a))
  * **i18n:** update translations ([#3607](https://github.com/box/box-ui-elements/issues/3607)) ([`8ad18b8`](https://github.com/box/box-ui-elements/commit/8ad18b8b7887c07189dee590ebc0a931fa5010e8))
  * **i18n:** update translations ([#3612](https://github.com/box/box-ui-elements/issues/3612)) ([`4bfceaa`](https://github.com/box/box-ui-elements/commit/4bfceaaf71ed4271ba62d6878ef714617a920c8c))
  * **i18n:** update translations ([#3615](https://github.com/box/box-ui-elements/issues/3615)) ([`945fa23`](https://github.com/box/box-ui-elements/commit/945fa23a8ba08bebf3bb4415e2b1827377eecbbd))
  * **i18n:** update translations ([#3619](https://github.com/box/box-ui-elements/issues/3619)) ([`bc011eb`](https://github.com/box/box-ui-elements/commit/bc011eb1369fc36762cfa3d7a206a538400d536d))
  * **i18n:** update translations ([#3620](https://github.com/box/box-ui-elements/issues/3620)) ([`62a9ef7`](https://github.com/box/box-ui-elements/commit/62a9ef7489e42d3cafa8edfabcddf57928ae514d))
  * **i18n:** update translations ([#3627](https://github.com/box/box-ui-elements/issues/3627)) ([`ae5cc3d`](https://github.com/box/box-ui-elements/commit/ae5cc3d0b0f0b2afacb37048f994b39867d9006a))
  * **i18n:** update translations ([#3633](https://github.com/box/box-ui-elements/issues/3633)) ([`13894ca`](https://github.com/box/box-ui-elements/commit/13894caaf44775d80d54b4458a997160be359ed1))
  * **i18n:** update translations ([#3636](https://github.com/box/box-ui-elements/issues/3636)) ([`0bee28b`](https://github.com/box/box-ui-elements/commit/0bee28b6208179a1f0d2ce2428a5200be199302f))
  * **i18n:** update translations ([#3639](https://github.com/box/box-ui-elements/issues/3639)) ([`83b403c`](https://github.com/box/box-ui-elements/commit/83b403cecc8dcdc210b31cf84fb59461f3325c8e))
  * **i18n:** update translations ([#3643](https://github.com/box/box-ui-elements/issues/3643)) ([`4cf5b3d`](https://github.com/box/box-ui-elements/commit/4cf5b3d55042274e8d73c8a9f1998ceed791179a))
  * **i18n:** update translations ([#3648](https://github.com/box/box-ui-elements/issues/3648)) ([`297fabf`](https://github.com/box/box-ui-elements/commit/297fabfe2ab8207ccdcb6e97057a4fb2f3022284))
  * **i18n:** update translations ([#3653](https://github.com/box/box-ui-elements/issues/3653)) ([`7b0e0fb`](https://github.com/box/box-ui-elements/commit/7b0e0fb44e3d205d28a10d8bc851ebaecaf5222f))
  * **i18n:** update translations ([#3659](https://github.com/box/box-ui-elements/issues/3659)) ([`41a17fe`](https://github.com/box/box-ui-elements/commit/41a17fe815b9ab7da9403836276de3fca379e86f))
  * **i18n:** update translations ([#3667](https://github.com/box/box-ui-elements/issues/3667)) ([`1f77bce`](https://github.com/box/box-ui-elements/commit/1f77bce4f470988d818ce7128954e1cd964d4f7f))
  * **i18n:** update translations ([#3673](https://github.com/box/box-ui-elements/issues/3673)) ([`7e5f7c1`](https://github.com/box/box-ui-elements/commit/7e5f7c1af0a05c35097827af5a55d5edd3470872))
  * **i18n:** update translations ([#3674](https://github.com/box/box-ui-elements/issues/3674)) ([`ebe8348`](https://github.com/box/box-ui-elements/commit/ebe8348b9cf0a79298ea102f27217b6cd10b631f))
  * **i18n:** update translations ([#3679](https://github.com/box/box-ui-elements/issues/3679)) ([`4bf65f8`](https://github.com/box/box-ui-elements/commit/4bf65f8b1c8ed6080a340bb28097d6f04d08ecc0))
  * **i18n:** update translations ([#3683](https://github.com/box/box-ui-elements/issues/3683)) ([`549188a`](https://github.com/box/box-ui-elements/commit/549188a9f005b8dd0f63c0ed4906e8a64144c3a4))
  * **i18n:** update translations ([#3686](https://github.com/box/box-ui-elements/issues/3686)) ([`9927e53`](https://github.com/box/box-ui-elements/commit/9927e53f47e54380d0f2e44e857fbd6b0a6528fd))
  * **i18n:** update translations ([#3689](https://github.com/box/box-ui-elements/issues/3689)) ([`47e7a6b`](https://github.com/box/box-ui-elements/commit/47e7a6be3036280bf89220f65ed978b3ef0bc2c7))
  * **i18n:** update translations ([#3692](https://github.com/box/box-ui-elements/issues/3692)) ([`d2e59c8`](https://github.com/box/box-ui-elements/commit/d2e59c846c3d72ab9efbe59f1123c72745945aa7))
  * **i18n:** update translations ([#3694](https://github.com/box/box-ui-elements/issues/3694)) ([`1850977`](https://github.com/box/box-ui-elements/commit/1850977829e4888139462a6f65794b1cffc52a08))
  * **i18n:** update translations ([#3697](https://github.com/box/box-ui-elements/issues/3697)) ([`665aedf`](https://github.com/box/box-ui-elements/commit/665aedff1834ffbc4bc1e903262b0d4e0bef2cc3))
  * **i18n:** update translations ([#3701](https://github.com/box/box-ui-elements/issues/3701)) ([`fe9f7cc`](https://github.com/box/box-ui-elements/commit/fe9f7cca9b100afe1521df41c697ed6f0f621f66))
  * **i18n:** update translations ([#3705](https://github.com/box/box-ui-elements/issues/3705)) ([`fa89f87`](https://github.com/box/box-ui-elements/commit/fa89f876d54680b95bdc2fd3eb0d07a3c729f03e))
  * **i18n:** update translations ([#3711](https://github.com/box/box-ui-elements/issues/3711)) ([`b6b61bf`](https://github.com/box/box-ui-elements/commit/b6b61bf47429541b1cbb1091fd94024c4ceeb6c8))
  * **metadata-instance-editor:** Fix support link ([#3671](https://github.com/box/box-ui-elements/issues/3671)) ([`b82687e`](https://github.com/box/box-ui-elements/commit/b82687e5cc0a55b6f82eb2c9aa1ea7b3482263b4))
  * **metadata-sidebar:** fix loading states ([#3684](https://github.com/box/box-ui-elements/issues/3684)) ([`5c54eb5`](https://github.com/box/box-ui-elements/commit/5c54eb51287b1273ad84145952be132b84ef9e04))
  * **metadata-sidebar:** Fix metadata sidebar AI capabilities ([#3681](https://github.com/box/box-ui-elements/issues/3681)) ([`fd164ec`](https://github.com/box/box-ui-elements/commit/fd164ec57c58ac912bdb4edbe4f9cdc30296b11a))
  * **metadata-sidebar:** Fix storybook tests ([#3695](https://github.com/box/box-ui-elements/issues/3695)) ([`8326472`](https://github.com/box/box-ui-elements/commit/83264724fa9de3e0935cc6f5762362dadcca884f))
  * **metadata-sidebar:** handle `onCancel` action for editing templates ([#3669](https://github.com/box/box-ui-elements/issues/3669)) ([`6ad083b`](https://github.com/box/box-ui-elements/commit/6ad083b4d14a721973df5ef3959913772c481922))
  * **metadata-sidebar:** `UnsavedChangesModal` changes ([#3691](https://github.com/box/box-ui-elements/issues/3691)) ([`305d3af`](https://github.com/box/box-ui-elements/commit/305d3af23a162db91e16ce13cc8c0bced865500d))
  * **notification:** unblock UI beneath Notification ([#3661](https://github.com/box/box-ui-elements/issues/3661)) ([`33b34d9`](https://github.com/box/box-ui-elements/commit/33b34d9c532501824ed45c8965f82df690bb6e5c))
  * **quick-search:** Quick Search buttons and footer navigation ([#3623](https://github.com/box/box-ui-elements/issues/3623)) ([`0427112`](https://github.com/box/box-ui-elements/commit/04271125b0beedaae80f3ec48273ca5fdf266ac7))
  * **quick-search:** Quick Search Navigation ([#3622](https://github.com/box/box-ui-elements/issues/3622)) ([`b814223`](https://github.com/box/box-ui-elements/commit/b8142235903cd8ee5d36ee9121437b01552a5597))
  * clean up eslint and configs ([#3584](https://github.com/box/box-ui-elements/issues/3584)) ([`c0ff8d7`](https://github.com/box/box-ui-elements/commit/c0ff8d7d7b24a919fc440a8f06f74b26fb0f5fa1)), closes [#3583](https://github.com/box/box-ui-elements/issues/3583)
  * resolve changes from `box/frontend` ([#3590](https://github.com/box/box-ui-elements/issues/3590)) ([`1d91171`](https://github.com/box/box-ui-elements/commit/1d9117162d658215fc9b62bbbfa0d351349901ff))
  * **quick-search:** Quick filter navigation ([#3582](https://github.com/box/box-ui-elements/issues/3582)) ([`6880f67`](https://github.com/box/box-ui-elements/commit/6880f67d6005f549ca7c2fbc5d9c395f25cf7128))
  * upgrade react-popper ([#3583](https://github.com/box/box-ui-elements/issues/3583)) ([`13396e4`](https://github.com/box/box-ui-elements/commit/13396e4f9f06c30b542fa5846659539f00edc392))

  ### Features

  * **taxonomy:** added view/create/updated taxonomy field support ([#3716](https://github.com/box/box-ui-elements/issues/3716)) ([`cccb0b0`](https://github.com/box/box-ui-elements/commit/cccb0b084a52838eb9f7e16c084507ef30ba30e1))
  * `noop` for BREAKING CHANGE blueprint peer dependency ([#3721](https://github.com/box/box-ui-elements/issues/3721)) ([`5a117ae`](https://github.com/box/box-ui-elements/commit/5a117ae1f4e887365b65d07dd0b8a3f00ebf45db))
  * **api:** add handling empty metadata suggestions ([#3608](https://github.com/box/box-ui-elements/issues/3608)) ([`ecd4c80`](https://github.com/box/box-ui-elements/commit/ecd4c80873ae0d447fd5dbfdcf622775eeeb206e))
  * **api:** Extend `getMetadata` in Metadata API ([#3611](https://github.com/box/box-ui-elements/issues/3611)) ([`765f592`](https://github.com/box/box-ui-elements/commit/765f592647c41bb1e2bd48ea32dd7b7e1ba2f305))
  * **blueprint:** Added blueprint ([#3585](https://github.com/box/box-ui-elements/issues/3585)) ([`0f2d876`](https://github.com/box/box-ui-elements/commit/0f2d87617838dc2af7c702c91dbc4321d7b31bf5))
  * **boxai-sidebar:** `BoxAISidebar` header added ([#3698](https://github.com/box/box-ui-elements/issues/3698)) ([`130b6b6`](https://github.com/box/box-ui-elements/commit/130b6b69c45a0b8e4a22009e3e9f44fb285e45e1))
  * **boxai-sidebar:** Empty Sidebar for Box AI ([#3668](https://github.com/box/box-ui-elements/issues/3668)) ([`611377c`](https://github.com/box/box-ui-elements/commit/611377ce21b3ed7a804c82eb2c29189851861dc2))
  * **content-answers:** Upgrade Content Answers ([#3658](https://github.com/box/box-ui-elements/issues/3658)) ([`002d496`](https://github.com/box/box-ui-elements/commit/002d4966fa2158c33371d9a218a41206e1462f6b)), closes [#3626](https://github.com/box/box-ui-elements/issues/3626)
  * **content-explorer-modal-container:** add optional info notice ([#3634](https://github.com/box/box-ui-elements/issues/3634)) ([`20d4c3f`](https://github.com/box/box-ui-elements/commit/20d4c3f3ca981820bf3684afe4ee68775b4b30bd))
  * **content-sidebar:** add archived date to content preview sidebar ([#3625](https://github.com/box/box-ui-elements/issues/3625)) ([`10e68f3`](https://github.com/box/box-ui-elements/commit/10e68f301183244062b6613006a5aa0cbdd33526))
  * **content-sidebar:** Add data-target-id to menu items ([#3610](https://github.com/box/box-ui-elements/issues/3610)) ([`cf05167`](https://github.com/box/box-ui-elements/commit/cf05167884084a199512a1d18d41cc9fde7a4fc7))
  * **content-sidebar:** Add placeholder `metadatasidebar` redesigned ([#3570](https://github.com/box/box-ui-elements/issues/3570)) ([`6a0d7ee`](https://github.com/box/box-ui-elements/commit/6a0d7ee0857d9c91719654e2ac387a6e7dc135b9))
  * **content-sidebar:** disable version modifications for archive file ([#3637](https://github.com/box/box-ui-elements/issues/3637)) ([`e735c4c`](https://github.com/box/box-ui-elements/commit/e735c4c3f5b755f3a773d2e7f185cd9a961de3cd))
  * **content-sidebar:** pass `metadata.aiSuggestions` flag into redesigned sidebar ([#3665](https://github.com/box/box-ui-elements/issues/3665)) ([`b672f70`](https://github.com/box/box-ui-elements/commit/b672f7059697e922d2ae193ef6a98217695c843d))
  * **metadata-sidebar:** Add handler for `Autofill` button ([#3700](https://github.com/box/box-ui-elements/issues/3700)) ([`95735e0`](https://github.com/box/box-ui-elements/commit/95735e0291f233d173c17a19304119c83e51723d))
  * **metadata-sidebar:** Add metadata instance list ([#3664](https://github.com/box/box-ui-elements/issues/3664)) ([`b4e4b01`](https://github.com/box/box-ui-elements/commit/b4e4b01fefea753d21a4aa75dccde92fce05af21)), closes [#3605](https://github.com/box/box-ui-elements/issues/3605)
  * **metadata-sidebar:** disable delete button ([#3677](https://github.com/box/box-ui-elements/issues/3677)) ([`2941a97`](https://github.com/box/box-ui-elements/commit/2941a9732b5081872bfcd0c2fe490ab14c6dc2ed))
  * **metadata-sidebar:** Handle create metadata instance ([#3663](https://github.com/box/box-ui-elements/issues/3663)) ([`321ba7e`](https://github.com/box/box-ui-elements/commit/321ba7e715d51b269ad7bc566b197d0cab52b699))
  * **metadata-sidebar:** handle delete metadata instance ([#3662](https://github.com/box/box-ui-elements/issues/3662)) ([`f6abd4e`](https://github.com/box/box-ui-elements/commit/f6abd4e07d8d23b0a0fe5224b4ba2f6b4c44f4e7))
  * **metadata-sidebar:** handle update metadata instance ([#3672](https://github.com/box/box-ui-elements/issues/3672)) ([`ef79e44`](https://github.com/box/box-ui-elements/commit/ef79e44d81eb875eec04233e48485f1c6326606d))
  * **metadata-sidebar:** Metadata sidebar redesign ([#3654](https://github.com/box/box-ui-elements/issues/3654)) ([`fe4fede`](https://github.com/box/box-ui-elements/commit/fe4fededd993c4025b1b6f38cc8a6387af1a9acc)), closes [#3606](https://github.com/box/box-ui-elements/issues/3606)
  * **metadata-sidebar:** pass `areAiSuggestionsAvailable` based on file ext ([#3675](https://github.com/box/box-ui-elements/issues/3675)) ([`dc074cf`](https://github.com/box/box-ui-elements/commit/dc074cf3f189a9ce06b7854d7245242732c1a294))
  * **metadata-sidebar:** tab content styles change ([#3708](https://github.com/box/box-ui-elements/issues/3708)) ([`f7c06a4`](https://github.com/box/box-ui-elements/commit/f7c06a4c411b453df9a1617d50fdddf77b032db7))
  * **taxonomy:** added metadata options endpoint ([#3678](https://github.com/box/box-ui-elements/issues/3678)) ([`47ba331`](https://github.com/box/box-ui-elements/commit/47ba331ca562c152c49cccf2c090664177e1370d))
  * **taxonomy:** added metadata taxonomy field support ([#3710](https://github.com/box/box-ui-elements/issues/3710)) ([`3a0c27e`](https://github.com/box/box-ui-elements/commit/3a0c27ea1cfbb22c6fd9090f7bd237e62f8536b6))
  * **uaa-logging:** Log UAA Parity data ([#3629](https://github.com/box/box-ui-elements/issues/3629)) ([`6cb5d8f`](https://github.com/box/box-ui-elements/commit/6cb5d8f1d972b40ec06ce08f39cb25aa1452ad10))
  * **unified-share-modal:** add custom avatars click handler ([#3688](https://github.com/box/box-ui-elements/issues/3688)) ([`c034de4`](https://github.com/box/box-ui-elements/commit/c034de4daec6881c08b05caa1033db91382af6e0))
  * **update\_app\_activity\_item:** Add permissions field ([#3680](https://github.com/box/box-ui-elements/issues/3680)) ([`c521c11`](https://github.com/box/box-ui-elements/commit/c521c113dafdc5787f7c4c163d3cbaa01a523c3b))
  * support `/2.0/ai/extract_structured` endpoint ([#3596](https://github.com/box/box-ui-elements/issues/3596)) ([`dee4eee`](https://github.com/box/box-ui-elements/commit/dee4eee4ff49d7e8e9bc69071ac23164ae180e4e))
  * **unified-share-modal:** added targeting attribute ([#3592](https://github.com/box/box-ui-elements/issues/3592)) ([`e26f1f1`](https://github.com/box/box-ui-elements/commit/e26f1f10731769ad7ed3cc94bdf6ab97117719d7))
  * support metadata suggestions API ([#3571](https://github.com/box/box-ui-elements/issues/3571)) ([`c985402`](https://github.com/box/box-ui-elements/commit/c9854024dec37927cfabdef37c4f8fe82ffb8d34)), closes [#3565](https://github.com/box/box-ui-elements/issues/3565)

  ### Performance Improvements

  * **content-answers:** lazy load content answers in preview ([#3720](https://github.com/box/box-ui-elements/issues/3720)) ([`ec115f7`](https://github.com/box/box-ui-elements/commit/ec115f749fea1c545663888c8d2cfc0bd3cfa514))

  ### Reverts

  * **content-explorer:** Revert rename dialog ([#3704](https://github.com/box/box-ui-elements/issues/3704)) ([`13b8c99`](https://github.com/box/box-ui-elements/commit/13b8c990bc5fb8528e3a79864f8f9579608febd1)), closes [#3666](https://github.com/box/box-ui-elements/issues/3666)

  ### BREAKING CHANGES

  * blueprint-web and blueprint-web-assets peer dependencies
</Update>

<Update label="2024-10-18">
  ## Box Java SDK v4.12.0 released

  ### New Features and Enhancements

  * Support AI Agent ([#1265](https://github.com/box/box-java-sdk/issues/1265)) ([`3cb2c7c`](https://github.com/box/box-java-sdk/commit/3cb2c7c275761a24be9403a6a2b41d0725ba8d9b))
  * Support AI extract and AI extract structured ([#1266](https://github.com/box/box-java-sdk/issues/1266)) ([`7ba90b9`](https://github.com/box/box-java-sdk/commit/7ba90b96070a32b3e2ac60e5c55bd04d0a5973c0))
</Update>

<Update label="2024-10-17">
  ## Box TypeScript SDK Generated v1.7.0 released

  ### New Features and Enhancements

  * Include raw data in response object (box/box-codegen[#576](https://github.com/box/box-typescript-sdk-gen/issues/576)) ([#375](https://github.com/box/box-typescript-sdk-gen/issues/375)) ([`bdb9d0c`](https://github.com/box/box-typescript-sdk-gen/commit/bdb9d0caab1a54ca56aef5de4260215d1d3fbd35))
  * Support `ai/extract` and `ai/extract_structured` endpoints (box/box-codegen[#566](https://github.com/box/box-typescript-sdk-gen/issues/566)) ([#356](https://github.com/box/box-typescript-sdk-gen/issues/356)) ([`4a33562`](https://github.com/box/box-typescript-sdk-gen/commit/4a335621c7eaa413162a5daa65d63d8353ba37f5))
</Update>

<Update label="2024-10-17">
  ## Box Dotnet SDK Generated v1.3.0 released

  ### Bug Fixes

  * bump `system.text.json` to 8.0.5 (box/box-codegen[#578](https://github.com/box/box-codegen/issues/578)) ([#271](https://github.com/box/box-codegen/issues/271)) ([`dad2f52`](https://github.com/box/box-codegen/commit/dad2f521066e73c3dcdaec196cd6940401e31f3a))

  ### New Features and Enhancements

  * support proxy (box/box-codegen[#577](https://github.com/box/box-codegen/issues/577)) ([#274](https://github.com/box/box-codegen/issues/274)) ([`dea1937`](https://github.com/box/box-codegen/commit/dea19373a7169365acb968a66c78c5937ef698e1))
</Update>

<Update label="2024-09-26">
  ## Box Dotnet SDK Generated v1.2.0 released

  ### Bug Fixes

  * correctly send `datetime` when in `queryParams` (box/box-codegen[#560](https://github.com/box/box-codegen/issues/560)) ([#243](https://github.com/box/box-codegen/issues/243)) ([`9657526`](https://github.com/box/box-codegen/commit/9657526667753d77eacfd674cde60ab4030ae42d))
  * Fix variants in metadata query results (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#249](https://github.com/box/box-codegen/issues/249)) ([`37625ea`](https://github.com/box/box-codegen/commit/37625eabe4f87d57a9f58920829c00cddd34bcb1))

  ### New Features and Enhancements

  * add Hubs Beta (box/box-openapi[#453](https://github.com/box/box-codegen/issues/453)) ([#241](https://github.com/box/box-codegen/issues/241)) ([`c28f660`](https://github.com/box/box-codegen/commit/c28f6605c94e250bbab853ef610c46c1d3c9ef95))
  * include raw `json` in types (box/box-codegen[#567](https://github.com/box/box-codegen/issues/567)) ([#258](https://github.com/box/box-codegen/issues/258)) ([`a1e7bc5`](https://github.com/box/box-codegen/commit/a1e7bc55da0dec8bfd1159a1c158154177581019))
  * Support `ai/extract` and `ai/extract_structured` endpoints (box/box-codegen[#564](https://github.com/box/box-codegen/issues/564)) ([#253](https://github.com/box/box-codegen/issues/253)) ([`a17d8f8`](https://github.com/box/box-codegen/commit/a17d8f8dbce8ac7f42b9e23c8c216e992a64d762))
</Update>

<Update label="2024-09-19">
  ## Box AI API default model update

  Box AI Platform API has been updated with a new default model for the `POST /2.0/ai/ask` endpoint. Both single and multiple document modes are now based on Azure's `gpt-4o-mini`.

  > **Note**: Box AI Platform API is currently a beta feature offered subject to Box’s Main Beta Agreement, and the available capabilities may change. Box AI Platform API is available to all Enterprise Plus customers.

  For more information on [default agent configuration](https://developer.box.com/guides/box-ai/ai-agents/get-agent-default-config/) and [supported AI models](https://developer.box.com/guides/box-ai/ai-models) visit developer guides.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/) for any help needed.
</Update>

<Update label="2024-09-19">
  ## Box Python SDK Generated v1.5.1 released

  ### Bug Fixes

  * Fix proxy `url` without proxy credentials (box/box-codegen[#568](https://github.com/box/box-codegen/issues/568)) ([#322](https://github.com/box/box-codegen/issues/322)) ([`fb19160`](https://github.com/box/box-codegen/commit/fb19160307b58d5f08bb12e0f846d71ff936ad6a)), closes [#318](https://github.com/box/box-codegen/issues/318)
  * Stop sending last empty chunk for chunk upload (box/box-codegen[#569](https://github.com/box/box-codegen/issues/569)) ([#324](https://github.com/box/box-codegen/issues/324)) ([`1605f04`](https://github.com/box/box-codegen/commit/1605f0495994b333e735bc98f28fa714324b75f5)), closes [#321](https://github.com/box/box-codegen/issues/321)
</Update>

<Update label="2024-09-18" description="Box Python SDK Generated v1.5.0 released">
  ## Box Python SDK Generated v1.5.0 released

  ### Bug Fixes

  * Add the missing license to `setup.py` (box/box-codegen[#562](https://github.com/box/box-codegen/issues/562)) ([#307](https://github.com/box/box-codegen/issues/307)) ([`679d789`](https://github.com/box/box-codegen/commit/679d7891b2a20e7407b8c9f00bd95c3b294ab861))
  * Fix variants in metadata query results (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#313](https://github.com/box/box-codegen/issues/313)) ([`8830303`](https://github.com/box/box-codegen/commit/883030335e2a3c12a5e0b01d8a82df30ccce16a6))

  ### New Features and Enhancements

  * Add support for proxy (box/box-codegen[#559](https://github.com/box/box-codegen/issues/559)) ([#302](https://github.com/box/box-codegen/issues/302)) ([`3d881ac`](https://github.com/box/box-codegen/commit/3d881acdebf2b18e2f0f82211f5abdcc32d1ddb0))
  * Introduce `raw_data` field for storing raw `json` response (box/box-codegen[#566](https://github.com/box/box-codegen/issues/566)) ([#319](https://github.com/box/box-codegen/issues/319)) ([`3776dc3`](https://github.com/box/box-codegen/commit/3776dc3d44bc09eb68da99f45e36e058dca2607e))
  * Support `ai/extract` and `ai/extract_structured` endpoints (box/box-codegen[#564](https://github.com/box/box-codegen/issues/564)) ([#317](https://github.com/box/box-codegen/issues/317)) ([`b3d8da4`](https://github.com/box/box-codegen/commit/b3d8da41007a9d47b73b699fd84da6f9540866d2))
  * Support App item associations (box/box-codegen[#561](https://github.com/box/box-codegen/issues/561)) ([#299](https://github.com/box/box-codegen/issues/299)) ([`8b6ea0b`](https://github.com/box/box-codegen/commit/8b6ea0bbec719a36eb11b6d214c08801c4f1a40b))
</Update>

<Update label="2024-09-17">
  ## Metadata extraction with Box AI Platform API now available in Beta

  With its recent addition, Box AI Platform API allows you to extract metadata from the provided input.
  For example you can extract the financial information from an invoice, or patient data from a medical certificate.

  > **Note**: Box AI Platform API is currently a beta feature offered subject to Box’s Main Beta Agreement, and the available capabilities may change. Box AI Platform API is available to all Enterprise Plus customers.

  You have the following options:

  [`POST /2.0/ai_extract`](/reference/post-ai-extract) endpoint allows you to extract metadata from the provided file in a freeform way.
  This means you have more freedom in creating the prompt, and the metadata template is not required to run the request.
  [`POST /2.0/ai_extract_structured`](/reference/post-ai-extract-structured) endpoint allows you to extract metadata from the provided file using a [metadata template](https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates) or `fields` structure.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-09-16">
  ## App item associations

  The [app item associations API](/reference/resources/app-item-association) allows you to check which app items are connected with a specific file or folder, including the app items associated with ancestors of the file or folder.

  An [app item](/reference/resources/app-item) is a content object owned by an application. It can group files and folders together from different paths. That set can be shared through a collaboration.

  An [app item association](/reference/resources/app-item-associations) is a connection between a file or folder and an app item. Associations between a folder and an app item cascade down to all descendants of the folder.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-09-11" description="Box TypeScript SDK Generated v1.6.0 released">
  ## Box TypeScript SDK Generated v1.6.0 released

  ### Bug Fixes

  * Add the missing license to `package.json` (box/box-codegen[#562](https://github.com/box/box-typescript-sdk-gen/issues/562)) ([#343](https://github.com/box/box-typescript-sdk-gen/issues/343)) ([`cc9a8b8`](https://github.com/box/box-typescript-sdk-gen/commit/cc9a8b8ac628e348d32176f8ba69add649c555bd))
  * Fix variants in metadata query results (box/box-openapi[#456](https://github.com/box/box-typescript-sdk-gen/issues/456)) ([#349](https://github.com/box/box-typescript-sdk-gen/issues/349)) ([`2131e98`](https://github.com/box/box-typescript-sdk-gen/commit/2131e98ff5530c7440ff50ec0da46cc317d0a4ae))

  ### New Features and Enhancements

  * add Hubs Beta (box/box-openapi[#453](https://github.com/box/box-typescript-sdk-gen/issues/453)) ([#333](https://github.com/box/box-typescript-sdk-gen/issues/333)) ([`40359c7`](https://github.com/box/box-typescript-sdk-gen/commit/40359c71aa25ecfe7ec53bfa19de62b9d83d4ace))
  * Add support for proxy (box/box-codegen[#559](https://github.com/box/box-typescript-sdk-gen/issues/559)) ([#337](https://github.com/box/box-typescript-sdk-gen/issues/337)) ([`0ffd9c8`](https://github.com/box/box-typescript-sdk-gen/commit/0ffd9c8095d1aa742144146383ae94f1f4526af0))
</Update>

<Update label="2024-09-11">
  ## Box Swift SDK Generated 0.5.0 released

  ### Bug Fixes

  * Fix variants in metadata query results (box/box-openapi[#456](https://github.com/box/box-codegen/issues/456)) ([#232](https://github.com/box/box-codegen/issues/232)) ([`be2fa52`](https://github.com/box/box-codegen/commit/be2fa52bb0d086f6c9b20fd5c3bdcad4b98f3f37))

  ### New Features and Enhancements

  * add Hubs Beta (box/box-openapi[#453](https://github.com/box/box-codegen/issues/453)) ([#220](https://github.com/box/box-codegen/issues/220)) ([`546f487`](https://github.com/box/box-codegen/commit/546f487bde9dae2407ff65620eb6e6a81e45b149))
</Update>

<Update label="2024-09-05">
  ## Box Swift SDK Generated 0.4.0 released

  ### Bug Fixes

  * Add missing fields to Sign Template Signer and fix AI schema (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#206](https://github.com/box/box-codegen/issues/206)) ([`31920e6`](https://github.com/box/box-codegen/commit/31920e67692c16b0600c4c9f4c279e22d02e4598))
  * Fix `IntegrationMapping` schemas (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#203](https://github.com/box/box-codegen/issues/203)) ([`0074ee3`](https://github.com/box/box-codegen/commit/0074ee326627d01057cf50cb257d2291b646ab08))
  * Fix chunk upload in Swift (box/box-codegen[#555](https://github.com/box/box-codegen/issues/555)) ([#215](https://github.com/box/box-codegen/issues/215)) ([`93ff568`](https://github.com/box/box-codegen/commit/93ff5686415d99aa807d57d9e062f5a96380d707))

  ### New Features and Enhancements

  * Include URL into `FetchOptions` (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#208](https://github.com/box/box-codegen/issues/208)) ([`b65822d`](https://github.com/box/box-codegen/commit/b65822d379b1d5e9be7b179ed754e725f5a499fa))
</Update>

<Update label="2024-08-30">
  ## Box TypeScript SDK Generated v1.5.1 released

  ### Bug Fixes

  * Fix fetch options with interceptor (box/box-codegen[#556](https://github.com/box/box-typescript-sdk-gen/issues/556)) ([#326](https://github.com/box/box-typescript-sdk-gen/issues/326)) ([`3751eea`](https://github.com/box/box-typescript-sdk-gen/commit/3751eea67047021fe298c841596ae362ed1e47da))
</Update>

<Update label="2024-08-30">
  ## Box Python SDK Generated v1.4.1 released

  ### Bug Fixes

  * Do not store data in-memory during download process in Python (box/box-codegen[#557](https://github.com/box/box-codegen/issues/557)) ([#294](https://github.com/box/box-codegen/issues/294)) ([`7c645ae`](https://github.com/box/box-codegen/commit/7c645aea9fa8575531e0b40ffc997a0f65b6e409))
</Update>

<Update label="2024-08-23">
  ## Box TypeScript SDK Generated v1.5.0 released

  ### Bug Fixes

  * Add missing fields to Sign Template Signer and fix AI schema (box/box-openapi[#451](https://github.com/box/box-typescript-sdk-gen/issues/451)) ([#317](https://github.com/box/box-typescript-sdk-gen/issues/317)) ([`340fbd8`](https://github.com/box/box-typescript-sdk-gen/commit/340fbd84f6fa408155c6a2a4b9b7b03b88f76f24))
  * Fix `IntegrationMapping` schemas (box/box-codegen[#551](https://github.com/box/box-typescript-sdk-gen/issues/551)) ([#315](https://github.com/box/box-typescript-sdk-gen/issues/315)) ([`a863b1e`](https://github.com/box/box-typescript-sdk-gen/commit/a863b1eb8fcfccd78714e3f52ce96d89ef69ca72))

  ### New Features and Enhancements

  * Add new parameters to Box AI methods and introduce `AiResponseFull` variant (box/box-openapi[#446](https://github.com/box/box-typescript-sdk-gen/issues/446)) ([#313](https://github.com/box/box-typescript-sdk-gen/issues/313)) ([`d9664fd`](https://github.com/box/box-typescript-sdk-gen/commit/d9664fd7d431685c8e115415085bbe69d17f272d))
  * Include URL into `FetchOptions` (box/box-codegen[#549](https://github.com/box/box-typescript-sdk-gen/issues/549)) ([#319](https://github.com/box/box-typescript-sdk-gen/issues/319)) ([`30eaa6b`](https://github.com/box/box-typescript-sdk-gen/commit/30eaa6ba7aa0fcd5e2f71026d7bf58729d387221))
</Update>

<Update label="2024-08-23">
  ## Box Python SDK Generated v1.4.0 released

  ### Bug Fixes

  * Add missing fields to Sign Template Signer and fix AI schema (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#281](https://github.com/box/box-codegen/issues/281)) ([`0708351`](https://github.com/box/box-codegen/commit/0708351171eca1fe4914b823a4257bbabd3cd075))
  * Fix `IntegrationMapping` schemas (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#279](https://github.com/box/box-codegen/issues/279)) ([`0337e06`](https://github.com/box/box-codegen/commit/0337e06c6bf6d35dd51409c429b7fef295f5a406))

  ### New Features and Enhancements

  * Add new parameters to Box AI methods and introduce `AiResponseFull` variant (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#277](https://github.com/box/box-codegen/issues/277)) ([`1267a21`](https://github.com/box/box-codegen/commit/1267a215fbc8292059603665a53b0159d7a1242c))
  * Include URL into `FetchOptions` (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#283](https://github.com/box/box-codegen/issues/283)) ([`dd05b1c`](https://github.com/box/box-codegen/commit/dd05b1c2b1687d8647f4116c022dbf1890984adc))
</Update>

<Update label="2024-08-23">
  ## Box Dotnet SDK Generated v1.1.0 released

  ### Bug Fixes

  * Add missing `item_upload` scope ([#201](https://github.com/box/box-codegen/issues/201)) ([`483b055`](https://github.com/box/box-codegen/commit/483b05586f8e45771e101d286fddebc564ff89bd))
  * Add missing fields to Sign Template Signer and fix AI schema (box/box-openapi[#451](https://github.com/box/box-codegen/issues/451)) ([#229](https://github.com/box/box-codegen/issues/229)) ([`121f733`](https://github.com/box/box-codegen/commit/121f733f52e945927125f4941206b1553202914d))
  * Fix `IntegrationMapping` schemas (box/box-codegen[#551](https://github.com/box/box-codegen/issues/551)) ([#226](https://github.com/box/box-codegen/issues/226)) ([`3eca154`](https://github.com/box/box-codegen/commit/3eca15434b65bc0bb2421d36ec50691e7fe40e3b))
  * Improve handling of network exceptions, handle big file upload (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#222](https://github.com/box/box-codegen/issues/222)) ([`75ccd07`](https://github.com/box/box-codegen/commit/75ccd078e29015b865462ea1aaf0420d5e63d9cd))

  ### New Features and Enhancements

  * Add new parameters to Box AI methods and introduce `AiResponseFull` variant (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#224](https://github.com/box/box-codegen/issues/224)) ([`6d205c4`](https://github.com/box/box-codegen/commit/6d205c4e28a657ad65ae704a7343a8670806f7f1))
  * Include URL into `FetchOptions` (box/box-codegen[#549](https://github.com/box/box-codegen/issues/549)) ([#231](https://github.com/box/box-codegen/issues/231)) ([`41c45dc`](https://github.com/box/box-codegen/commit/41c45dcf6476b6cae7941c0952c375aa76ce42a1))
  * Parametrize chunked uploads endpoint URLs (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#208](https://github.com/box/box-codegen/issues/208)) ([`feac37c`](https://github.com/box/box-codegen/commit/feac37c34f99b5951731b605ef895f7f3b5de6dd))
  * Support `nullable` fields (box/box-codegen[#550](https://github.com/box/box-codegen/issues/550)) ([#230](https://github.com/box/box-codegen/issues/230)) ([`b9da32b`](https://github.com/box/box-codegen/commit/b9da32b27f506618faa0119f725528555be14f60))
</Update>

<Update label="2024-08-22">
  ## Box Swift SDK Generated 0.3.1 released

  ### Bug Fixes

  * Extract `IntegrationMappingPartnerItemSlack` to `IntegrationMappingPartnerItemSlackUnion` (box/box-codegen[#530](https://github.com/box/box-codegen/issues/530)) ([#165](https://github.com/box/box-codegen/issues/165)) ([`d51df9a`](https://github.com/box/box-codegen/commit/d51df9a19d06db886358e94ce70551c283e5cc45))
  * Improve chunked upload reliability (box/box-codegen[#529](https://github.com/box/box-codegen/issues/529)) ([#164](https://github.com/box/box-codegen/issues/164)) ([`5d87629`](https://github.com/box/box-codegen/commit/5d876299aa88b18accde22379950780bff100da0))
  * Retry requests with 202 status code and `Retry-After` header (box/box-codegen[#538](https://github.com/box/box-codegen/issues/538)) ([#177](https://github.com/box/box-codegen/issues/177)) ([`64f27b3`](https://github.com/box/box-codegen/commit/64f27b3858725adaa53a10a6e8df8c0bcfe73fea))

  ### New Features and Enhancements

  * Add `is_active` parameter to user collaboration (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#163](https://github.com/box/box-codegen/issues/163)) ([`5f726bb`](https://github.com/box/box-codegen/commit/5f726bbffd682934ab5731e1620489b1ee54e5a1))
  * Add new parameters to Box AI methods and introduce `AiResponseFull` variant (box/box-openapi[#446](https://github.com/box/box-codegen/issues/446)) ([#201](https://github.com/box/box-codegen/issues/201)) ([`7c09090`](https://github.com/box/box-codegen/commit/7c0909032733742cb5a019c897910ced2e9d6788))
  * Add support for Swift 5.6 (box/box-codegen[#541](https://github.com/box/box-codegen/issues/541)) ([#180](https://github.com/box/box-codegen/issues/180)) ([`04b7020`](https://github.com/box/box-codegen/commit/04b7020f1220f73ad4637e6033d5539c56a64fcd))
  * parametrize chunked uploads endpoint URLs (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#192](https://github.com/box/box-codegen/issues/192)) ([`ea18f9e`](https://github.com/box/box-codegen/commit/ea18f9e5eb6558edb29ff378bceb5528ccd4fcfb))
  * Support AI Agent API (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#170](https://github.com/box/box-codegen/issues/170)) ([`fc9a00b`](https://github.com/box/box-codegen/commit/fc9a00bdcaffeaccfd87caad73fe666fb46c36ab))
</Update>

<Update label="2024-08-22">
  ## Box Python SDK v3.13.0 released

  ### New Features and Enhancements

  * Add support for get AI agent default ([#883](https://github.com/box/box-python-sdk/issues/883)) ([`c1010e0`](https://github.com/box/box-python-sdk/commit/c1010e0349847586a9f00046570e975ec48eb0c5))
</Update>

<Update label="2024-08-12">
  ## Box TypeScript SDK Generated v1.4.0 released

  ### Bug Fixes

  * Add missing token scope (box/box-openapi[#442](https://github.com/box/box-typescript-sdk-gen/issues/442)) ([#281](https://github.com/box/box-typescript-sdk-gen/issues/281)) ([`ca77f58`](https://github.com/box/box-typescript-sdk-gen/commit/ca77f58b10d3a302748750584730f0fcdd8b4b55))
  * Fix fetch method for multipart request (box/box-codegen[#545](https://github.com/box/box-typescript-sdk-gen/issues/545)) ([#303](https://github.com/box/box-typescript-sdk-gen/issues/303)) ([`f8ceac0`](https://github.com/box/box-typescript-sdk-gen/commit/f8ceac005f043017e7cde310490e79ab9195f8d7))

  ### New Features and Enhancements

  * Parametrize chunked uploads endpoint URLs (box/box-openapi[#444](https://github.com/box/box-typescript-sdk-gen/issues/444)) ([#302](https://github.com/box/box-typescript-sdk-gen/issues/302)) ([`293a6e9`](https://github.com/box/box-typescript-sdk-gen/commit/293a6e9aeabbba37e4c12e2322a79717a10e1775))
  * **ts:** Add comments to properties and methods (box/box-codegen[#537](https://github.com/box/box-typescript-sdk-gen/issues/537)) ([#284](https://github.com/box/box-typescript-sdk-gen/issues/284)) ([`db3a2b5`](https://github.com/box/box-typescript-sdk-gen/commit/db3a2b57fbe0eec17373a2acf8089ff247c98225))
</Update>

<Update label="2024-08-12">
  ## Box Python SDK Generated v1.3.0 released

  ### Bug Fixes

  * Fix fetch method for multipart request (box/box-codegen[#545](https://github.com/box/box-codegen/issues/545)) ([#266](https://github.com/box/box-codegen/issues/266)) ([`08a0818`](https://github.com/box/box-codegen/commit/08a0818995d64995c3e2720a459f9221c9ca1dea))

  ### New Features and Enhancements

  * Parametrize chunked uploads endpoint URLs (box/box-openapi[#444](https://github.com/box/box-codegen/issues/444)) ([#264](https://github.com/box/box-codegen/issues/264)) ([`b5bce24`](https://github.com/box/box-codegen/commit/b5bce24478c70ae6bb997adc773a0e2a76223568))
</Update>

<Update label="2024-08-06">
  ## Box Python SDK v3.12.0 released

  ### New Features and Enhancements

  * add create sign request function with different required parameters ([#878](https://github.com/box/box-python-sdk/issues/878)) ([`d972f54`](https://github.com/box/box-python-sdk/commit/d972f54dcf9962c6b911422793a682d8f6289f9e))
  * Support Box AI features ([#877](https://github.com/box/box-python-sdk/issues/877)) ([`3026d2a`](https://github.com/box/box-python-sdk/commit/3026d2ab9932cd07aa9ff15a3ac3c3c14d3089b0))
</Update>

<Update label="2024-08-06">
  ## Box Node SDK v3.7.1 released

  ### Bug Fixes

  * add version to copy file options annotation ([#885](https://github.com/box/box-node-sdk/issues/885)) ([`4f9312c`](https://github.com/box/box-node-sdk/commit/4f9312c63138f8cf8e0a9e46a9e1345172dbdc6b))
</Update>

<Update label="2024-08-06">
  ## Box CLI v3.15.0 released

  ### New Features and Enhancements

  * Support AI APIs using Box Node SDK ([#539](https://github.com/box/boxcli/issues/539)) ([`59551d2`](https://github.com/box/boxcli/commit/59551d2153549b5a87b2c3fae01eb3089d640c89))
</Update>

<Update label="2024-07-26">
  ## Box Python SDK Generated v1.2.0 released

  ### Bug Fixes

  * Improve chunked upload reliability ([#224](https://github.com/box/box-codegen/issues/224)) ([`05f0353`](https://github.com/box/box-codegen/commit/05f035354a76dac0d71849523e4a28641ac92aee))

  ### New Features and Enhancements

  * Add `is_active` parameter to user collaboration (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#222](https://github.com/box/box-codegen/issues/222)) ([`2b7bbe4`](https://github.com/box/box-codegen/commit/2b7bbe41ed23e50c6717148fa5e9e2c24a3f5897))
  * Retry request with status code `202` (box/box-codegen[#511](https://github.com/box/box-codegen/issues/511)) ([#204](https://github.com/box/box-codegen/issues/204)) ([`f50ad6e`](https://github.com/box/box-codegen/commit/f50ad6e236003901792eb333738020cbdd8c8ae3))
  * Support AI Agent API (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#229](https://github.com/box/box-codegen/issues/229)) ([`c565383`](https://github.com/box/box-codegen/commit/c5653839e1a150377e7d5c4764d4c2a7b7d07c4a))
  * Support sending fields with `null` value (box/box-codegen[#528](https://github.com/box/box-codegen/issues/528)) ([#230](https://github.com/box/box-codegen/issues/230)) ([`f91076e`](https://github.com/box/box-codegen/commit/f91076e1bfbccae4a0dff4b66d7bafb5357858c5)), closes [#202](https://github.com/box/box-codegen/issues/202)
</Update>

<Update label="2024-07-25">
  ## Introducing New Generation Swift SDK

  We are excited to introduce [Box Swift SDK](https://github.com/box/box-swift-sdk-gen), designed to elevate the developer experience and streamline your integration with the Box Content Cloud.

  With the [new generation of Swift SDK](https://github.com/box/box-swift-sdk-gen), you’ll have access to:

  * **Full API Support**: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications.
  * **Rapid API Updates**: Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
  * **Embedded Documentation**: We understand that access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process.
  * **Enhanced Convenience Methods**: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers which help to ensure that you’re using variables correctly, and much more.

  Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. Start building innovative solutions faster and more efficiently. Happy coding!
</Update>

<Update label="2024-07-25">
  ## Fetch and override default AI configuration

  Thanks to the [`GET /2.0/ai_agent_default`](/reference/get-ai-agent-default) endpoint you can now fetch the default configuration for AI services.

  Once you get the configuration details, you can override them using the `ai_agent` parameter available in the [`POST /2.0/ai/ask`](/reference/post-ai-ask#param-ai-agent) and [`POST /2.0/ai/text_gen`](/reference/post-ai-text-gen#param-ai-agent) requests.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-07-24">
  ## Box TypeScript SDK Generated v1.3.0 released

  ### Bug Fixes

  * Extract `IntegrationMappingPartnerItemSlack` to union type (box/box-codegen[#530](https://github.com/box/box-typescript-sdk-gen/issues/530)) ([#255](https://github.com/box/box-typescript-sdk-gen/issues/255)) ([`fa8952a`](https://github.com/box/box-typescript-sdk-gen/commit/fa8952a6582d9965bbb4ab66bbeff057f5c68851))
  * Improve chunked upload reliability (box/box-codegen[#529](https://github.com/box/box-typescript-sdk-gen/issues/529)) ([#254](https://github.com/box/box-typescript-sdk-gen/issues/254)) ([`12d9288`](https://github.com/box/box-typescript-sdk-gen/commit/12d928850e0a1cd60f336a9919474b9aaba33028))

  ### New Features and Enhancements

  * Add `is_active` parameter to user collaboration (box/box-openapi[#437](https://github.com/box/box-typescript-sdk-gen/issues/437)) ([#253](https://github.com/box/box-typescript-sdk-gen/issues/253)) ([`4d8d436`](https://github.com/box/box-typescript-sdk-gen/commit/4d8d436977b3e487a47e7717626f1c0f2eb43227))
  * Support AI Agent API (box/box-codegen[#531](https://github.com/box/box-typescript-sdk-gen/issues/531)) ([#260](https://github.com/box/box-typescript-sdk-gen/issues/260)) ([`0ec40d4`](https://github.com/box/box-typescript-sdk-gen/commit/0ec40d44c86a8a9cf4fe594966cfad1866be457c))
</Update>

<Update label="2024-07-24">
  ## Box Dotnet SDK Generated v1.0.0 released

  ### Bug Fixes

  * Extract `IntegrationMappingPartnerItemSlack` to `IntegrationMappingPartnerItemSlackUnion` (box/box-codegen[#530](https://github.com/box/box-codegen/issues/530)) ([#183](https://github.com/box/box-codegen/issues/183)) ([`3b1b634`](https://github.com/box/box-codegen/commit/3b1b634904edc73af094aa8aa6e89d32b9e92aee))
  * Improve chunked upload reliability (box/box-codegen[#529](https://github.com/box/box-codegen/issues/529)) ([#182](https://github.com/box/box-codegen/issues/182)) ([`e2a045f`](https://github.com/box/box-codegen/commit/e2a045f5d2afbe15be0284099ee2236f9c19cd73))
  * remove `init` from some of the required fields, `nullability` fixes (box/box-codegen[#532](https://github.com/box/box-codegen/issues/532)) ([#190](https://github.com/box/box-codegen/issues/190)) ([`c58f8af`](https://github.com/box/box-codegen/commit/c58f8afa41fa4346eb3f2ced9e48695980e917e1))
  * retry requests with status code of 202 and `retry-after` header (box/box-codegen[#533](https://github.com/box/box-codegen/issues/533)) ([#191](https://github.com/box/box-codegen/issues/191)) ([`abaafd7`](https://github.com/box/box-codegen/commit/abaafd70b982ae560430ff083b4bee1d533d5275))
  * Update chunked upload (box/box-codegen[#523](https://github.com/box/box-codegen/issues/523)) ([#177](https://github.com/box/box-codegen/issues/177)) ([`9bcaf51`](https://github.com/box/box-codegen/commit/9bcaf51e0bcd3134dea2b37277a24abaa483754a))

  ### New Features and Enhancements

  * Add `is_active` parameter to user collaboration (box/box-openapi[#437](https://github.com/box/box-codegen/issues/437)) ([#181](https://github.com/box/box-codegen/issues/181)) ([`ec5f2d1`](https://github.com/box/box-codegen/commit/ec5f2d1d2cdba330f26a7db40042b70d3ec5bca2))
  * simplify `namespaces` (box/box-codegen[#518](https://github.com/box/box-codegen/issues/518)) ([#175](https://github.com/box/box-codegen/issues/175)) ([`7831b09`](https://github.com/box/box-codegen/commit/7831b098971616497cbc90a8c277fee9b2c42c39))
  * Support AI Agent API (box/box-codegen[#531](https://github.com/box/box-codegen/issues/531)) ([#188](https://github.com/box/box-codegen/issues/188)) ([`0c29645`](https://github.com/box/box-codegen/commit/0c296458ef966e57c5aba2a8068034d4de820ef9))
  * Support default interface properties, bump dependencies (box/box-codegen[#527](https://github.com/box/box-codegen/issues/527)) ([#184](https://github.com/box/box-codegen/issues/184)) ([`6b52792`](https://github.com/box/box-codegen/commit/6b52792057ab94f6bcc2f86b47e0ed5f25900adf))
</Update>

<Update label="2024-07-22">
  ## Box Windows SDK v5.8.0 released

  ### New Features and Enhancements

  * add support for AI ([#965](https://github.com/box/box-windows-sdk-v2/issues/965)) ([`a9e130a`](https://github.com/box/box-windows-sdk-v2/commit/a9e130a99cf9862f9b50178a6188b2820f9f2c32))

  ### Bug Fixes

  * Bump `System.IdentityModel.Tokens.Jwt` dependency version to `v6.35.0` ([#962](https://github.com/box/box-windows-sdk-v2/issues/962)) ([`6e47237`](https://github.com/box/box-windows-sdk-v2/commit/6e472378e2fccea2db67bf5ef0eb017a31491703)), closes [#960](https://github.com/box/box-windows-sdk-v2/issues/960) [#961](https://github.com/box/box-windows-sdk-v2/issues/961)
  * remove `Microsoft.AspNetCore.StaticFiles` and `System.Web` dependencies ([#964](https://github.com/box/box-windows-sdk-v2/issues/964)) ([`2c8eedc`](https://github.com/box/box-windows-sdk-v2/commit/2c8eedc91c473aca52249aad443345471ca7eafc))

  - [https://www.nuget.org/packages/Box.V2/5.8.0>](https://www.nuget.org/packages/Box.V2/5.8.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.8.0>](https://www.nuget.org/packages/Box.V2.Core/5.8.0>)
</Update>

<Update label="2024-07-17">
  ## React 18 support for Box UI Elements

  [Box UI Elements](/guides/embed/ui-elements) now support React 18, bringing a whole new level of flexibility and functionality for content collaboration in third-party apps.
  With this update, you can leverage the power of React 18’s cutting-edge features, drive innovation with latest front-end stack, while seamlessly integrating with the intelligent content cloud.

  For details, read our [blog post](https://medium.com/box-developer-blog/seamless-integration-box-ui-elements-and-react-18-compatibility-4db97a09ff01).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://medium.com/box-developer-blog/seamless-integration-box-ui-elements-and-react-18-compatibility-4db97a09ff01) for any help needed.
</Update>

<Update label="2024-07-16">
  ## Box UI Elements v21.0.0 released

  ### [21.0.0](https://github.com/box/box-ui-elements/compare/v20.0.0...v21.0.0) (2024-07-16)

  ### Bug Fixes

  * upgrade hapi address package dependency ([#3579](https://github.com/box/box-ui-elements/issues/3579)) ([`b089619`](https://github.com/box/box-ui-elements/commit/b0896194b79263ab60b47363abfbb98258244a47))
  * upgrade react-virtualized peer dependency ([#3578](https://github.com/box/box-ui-elements/issues/3578)) ([`3ebae37`](https://github.com/box/box-ui-elements/commit/3ebae376521ab8a4232005bae32e81c2b82da903))
  * **avatars:** Add type to Fetch avatar ([#3560](https://github.com/box/box-ui-elements/issues/3560)) ([`14a194f`](https://github.com/box/box-ui-elements/commit/14a194f449018932134cc5df741ecd36c774a321))
  * **content-sidebar:** update to sidebar icon styles ([#3561](https://github.com/box/box-ui-elements/issues/3561)) ([`381a3b6`](https://github.com/box/box-ui-elements/commit/381a3b642b0148553c6f65cea159b0718271117a))
  * **content-uploader:** fix multiple items droppable issue ([#3565](https://github.com/box/box-ui-elements/issues/3565)) ([`87815de`](https://github.com/box/box-ui-elements/commit/87815de94e8fb607f24a0e17750ffbaa2e713125))
  * **i18n:** update translations ([#3563](https://github.com/box/box-ui-elements/issues/3563)) ([`6d9c65f`](https://github.com/box/box-ui-elements/commit/6d9c65f0054d329a20a65ef814b9c0e867c9baf7))
  * **i18n:** update translations ([#3564](https://github.com/box/box-ui-elements/issues/3564)) ([`7988af8`](https://github.com/box/box-ui-elements/commit/7988af8eb56a8e6e5abf8bb07d53f3250b148cf5))
  * **i18n:** update translations ([#3566](https://github.com/box/box-ui-elements/issues/3566)) ([`3103983`](https://github.com/box/box-ui-elements/commit/310398302abd67bb48dbf5317dc858f054b0cc16))
  * **preview:** Update preview error messages ([#3562](https://github.com/box/box-ui-elements/issues/3562)) ([`aff6217`](https://github.com/box/box-ui-elements/commit/aff6217671d25015d314813295b871facfb8a9cc))

  ### Features

  * **docgen:** add docgen icon ([#3573](https://github.com/box/box-ui-elements/issues/3573)) ([`f5d4955`](https://github.com/box/box-ui-elements/commit/f5d49554683c965335366ba0f7f34771cec4d4d4))
  * **react:** BREAKING CHANGE Upgrade to React 18 ([#3556](https://github.com/box/box-ui-elements/issues/3556)) ([`91e0978`](https://github.com/box/box-ui-elements/commit/91e09787c545194ef61cb057e74df7dfd111728b))
  * **webpack:** BREAKING CHANGE Upgrade to webpack 5 and `react-styleguidist` 12.0.1 ([#3568](https://github.com/box/box-ui-elements/issues/3568)) ([`a812294`](https://github.com/box/box-ui-elements/commit/a81229420c1a133145c9899efe908a080f59bd9f))

  ### BREAKING CHANGES

  * upgrade hapi/address to resolve undefined buffer reference
  * upgrade peer dependency for react-virtualized to support react 18
</Update>

<Update label="2024-07-16">
  ## Box Node SDK v3.7.0 released

  ### New Features and Enhancements

  * Support AI APIs ([#883](https://github.com/box/box-node-sdk/issues/883)) ([`bb81e07`](https://github.com/box/box-node-sdk/commit/bb81e074eb1017bd742c90159e6cf4e6ce9d9776))
</Update>

<Update label="2024-07-16">
  ## Box Java SDK v4.11.1 released

  ### Bug Fixes

  * Fix order of file upload multipart request ([#1261](https://github.com/box/box-java-sdk/issues/1261)) ([`7200ac7`](https://github.com/box/box-java-sdk/commit/7200ac77888b3639f2c294486be278e316efcfb0))
</Update>

<Update label="2024-07-15">
  ## Box Java SDK v4.11.0 released

  ### New Features and Enhancements

  * Allow overriding creation of OkHttp Call ([#1257](https://github.com/box/box-java-sdk/issues/1257)) ([`bd6fde6`](https://github.com/box/box-java-sdk/commit/bd6fde6689bebe6cb5889c91214db68e08a4ec8b))

  ### Bug Fixes

  * Add missing fields when update classification template ([#1255](https://github.com/box/box-java-sdk/issues/1255)) ([`f17f817`](https://github.com/box/box-java-sdk/commit/f17f817bde5a412358bf3de8e489ed080715ec4b))
  * Fix deserializing permissions for `BoxFile` and `BoxFolder` ([#1256](https://github.com/box/box-java-sdk/issues/1256)) ([`f088448`](https://github.com/box/box-java-sdk/commit/f08844889800a01f7c78941036f6228502fca8b0))
</Update>

<Update label="2024-07-08">
  ## Box TypeScript SDK Generated v1.2.0 released

  ### Bug Fixes

  * Fix upload in browser (box/box-codegen[#524](https://github.com/box/box-typescript-sdk-gen/issues/524)) ([#248](https://github.com/box/box-typescript-sdk-gen/issues/248)) ([`88d747e`](https://github.com/box/box-typescript-sdk-gen/commit/88d747e0f03dfa3c2d6089257c6e8b5b635775e0))
  * Update chunked upload (box/box-codegen[#523](https://github.com/box/box-typescript-sdk-gen/issues/523)) ([#247](https://github.com/box/box-typescript-sdk-gen/issues/247)) ([`27ceb35`](https://github.com/box/box-typescript-sdk-gen/commit/27ceb35e6444843eea9b7ec6923fe958c9a74571))

  ### New Features and Enhancements

  * Retry request with status code `202` (box/box-codegen[#511](https://github.com/box/box-typescript-sdk-gen/issues/511)) ([#235](https://github.com/box/box-typescript-sdk-gen/issues/235)) ([`03b8f43`](https://github.com/box/box-typescript-sdk-gen/commit/03b8f4314ada5ef5596706b7599cc76565fe96a5))
  * Support extensible enum types in Typescript (box/box-codegen[#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([#243](https://github.com/box/box-typescript-sdk-gen/issues/243)) ([`5237972`](https://github.com/box/box-typescript-sdk-gen/commit/523797273bc08e3b22609ef0019432ab3e43c3ba))
</Update>

<Update label="2024-07-03">
  ## Box Dotnet SDK Generated v0.4.0 released

  ### Bug Fixes

  * Change base URLs (box/box-codegen[#491](https://github.com/box/box-codegen/issues/491)) ([#126](https://github.com/box/box-codegen/issues/126)) ([`b4c6025`](https://github.com/box/box-codegen/commit/b4c6025dc7039e923b19282333f162bb9d3469a9))
  * Fix CI for auto update pull requests (box/box-codegen[#506](https://github.com/box/box-codegen/issues/506)) ([#152](https://github.com/box/box-codegen/issues/152)) ([`766f03c`](https://github.com/box/box-codegen/commit/766f03c743b7a2ab363135ff282e468b6b71d377))
  * Fix schema for updating classification on a file and folder (box/box-openapi[#423](https://github.com/box/box-codegen/issues/423)) ([#117](https://github.com/box/box-codegen/issues/117)) ([`40f5a97`](https://github.com/box/box-codegen/commit/40f5a97ea44118ff9425e8b0ebb767d9ed08cee7))
  * Improve wording for box sign (box/box-openapi[#424](https://github.com/box/box-codegen/issues/424)) ([#122](https://github.com/box/box-codegen/issues/122)) ([`64b3bcd`](https://github.com/box/box-codegen/commit/64b3bcd2d99039d1c881a565de6e7bc40dfe7aa9))

  ### New Features and Enhancements

  * Add default implementation for interface methods (box/box-codegen[#502](https://github.com/box/box-codegen/issues/502)) ([#148](https://github.com/box/box-codegen/issues/148)) ([`0f39071`](https://github.com/box/box-codegen/commit/0f39071d2442b9d07f9c51de8a5a757b16cc4fe7))
  * Add docs improvements and marker pagination (box/box-openapi[#431](https://github.com/box/box-codegen/issues/431)) ([#153](https://github.com/box/box-codegen/issues/153)) ([`780a58b`](https://github.com/box/box-codegen/commit/780a58b4d4b18c357381c76dd5e72dd791a20d89))
  * Add support for `ExtraData` of generic type (box/box-codegen[#521](https://github.com/box/box-codegen/issues/521)) ([#170](https://github.com/box/box-codegen/issues/170)) ([`2a2208d`](https://github.com/box/box-codegen/commit/2a2208d422f5beb1718576acdc10d9eb973ba95c))
  * Add support for unions of primitives (box/box-codegen[#501](https://github.com/box/box-codegen/issues/501)) ([#150](https://github.com/box/box-codegen/issues/150)) ([`e75ce82`](https://github.com/box/box-codegen/commit/e75ce82b09641d4bec439d620facbbf25da97845))
  * Make models immutable, hide fields for authentication (box/box-codegen[#494](https://github.com/box/box-codegen/issues/494)) ([#127](https://github.com/box/box-codegen/issues/127)) ([`8adcc85`](https://github.com/box/box-codegen/commit/8adcc858ef0f924f168406b031d379c786fa90d0))
  * Add `SuppressNotifications` and `ExternalSystemName` fields for Box Sign (box/box-openapi[#425](https://github.com/box/box-codegen/issues/425)) ([#124](https://github.com/box/box-codegen/issues/124)) ([`c841881`](https://github.com/box/box-codegen/commit/c841881cea9b0636bb624fe45d77c2817327dd35))
  * Support `StringEnum` (box/box-codegen[#514](https://github.com/box/box-codegen/issues/514)) ([#162](https://github.com/box/box-codegen/issues/162)) ([`6ac2fe9`](https://github.com/box/box-codegen/commit/6ac2fe9811efde6b02cd3ca50834b0bdafea1ab3))
</Update>

<Update label="2024-06-28">
  ## Box Windows SDK v5.7.1 released

  ### Bug Fixes

  * Add missing enum values to `BoxSortBy` ([#953](https://github.com/box/box-windows-sdk-v2/issues/953)) ([`1f89bb0`](https://github.com/box/box-windows-sdk-v2/commit/1f89bb047442dcdc9045aeff1c3d6aadf61e2856)), closes [#952](https://github.com/box/box-windows-sdk-v2/issues/952)
  * Add missing fields of `EventSource` ([#956](https://github.com/box/box-windows-sdk-v2/issues/956)) ([`138eda5`](https://github.com/box/box-windows-sdk-v2/commit/138eda516ad59f08968d88b04e9bb06df3c397f2))
  * do not recreate Random each time ([#945](https://github.com/box/box-windows-sdk-v2/issues/945)) ([`d03b1ce`](https://github.com/box/box-windows-sdk-v2/commit/d03b1ce65d4077e2895acfce3bc286ea501669aa)), closes [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944) [#944](https://github.com/box/box-windows-sdk-v2/issues/944)

  - [https://www.nuget.org/packages/Box.V2/5.7.1>](https://www.nuget.org/packages/Box.V2/5.7.1>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.7.1>](https://www.nuget.org/packages/Box.V2.Core/5.7.1>)
</Update>

<Update label="2024-06-28">
  ## Box Swift SDK Generated 0.3.0 released

  ### Bug Fixes

  * Change base URLs (box/box-codegen[#491](https://github.com/box/box-codegen/issues/491)) ([#115](https://github.com/box/box-codegen/issues/115)) ([`d0a7adb`](https://github.com/box/box-codegen/commit/d0a7adb201c823313f0a5de25fa4fc5469590c97))
  * Fix Box AI endpoints (box/box-openapi[#418](https://github.com/box/box-codegen/issues/418)) ([#88](https://github.com/box/box-codegen/issues/88)) ([`022f83a`](https://github.com/box/box-codegen/commit/022f83aaa7fbe3f4292a06527875123ecc7b99f0))
  * Fix CI for auto update pull requests (box/box-codegen[#506](https://github.com/box/box-codegen/issues/506)) ([#135](https://github.com/box/box-codegen/issues/135)) ([`a62e238`](https://github.com/box/box-codegen/commit/a62e238534cb625dbc98cbe59c98939c78b74f4a))
  * fix deserialisation of Union with array in Swift (box/box-codegen[#486](https://github.com/box/box-codegen/issues/486)) ([#94](https://github.com/box/box-codegen/issues/94)) ([`4f187be`](https://github.com/box/box-codegen/commit/4f187bed1e88c93c1258be8723a39b45129ff21f))
  * Fix metadata filter resource (box/box-openapi[#419](https://github.com/box/box-codegen/issues/419)) ([#90](https://github.com/box/box-codegen/issues/90)) ([`b04f7ce`](https://github.com/box/box-codegen/commit/b04f7ceee9bca4f1f19d66401f38636e7737b4b1))
  * Fix schemas for updating classification on a file and folder (box/box-openapi[#423](https://github.com/box/box-codegen/issues/423)) ([#104](https://github.com/box/box-codegen/issues/104)) ([`caa9d2b`](https://github.com/box/box-codegen/commit/caa9d2b7d0a6c2728f543fa19acb7859f21fb5c9))
  * improve wording for box sign (box/box-openapi[#424](https://github.com/box/box-codegen/issues/424)) ([#111](https://github.com/box/box-codegen/issues/111)) ([`4fa69f0`](https://github.com/box/box-codegen/commit/4fa69f01ca3a2a7fc8dcdc71cbecb03c469a83e6))

  ### New Features and Enhancements

  * add missing marker pagination fields and introduce new event type `(box/box-openapi[#431](https://github.com/box/box-codegen/issues/431))` ([#136](https://github.com/box/box-codegen/issues/136)) ([`b186b11`](https://github.com/box/box-codegen/commit/b186b11a2c591cd4fdd3b50733750a7bb4ec94e9))
  * Add support for `visionOS` and add privacy manifest file for swift `(box/box-codegen[#510](https://github.com/box/box-codegen/issues/510))` ([#139](https://github.com/box/box-codegen/issues/139)) ([`7fc76fc`](https://github.com/box/box-codegen/commit/7fc76fc1799db0a50ad22eb047d013c4597c5277))
  * Add support for Date in Swift (box/box-codegen[#488](https://github.com/box/box-codegen/issues/488)) ([#103](https://github.com/box/box-codegen/issues/103)) ([`7e1ea1a`](https://github.com/box/box-codegen/commit/7e1ea1af553cc8458eb9026c777608f7929e686d))
  * Improve chunk upload in Swift `(box/box-codegen[#515](https://github.com/box/box-codegen/issues/515))` ([#143](https://github.com/box/box-codegen/issues/143)) ([`b8099ab`](https://github.com/box/box-codegen/commit/b8099ab41ea5b8706e14285a0f9db2fd3c0a7a6d))
  * move notification suppression to public schema (box/box-openapi[#425](https://github.com/box/box-codegen/issues/425)) ([#113](https://github.com/box/box-codegen/issues/113)) ([`069be60`](https://github.com/box/box-codegen/commit/069be60613889b45b396bbe22262c5f8df32b158))
  * Move schemas to separate modules (box/box-codegen[#483](https://github.com/box/box-codegen/issues/483)) ([#99](https://github.com/box/box-codegen/issues/99)) ([`c7a8506`](https://github.com/box/box-codegen/commit/c7a85069544c28e2be918eafd9e240f39660ead3))
  * Start throwing common errors `(box/box-codegen[#516](https://github.com/box/box-codegen/issues/516))` ([#147](https://github.com/box/box-codegen/issues/147)) ([`d12bbb7`](https://github.com/box/box-codegen/commit/d12bbb7d06bd3fcf39c31e316f1047065b56baac))
  * Support Box AI endpoints (box/box-openapi[#416](https://github.com/box/box-codegen/issues/416)) ([#86](https://github.com/box/box-codegen/issues/86)) ([`175ab82`](https://github.com/box/box-codegen/commit/175ab82c18dc390bcd4c8e20aea8e405a2e31c4d))
  * Support chunk upload in Swift `(box/box-codegen[#513](https://github.com/box/box-codegen/issues/513))` ([#142](https://github.com/box/box-codegen/issues/142)) ([`9e0b4e2`](https://github.com/box/box-codegen/commit/9e0b4e26a9283b5900ae0fe0fa858394b732f51b))
  * support excluding endpoints and schemas in parser (box/box-codegen[#487](https://github.com/box/box-codegen/issues/487)) ([#100](https://github.com/box/box-codegen/issues/100)) ([`af9e171`](https://github.com/box/box-codegen/commit/af9e171c101703c98ff9a53093d7fc9c306137d9))
</Update>

<Update label="2024-06-12">
  ## Box TypeScript SDK Generated v1.1.0 released

  ### Bug Fixes

  * Fix CI for auto update pull requests (`box/box-codegen`[#506](https://github.com/box/box-typescript-sdk-gen/issues/506)) ([#221](https://github.com/box/box-typescript-sdk-gen/issues/221)) ([`bbc14f6`](https://github.com/box/box-typescript-sdk-gen/commit/bbc14f66e14a9386c8d54a5d0bb36ec2cdc501c1))
  * remove quotation mark when date or `datetime` is used in `queryParams` (box/`box-codegen`[#509](https://github.com/box/box-typescript-sdk-gen/issues/509)) ([#225](https://github.com/box/box-typescript-sdk-gen/issues/225)) ([`28d2220`](https://github.com/box/box-typescript-sdk-gen/commit/28d22200602cf02d73590189c304109f1c26db17))

  ### New Features and Enhancements

  * add missing marker pagination fields and introduce new event type `AppItemEventSource` `(box/box-openapi[#431](https://github.com/box/box-typescript-sdk-gen/issues/431))` ([#224](https://github.com/box/box-typescript-sdk-gen/issues/224)) ([`6c18ca3`](https://github.com/box/box-typescript-sdk-gen/commit/6c18ca3b00da0b878d28e142a2361b6386ef0c15))
</Update>

<Update label="2024-06-12">
  ## Box Python SDK Generated v1.1.0 released

  ### Bug Fixes

  * Fix CI for auto update pull requests (`box/box-codegen`[#506](https://github.com/box/box-codegen/issues/506)) ([#187](https://github.com/box/box-codegen/issues/187)) ([`5e59f69`](https://github.com/box/box-codegen/commit/5e59f69591e01cd2caf0033e0023061093989aa5))

  ### New Features and Enhancements

  * add missing marker pagination fields and introduce new event type `AppItemEventSource` `(box/box-openapi[#431](https://github.com/box/box-codegen/issues/431))` ([#189](https://github.com/box/box-codegen/issues/189)) ([`8d22ce2`](https://github.com/box/box-codegen/commit/8d22ce20d57f4b5dcb5b344ff6bfc67bcaa3568d))
</Update>

<Update label="2024-06-07">
  ## Box Python SDK v3.11.0 released

  ### New Features and Enhancements

  * Use upload session `urls` for chunk upload ([#875](https://github.com/box/box-python-sdk/issues/875)) ([`c67b03c`](https://github.com/box/box-python-sdk/commit/c67b03c7d88533773d62d72f0b626031805d61eb))
</Update>

<Update label="2024-06-06" description="Box Java SDK v4.9.1 released">
  ## Box Java SDK v4.9.1 released

  ### Bug Fixes

  * Bumped `org.bouncycastle:bcprov-jdk18on:1.78.1` and `org.bouncycastle:bcpkix-jdk18on:1.78.1` ([#1246](https://github.com/box/box-java-sdk/issues/1246)) ([`0557bed`](https://github.com/box/box-java-sdk/commit/0557bed2b65d1be717b64a612d74fca73ba21096))
</Update>

<Update label="2024-06-06">
  ## Box Java SDK v4.10.0 released

  ### New Features and Enhancements

  * Overload the `getRepresentationContent` method with a `maxRetries` parameter ([#1251](https://github.com/box/box-java-sdk/issues/1251)) ([`d26bd4f`](https://github.com/box/box-java-sdk/commit/d26bd4f5a141150a372159bc3867abbbbdda1406))
  * Support `login_required`, `password`, `suppress_nofitications`, `verification_phone_number` and `additional_info` fields in sign request ([#1250](https://github.com/box/box-java-sdk/issues/1250)) ([`3ee55b3`](https://github.com/box/box-java-sdk/commit/3ee55b3613c5f5fa92cdd4a17c0cb3e2cc86a9a4))
</Update>

<Update label="2024-06-06">
  ## Box CLI v3.14.1 released

  ### Bug Fixes

  * Fix bulk action in `search` command ([#528](https://github.com/box/boxcli/issues/528)) ([`782b0e6`](https://github.com/box/boxcli/commit/782b0e6b00905d9724289cb05cf03a708c32ebb3))
  * Fix bulk operation for `sign-requests:create` command ([#531](https://github.com/box/boxcli/issues/531)) ([`6d9cd6b`](https://github.com/box/boxcli/commit/6d9cd6b82088185c1b98e8c4ed9ac26af4ee3362))
</Update>

<Update label="2024-05-31">
  ## Box UI Elements v20.0.1-beta.1 released

  ## [`20.0.1-beta.1`](https://github.com/box/box-ui-elements/compare/v20.0.0...v20.0.1-beta.1) (2024-05-31)

  ### Bug Fixes

  * **avatars:** Add type to Fetch avatar ([#3560](https://github.com/box/box-ui-elements/issues/3560)) ([`14a194f`](https://github.com/box/box-ui-elements/commit/14a194f))
</Update>

<Update label="2024-06-18">
  ## PDF.js vulnerability affecting Box Preview SDK

  A `CVE-2024-4367` vulnerability has been identified in the `PDF.js` library used by [Box Preview SDK](https://github.com/box/box-content-preview/blob/master/README.md).
  The vulnerability exposes a gap in the `PDF.js` type, checking code that allows for arbitrary JavaScript to run when opened in Preview.

  Since this vulnerability existed in all versions of `PDF.js` that were lower or equal to `4.1.392`, it affects all versions of Preview SDK lower than `2.106.0`.
  To mitigate this vulnerability, upgrade the Preview SDK used in your apps to `2.106.0` or higher.

  All customers and application owners who are potentially affected have been notified directly via email.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-05-22">
  ## Box UI Elements v20.0.0 released

  ### [20.0.0](https://github.com/box/box-ui-elements/compare/v19.0.0...v20.0.0) (2024-05-22)

  ### Bug Fixes

  * **content-answers:** scope styles to content answers modal ([#3548](https://github.com/box/box-ui-elements/issues/3548)) ([`97d49ff`](https://github.com/box/box-ui-elements/commit/97d49ff))
  * **fonts:** update common fonts version ([#3499](https://github.com/box/box-ui-elements/issues/3499)) ([`870de6d`](https://github.com/box/box-ui-elements/commit/870de6d))
  * **i18n:** update translations ([#3508](https://github.com/box/box-ui-elements/issues/3508)) ([`785be2a`](https://github.com/box/box-ui-elements/commit/785be2a))
  * **i18n:** update translations ([#3509](https://github.com/box/box-ui-elements/issues/3509)) ([`85ebf26`](https://github.com/box/box-ui-elements/commit/85ebf26))
  * **i18n:** update translations ([#3516](https://github.com/box/box-ui-elements/issues/3516)) ([`cb470e9`](https://github.com/box/box-ui-elements/commit/cb470e9))
  * **i18n:** update translations ([#3525](https://github.com/box/box-ui-elements/issues/3525)) ([`ffb447c`](https://github.com/box/box-ui-elements/commit/ffb447c))
  * **i18n:** update translations ([#3528](https://github.com/box/box-ui-elements/issues/3528)) ([`1cf016f`](https://github.com/box/box-ui-elements/commit/1cf016f))
  * **i18n:** update translations ([#3534](https://github.com/box/box-ui-elements/issues/3534)) ([`36e95a9`](https://github.com/box/box-ui-elements/commit/36e95a9))
  * **i18n:** update translations ([#3535](https://github.com/box/box-ui-elements/issues/3535)) ([`c8d03c3`](https://github.com/box/box-ui-elements/commit/c8d03c3))
  * **i18n:** update translations ([#3538](https://github.com/box/box-ui-elements/issues/3538)) ([`cde1b88`](https://github.com/box/box-ui-elements/commit/cde1b88))
  * **i18n:** update translations ([#3540](https://github.com/box/box-ui-elements/issues/3540)) ([`a7043e6`](https://github.com/box/box-ui-elements/commit/a7043e6))
  * **i18n:** update translations ([#3541](https://github.com/box/box-ui-elements/issues/3541)) ([`3ced4a5`](https://github.com/box/box-ui-elements/commit/3ced4a5))
  * **`multiput-upload`:** improve upload performance ([#3512](https://github.com/box/box-ui-elements/issues/3512)) ([`2583e94`](https://github.com/box/box-ui-elements/commit/2583e94))
  * **`npm`:** add chromatic config to `npmignore` ([#3546](https://github.com/box/box-ui-elements/issues/3546)) ([`e2e6731`](https://github.com/box/box-ui-elements/commit/e2e6731))
  * **preview:** Update default preview version to `2.106.0` ([#3555](https://github.com/box/box-ui-elements/issues/3555)) ([`f07d616`](https://github.com/box/box-ui-elements/commit/f07d616))
  * **`react-intl`:** mock date in relative time unit tests ([#3518](https://github.com/box/box-ui-elements/issues/3518)) ([`3ce175b`](https://github.com/box/box-ui-elements/commit/3ce175b))
  * **shared-link-settings-modal:** correct expiration date formatting ([#3545](https://github.com/box/box-ui-elements/issues/3545)) ([`e47892f`](https://github.com/box/box-ui-elements/commit/e47892f))
  * **upload:** improve `multiput` upload performance 2 ([#3517](https://github.com/box/box-ui-elements/issues/3517)) ([`2440746`](https://github.com/box/box-ui-elements/commit/2440746))
  * **usm:** fix item type hubs ([#3532](https://github.com/box/box-ui-elements/issues/3532)) ([`0d1e9cf`](https://github.com/box/box-ui-elements/commit/0d1e9cf))
  * **usm:** hide link description when upsell shows ([#3553](https://github.com/box/box-ui-elements/issues/3553)) ([`838a2e8`](https://github.com/box/box-ui-elements/commit/838a2e8))

  ### Features

  * **content-explorer:** allow not using Portal when rendering modal ([#3501](https://github.com/box/box-ui-elements/issues/3501)) ([`b096d38`](https://github.com/box/box-ui-elements/commit/b096d38))
  * **content-uploader:** Added `allowPrepopulateFiles` prop to content uploader ([#3519](https://github.com/box/box-ui-elements/issues/3519)) ([`12427b1`](https://github.com/box/box-ui-elements/commit/12427b1))
  * **content-uploader:** Implemented partial upload for successful file transfers ([#3529](https://github.com/box/box-ui-elements/issues/3529)) ([`e70825c`](https://github.com/box/box-ui-elements/commit/e70825c))
  * **docgen:** docgen sidebar base ([#3484](https://github.com/box/box-ui-elements/issues/3484)) ([`4b18b21`](https://github.com/box/box-ui-elements/commit/4b18b21))
  * **`react-intl`:** Bump `react-intl` package \[BREAKING CHANGE] ([#3466](https://github.com/box/box-ui-elements/issues/3466)) ([`307c6a4`](https://github.com/box/box-ui-elements/commit/307c6a4))
  * **usm:** Add access level label for hubs ([#3526](https://github.com/box/box-ui-elements/issues/3526)) ([`6504480`](https://github.com/box/box-ui-elements/commit/6504480))
  * **usm:** add inline notice as component ([#3549](https://github.com/box/box-ui-elements/issues/3549)) ([`d646c65`](https://github.com/box/box-ui-elements/commit/d646c65))

  ### BREAKING CHANGES

  * **`react-intl`:** upgrade the major version of the `react-intl` dependency

  * fix: fix `intl` type

  * fix: fix message syntax

  * fix: fix comments and i18n readme file

  * fix: fix `react-intl` version comments

  * fix: use `IntlShape` as a type in js files

  * Fix: correct type import for `IntlShape`

  * fix: add resolution

  * fix: use exact version to match other repositories

  * Fix: correct type import for `IntlShape`

  * fix: remove all support for legacy versions

  * fix: add `relativeTime` helper function

  * fix: fix `relativeTime` in `PresenceAvatarTooltipContent` component

  * fix: fix `relativeTime` in `PresenceCollaborator` component

  * fix: use inclusive inequalities in `relativeTime` helper

  * fix: remove unnecessary modulo operations

  * fix: fix `relativeTime` in `ReadableTime` + fix snapshots

  * fix: fix `relativeTime` in `lastModifiedByCellRenderer`

  * fix: fix tests

  * fix: use js

  * fix: fix import

  * fix: fix else statement

  * fix: revert import reorder
</Update>

<Update label="2024-05-22">
  ## Box Python SDK v3.10.0 released

  ### New Features and Enhancements

  * Transition to stable status ([#872](https://github.com/box/box-python-sdk/issues/872)) ([`6203606`](https://github.com/box/box-python-sdk/commit/620360607a51ee302cde61401db1424c9bf48d81))

  ### Bug Fixes

  * Change exception type for missing location header ([#871](https://github.com/box/box-python-sdk/issues/871)) ([`8c5e0ec`](https://github.com/box/box-python-sdk/commit/8c5e0eca7e494baa8138dceededa2009abc1717b))
  * fix annotation of oauths `access_token` ([#855](https://github.com/box/box-python-sdk/issues/855)) ([`804780e`](https://github.com/box/box-python-sdk/commit/804780e4c8d410590fa20cdb6dd35224d59d2ec0))
  * Fix retention policy integration test ([#867](https://github.com/box/box-python-sdk/issues/867)) ([`8e0d640`](https://github.com/box/box-python-sdk/commit/8e0d6406f26be87799838b0aa57acd62c79d59a2))
  * Remove delete classification ([#861](https://github.com/box/box-python-sdk/issues/861)) ([`393cfef`](https://github.com/box/box-python-sdk/commit/393cfefa57e729f34221a4e5923a4a50532f4013))
  * Update exception file get download URL ([#866](https://github.com/box/box-python-sdk/issues/866)) ([`94dcbcd`](https://github.com/box/box-python-sdk/commit/94dcbcd490d98ff19afd38c9880de8022ad2ec89))
</Update>

<Update label="2024-05-20">
  ## Introducing New Generation Python SDK

  We are excited to introduce [Box Python SDK](https://github.com/box/box-python-sdk-gen), designed to elevate the developer experience and streamline your integration with the Box Content Cloud.

  With the [new generation of Python SDK](https://github.com/box/box-python-sdk-gen), you'll have access to:

  * **Full API Support**: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications.
  * **Rapid API Updates** Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
  * **Embedded Documentation**: We understand that access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process.
  * **Enhanced Convenience Methods**: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers which help to ensure that you’re using variables correctly, and much more.

  Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. Start building innovative solutions faster and more efficiently. Happy coding!
</Update>

<Update label="2024-05-20">
  ## Box Node SDK v3.6.0 released

  ### New Features and Enhancements

  * Transition to stable status ([#880](https://github.com/box/box-node-sdk/issues/880)) ([`ae996ea`](https://github.com/box/box-node-sdk/commit/ae996eafd9e34de99119a7780384b90758908313))
</Update>

<Update label="2024-05-20">
  ## Introducing New Generation TypeScript SDK

  We are excited to introduce [Box TypeScript SDK](https://github.com/box/box-typescript-sdk-gen), designed to elevate the developer experience and streamline your integration with the Box Content Cloud.

  With the [new generation of Typescript SDK](https://github.com/box/box-typescript-sdk-gen), you’ll have access to:

  * **Full API Support**: The new generation of Box SDKs empowers developers with complete coverage of the Box API ecosystem. You can now access all the latest features and functionalities offered by Box, allowing you to build even more sophisticated and feature-rich applications.
  * **Rapid API Updates**: Say goodbye to waiting for new Box APIs to be incorporated into the SDK. With our new auto-generation development approach, we can now add new Box APIs to the SDK at a much faster pace (in a matter of days). This means you can leverage the most up-to-date features in your applications without delay.
  * **Embedded Documentation**: We understand that access to information is crucial for developers. With our new approach, we have included comprehensive documentation for all objects and parameters directly in the source code of the SDK. This means you no longer need to look up this information on the developer portal, saving you time and streamlining your development process.
  * **Enhanced Convenience Methods**: Our commitment to enhancing your development experience continues with the introduction of convenience methods. These methods cover various aspects such as authentication, chunk uploads, exponential back-offs, automatic retries, type checkers which help to ensure that you’re using variables correctly, and much more.

  Embrace the new generation of Box SDKs and unlock the full potential of the Box Content Cloud. Start building innovative solutions faster and more efficiently. Happy coding!
</Update>

<Update label="2024-05-15">
  ## Notification suppression for Box Sign

  [Box Sign API](/reference/post-sign-requests) allows you to suppress the **default** Box email
  notifications sent during the Box Sign workflow.​​

  Thanks to this feature, you can turn the default notifications
  off to use your own, customized messages and decide on channels
  they will be sent through.

  ***Note**: When you choose to suppress email notifications for Box Sign, your organization assumes responsibility for ensuring the delivery to Signers of all notifications at the appropriate time in the signing process and with the appropriate content, in compliance with all applicable laws and regulations, including with respect to obtaining Signer consent to the delivery methods used, if applicable.*

  ## New Box Sign webhooks

  Along with the notification suppression feature, we introduce three new [webhooks](https://developer.box.com/sign/webhooks/) to enhance the customization options for e-signature workflows:

  * `SIGN.REQUEST.SIGNATURE_REQUESTED`
  * `SIGN.REQUEST.SIGNER_SIGNED`
  * `SIGN.REQUEST.ERROR_FINALIZING`

  You can use these webhooks to trigger actions in your own applications or notify your users about events happening in Box Sign.​​

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-05-07">
  ## Box Java SDK v4.9.0 released

  ### New Features and Enhancements

  * Support AI API ([#1243](https://github.com/box/box-java-sdk/issues/1243)) ([`4e64f27`](https://github.com/box/box-java-sdk/commit/4e64f27874fabf36f7fbf385ca4a60683f4a7670))
  * Support pagination of file versions ([#1240](https://github.com/box/box-java-sdk/issues/1240)) ([`7e7af3f`](https://github.com/box/box-java-sdk/commit/7e7af3f6e40a44522a7649817547846e3f633fc8))

  ### Bug Fixes

  * Support create empty shared link ([#1241](https://github.com/box/box-java-sdk/issues/1241)) ([`0c86487`](https://github.com/box/box-java-sdk/commit/0c86487848e5004a713873baffa2d9dcc63b1502))
  * Update exception message for get representation content ([#1239](https://github.com/box/box-java-sdk/issues/1239)) ([`a608f9a`](https://github.com/box/box-java-sdk/commit/a608f9a4350b723e9f07eaf00af45243737a17c9))
</Update>

<Update label="2024-05-03">
  ## Introducing Box AI API and Box AI Dev Zone

  Box AI API allows you to use Box AI functionality in your custom applications. For example, you can implement Box AI question and answer functionality in your third party applications or generate content right in your product’s content editor.

  *Box AI API and Box AI for UI Elements are beta features, which means the available capabilities may change. Box AI features are available to all **Enterprise Plus** customers.*

  Currently, you can ask Box AI to answer your questions, summarize the document content, or generate text you can use in your documents.
  Check the [Box AI API developer guides](https://developer.box.com/guides/box-ai) to learn more about Box AI and check the API Reference for details.

  ## Box AI Developer Zone

  Alongside with the Box AI API, we have launched a new developer documentation demo page. [Box AI Dev Zone](https://developer.box.com/ai) allows you to explore the Box AI API through rich, interactive experiences. You can view use cases, example prompts and responses, and sample code.

  ## Box AI for UI Elements

  [Box AI for UI Elements](/guides/embed/ui-elements/preview#box-ai-ui-element) enhances the [Content Preview](/guides/embed/ui-elements/preview) header with AI Q\&A functionality.
  The new Box AI for UI Elements allows the users to embed AI functionality in their custom applications to facilitate answering questions and taking actions like summarizing a document.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-05-02">
  ## Box Node SDK v3.5.1 released

  ### Bug Fixes

  * Fix `options` parameter in metadata query method ([#878](https://github.com/box/box-node-sdk/issues/878)) ([`7943420`](https://github.com/box/box-node-sdk/commit/79434209c572cd77c329d6008cda9837a9dba411))
</Update>

<Update label="2024-04-05">
  ## Box iOS SDK v5.6.0 released

  ### New Features and Enhancements

  * Add privacy manifest files ([#924](https://github.com/box/box-ios-sdk/issues/924)) ([`cbef168`](https://github.com/box/box-ios-sdk/commit/cbef168bb872941899be26116c647ac29f5dd44b))
  * Add support for `visionOS` ([#916](https://github.com/box/box-ios-sdk/issues/916)) ([`a05b243`](https://github.com/box/box-ios-sdk/commit/a05b2433f1b2d0c1ec72f946e0706d03a4548703))
  * Add support for additional fields in `SignRequest` ([#919](https://github.com/box/box-ios-sdk/issues/919)) ([`36f464c`](https://github.com/box/box-ios-sdk/commit/36f464c23a161f5d0fcc6858c3615d884ce8ee07))
  * Make fields from `TokenInfo` publicly available ([#920](https://github.com/box/box-ios-sdk/issues/920)) ([`eb26f47`](https://github.com/box/box-ios-sdk/commit/eb26f47bbde6749f44f149e95b3610e41c16d2f2))
</Update>

<Update label="2024-03-06">
  ## Box CLI v3.14.0 released

  ### New Features and Enhancements

  * Add support for `vanity_name` when creating `shared-links` ([#524](https://github.com/box/boxcli/issues/524)) ([`38164bc`](https://github.com/box/boxcli/commit/38164bc716879aef0a8a2b973a9c6fc7eb705978))
  * Support sign request signer group ID ([#521](https://github.com/box/boxcli/issues/521)) ([`f7b1b44`](https://github.com/box/boxcli/commit/f7b1b4409e0f72c264cc23a0f1ca1849060bf121))
</Update>

<Update label="2024-02-27">
  ## Box Windows SDK v5.7.0 released

  ### New Features and Enhancements

  * add marker-based pagination version of `GetFolderItems` ([#936](https://github.com/box/box-windows-sdk-v2/issues/936)) ([`f877a8f`](https://github.com/box/box-windows-sdk-v2/commit/f877a8f9105d65a3e3ca459fcbf4a1bb653ff0f3))
  * Support sign request signer group ID ([#938](https://github.com/box/box-windows-sdk-v2/issues/938)) ([`096a098`](https://github.com/box/box-windows-sdk-v2/commit/096a09805b189c591289e77ae5f8a8e6f1b466f1))

  ### Bug Fixes

  * Remove delete classification ([#932](https://github.com/box/box-windows-sdk-v2/issues/932)) ([`fb59489`](https://github.com/box/box-windows-sdk-v2/commit/fb594897850ad9daacf75cab702f3765cc7168c0))

  - [https://www.nuget.org/packages/Box.V2/5.7.0>](https://www.nuget.org/packages/Box.V2/5.7.0>)
  - [https://www.nuget.org/packages/Box.V2.Core/5.7.0>](https://www.nuget.org/packages/Box.V2.Core/5.7.0>)
</Update>

<Update label="2024-02-27">
  ## Box Java SDK v4.8.0 released

  ### New Features and Enhancements

  * allow modifying `BoxAPIRequest` URL ([#1236](https://github.com/box/box-java-sdk/issues/1236)) ([`eaea019`](https://github.com/box/box-java-sdk/commit/eaea0193ab7e72b73746ea85806e62468825bbce))
  * Bumped `org.bouncycastle:bcprov-jdk18on:1.77` and `org.bouncycastle:bcpkix-jdk18on:1.77` ([#1237](https://github.com/box/box-java-sdk/issues/1237)) ([`6c7fe7b`](https://github.com/box/box-java-sdk/commit/6c7fe7b74dbfb34e729fcecf8a29a1d3a1ba596f)), closes [#1235](https://github.com/box/box-java-sdk/issues/1235)

  ### Bug Fixes

  * fix download for empty files ([#1231](https://github.com/box/box-java-sdk/issues/1231)) ([`0e2230b`](https://github.com/box/box-java-sdk/commit/0e2230b0be36f6bfb35f1d6b9dd4ba58e4d125ec))
  * stop using `SharedLinkAPIConnection` in `getSharedItem()` ([#1234](https://github.com/box/box-java-sdk/issues/1234)) ([`9f9af8e`](https://github.com/box/box-java-sdk/commit/9f9af8e22b4a38dc9a31a611ff1b962966bbd6b5))
</Update>

<Update label="2024-02-22">
  ## Box CLI v3.13.0 released

  ### New Features and Enhancements

  * Add additional `UseDisplayName` flag to metadata extraction script ([#515](https://github.com/box/boxcli/issues/515)) ([`b900fdb`](https://github.com/box/boxcli/commit/b900fdb984345c0fdfeb09e531f6a358ad8c3b8e))
  * Add additional context info when throw exception ([#519](https://github.com/box/boxcli/issues/519)) ([`b99a58d`](https://github.com/box/boxcli/commit/b99a58d930eccf5363c82b84e4415336d7d69541))
  * Support overwrite/skip folder download ([#516](https://github.com/box/boxcli/issues/516)) ([`300f914`](https://github.com/box/boxcli/commit/300f914ba8bb94d9c399699d126d81aba0b22142))

  ### Bug Fixes

  * Fix metadata extraction script ([#514](https://github.com/box/boxcli/issues/514)) ([`2fad540`](https://github.com/box/boxcli/commit/2fad540badf60538fe1456f8071b74bf917f7464))
  * Fix the functionality of the overwrite flag ([#513](https://github.com/box/boxcli/issues/513)) ([`f4bf7af`](https://github.com/box/boxcli/commit/f4bf7af8e0bbdf7e73fab23d920259ef16672be0))
</Update>

<Update label="2024-02-19">
  ## Box Node SDK v3.5.0 released

  ### New Features and Enhancements

  * Sign request group ([#870](https://github.com/box/box-node-sdk/issues/870)) ([`11bf5d2`](https://github.com/box/box-node-sdk/commit/11bf5d2db7e0cefc669aab99c8b65c632289ac46))

  ### Bug Fixes

  * Bumped proxy-agent to 6.4.0 ([#874](https://github.com/box/box-node-sdk/issues/874)) ([`55a8a0b`](https://github.com/box/box-node-sdk/commit/55a8a0baebe151f4107fdbec0a1022e9534f88a4))
  * Remove delete classification ([#869](https://github.com/box/box-node-sdk/issues/869)) ([`22384ab`](https://github.com/box/box-node-sdk/commit/22384abc3abbc35800cbcdea7c7eb9a452cc4859))
</Update>

<Update label="2024-02-06">
  ## Working with Box Sign

  We are thrilled to announce the release of our new dedicated resource page [Working with the Box Sign API](https://developer.box.com/sign/). This comprehensive guide is designed to help you seamlessly integrate Box Sign into your applications, providing you with the tools and knowledge to make the most out of this powerful e-signature solution.

  ## Table of content

  * [Quick start](https://developer.box.com/sign/quick-start/)
  * [Technical use cases](https://developer.box.com/sign/technical-use-cases/)
  * [Signature request options](https://developer.box.com/sign/request-options/)
  * [Webhooks](https://developer.box.com/sign/webhooks/)
  * [Workshops](https://github.com/barduinor/box-python-gen-workshop/blob/main/workshops/sign/sign.md)
</Update>

<Update label="2024-02-02">
  ## Metadata view in Content Explorer

  Content Explorer comes with a metadata view that uses metadata query to find files and folders. The data is then displayed in the embedded view.

  For details, read the [Content Explorer guide](/guides/embed/ui-elements/explorer) and our [blog post](https://medium.com/box-developer-blog/metadata-view-in-box-content-explorer-4978e47e97e9).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-01-25">
  ## Box UI Elements v19.0.0 released

  ### [19.0.0](https://github.com/box/box-ui-elements/compare/v18.1.0...v19.0.0) (2024-01-25)

  ### Bug Fixes

  * **activity-feed-zoom:** add a min-height prop to the items container ([#3411](https://github.com/box/box-ui-elements/issues/3411)) ([`a60a70d`](https://github.com/box/box-ui-elements/commit/a60a70d))
  * **button:** add aria labels for accessibility ([#3377](https://github.com/box/box-ui-elements/issues/3377)) ([`9a9b5e3`](https://github.com/box/box-ui-elements/commit/9a9b5e3))
  * **content-answers:** add `bdl` prefix into the styles ([#3421](https://github.com/box/box-ui-elements/issues/3421)) ([`fdbfc4d`](https://github.com/box/box-ui-elements/commit/fdbfc4d))
  * **content-explorer:** allow `onDelete` callback to be success on 404 ([#3468](https://github.com/box/box-ui-elements/issues/3468)) ([`13ed6da`](https://github.com/box/box-ui-elements/commit/13ed6da))
  * **content-explorer:** detect if device supports downloading ([#3480](https://github.com/box/box-ui-elements/issues/3480)) ([`fa68f9b`](https://github.com/box/box-ui-elements/commit/fa68f9b))
  * **content-explorer:** fix text ellipsis in breadcrumbs ([#3481](https://github.com/box/box-ui-elements/issues/3481)) ([`6099b1d`](https://github.com/box/box-ui-elements/commit/6099b1d))
  * **content-explorer:** Remove lingering `contentPreviewProps` ([#3489](https://github.com/box/box-ui-elements/issues/3489)) ([`4181e0c`](https://github.com/box/box-ui-elements/commit/4181e0c))
  * **content-explorer:** show pagination count for small devices ([#3498](https://github.com/box/box-ui-elements/issues/3498)) ([`98537b9`](https://github.com/box/box-ui-elements/commit/98537b9))
  * **content-picker:** use pagination component to import correct styles ([#3472](https://github.com/box/box-ui-elements/issues/3472)) ([`6aef87b`](https://github.com/box/box-ui-elements/commit/6aef87b))
  * **content-sidebar:** increase z-index to stack above annotations ([#3478](https://github.com/box/box-ui-elements/issues/3478)) ([`762b82d`](https://github.com/box/box-ui-elements/commit/762b82d))
  * **content-uploader:** add text ellipsis and adjust spacing ([#3479](https://github.com/box/box-ui-elements/issues/3479)) ([`36df228`](https://github.com/box/box-ui-elements/commit/36df228))
  * **flyout:** set default role for Flyout to 'dialog' ([#3388](https://github.com/box/box-ui-elements/issues/3388)) ([`942f6b7`](https://github.com/box/box-ui-elements/commit/942f6b7))
  * **i18n:** update translations ([#3396](https://github.com/box/box-ui-elements/issues/3396)) ([`2175a82`](https://github.com/box/box-ui-elements/commit/2175a82))
  * **i18n:** update translations ([#3398](https://github.com/box/box-ui-elements/issues/3398)) ([`4d71c62`](https://github.com/box/box-ui-elements/commit/4d71c62))
  * **i18n:** update translations ([#3401](https://github.com/box/box-ui-elements/issues/3401)) ([`0911005`](https://github.com/box/box-ui-elements/commit/0911005))
  * **i18n:** update translations ([#3409](https://github.com/box/box-ui-elements/issues/3409)) ([`4c95746`](https://github.com/box/box-ui-elements/commit/4c95746))
  * **i18n:** update translations ([#3413](https://github.com/box/box-ui-elements/issues/3413)) ([`65eb428`](https://github.com/box/box-ui-elements/commit/65eb428))
  * **i18n:** update translations ([#3417](https://github.com/box/box-ui-elements/issues/3417)) ([`9aab003`](https://github.com/box/box-ui-elements/commit/9aab003))
  * **i18n:** update translations ([#3422](https://github.com/box/box-ui-elements/issues/3422)) ([`523492a`](https://github.com/box/box-ui-elements/commit/523492a))
  * **i18n:** update translations ([#3430](https://github.com/box/box-ui-elements/issues/3430)) ([`7b705bc`](https://github.com/box/box-ui-elements/commit/7b705bc))
  * **i18n:** update translations ([#3433](https://github.com/box/box-ui-elements/issues/3433)) ([`0e8decb`](https://github.com/box/box-ui-elements/commit/0e8decb))
  * **i18n:** update translations ([#3434](https://github.com/box/box-ui-elements/issues/3434)) ([`15e2e2e`](https://github.com/box/box-ui-elements/commit/15e2e2e))
  * **i18n:** update translations ([#3437](https://github.com/box/box-ui-elements/issues/3437)) ([`0d06403`](https://github.com/box/box-ui-elements/commit/0d06403))
  * **i18n:** update translations ([#3438](https://github.com/box/box-ui-elements/issues/3438)) ([`a6f4868`](https://github.com/box/box-ui-elements/commit/a6f4868))
  * **i18n:** update translations ([#3452](https://github.com/box/box-ui-elements/issues/3452)) ([`22bb031`](https://github.com/box/box-ui-elements/commit/22bb031))
  * **i18n:** update translations ([#3453](https://github.com/box/box-ui-elements/issues/3453)) ([`85d2521`](https://github.com/box/box-ui-elements/commit/85d2521))
  * **i18n:** update translations ([#3454](https://github.com/box/box-ui-elements/issues/3454)) ([`e83185e`](https://github.com/box/box-ui-elements/commit/e83185e))
  * **i18n:** update translations ([#3455](https://github.com/box/box-ui-elements/issues/3455)) ([`a10aa5c`](https://github.com/box/box-ui-elements/commit/a10aa5c))
  * **i18n:** update translations ([#3456](https://github.com/box/box-ui-elements/issues/3456)) ([`41ad809`](https://github.com/box/box-ui-elements/commit/41ad809))
  * **i18n:** update translations ([#3457](https://github.com/box/box-ui-elements/issues/3457)) ([`b3f57ff`](https://github.com/box/box-ui-elements/commit/b3f57ff))
  * **i18n:** update translations ([#3458](https://github.com/box/box-ui-elements/issues/3458)) ([`a1c42d7`](https://github.com/box/box-ui-elements/commit/a1c42d7))
  * **i18n:** update translations ([#3459](https://github.com/box/box-ui-elements/issues/3459)) ([`1b6f4c2`](https://github.com/box/box-ui-elements/commit/1b6f4c2))
  * **i18n:** update translations ([#3462](https://github.com/box/box-ui-elements/issues/3462)) ([`13fc9b0`](https://github.com/box/box-ui-elements/commit/13fc9b0))
  * **i18n:** update translations ([#3464](https://github.com/box/box-ui-elements/issues/3464)) ([`d1a888d`](https://github.com/box/box-ui-elements/commit/d1a888d))
  * **i18n:** update translations ([#3465](https://github.com/box/box-ui-elements/issues/3465)) ([`5413089`](https://github.com/box/box-ui-elements/commit/5413089))
  * **i18n:** update translations ([#3469](https://github.com/box/box-ui-elements/issues/3469)) ([`2ffe17f`](https://github.com/box/box-ui-elements/commit/2ffe17f))
  * **i18n:** update translations ([#3470](https://github.com/box/box-ui-elements/issues/3470)) ([`1139bb0`](https://github.com/box/box-ui-elements/commit/1139bb0))
  * **i18n:** update translations ([#3471](https://github.com/box/box-ui-elements/issues/3471)) ([`41e02db`](https://github.com/box/box-ui-elements/commit/41e02db))
  * **modal-dialog:** add aria-modal to `ModalDialog` ([#3380](https://github.com/box/box-ui-elements/issues/3380)) ([`c8f8509`](https://github.com/box/box-ui-elements/commit/c8f8509))
  * **modify-reply:** Map object to parameters ([#3387](https://github.com/box/box-ui-elements/issues/3387)) ([`3989675`](https://github.com/box/box-ui-elements/commit/3989675))
  * **preview:** Add accessibility to annotation badge type icon ([#3404](https://github.com/box/box-ui-elements/issues/3404)) ([`d4b7852`](https://github.com/box/box-ui-elements/commit/d4b7852))
  * **preview:** Change focus indicator for actions in version panel ([#3397](https://github.com/box/box-ui-elements/issues/3397)) ([`f111c64`](https://github.com/box/box-ui-elements/commit/f111c64))
  * **preview:** Ensure promoted-by field shows correct user ([#3414](https://github.com/box/box-ui-elements/issues/3414)) ([`458fdbf`](https://github.com/box/box-ui-elements/commit/458fdbf))
  * **preview:** extending HOC to not override `onDismiss` callback ([#3431](https://github.com/box/box-ui-elements/issues/3431)) ([`4cc57a3`](https://github.com/box/box-ui-elements/commit/4cc57a3))
  * **search-form:** extract search actions component ([#3475](https://github.com/box/box-ui-elements/issues/3475)) ([`8d77320`](https://github.com/box/box-ui-elements/commit/8d77320))
  * deactivate copy in `textInputWithCopyButton` when button is deactivated ([#3419](https://github.com/box/box-ui-elements/issues/3419)) ([`68b2def`](https://github.com/box/box-ui-elements/commit/68b2def))
  * hide uploads manager progress bar for screen-readers if not visible ([#3383](https://github.com/box/box-ui-elements/issues/3383)) ([`5592a48`](https://github.com/box/box-ui-elements/commit/5592a48))
  * remove `core-js` from examples wrapper ([#3392](https://github.com/box/box-ui-elements/issues/3392)) ([`48ccdf7`](https://github.com/box/box-ui-elements/commit/48ccdf7))
  * remove internal boxer names ([#3390](https://github.com/box/box-ui-elements/issues/3390)) ([`65cc5cb`](https://github.com/box/box-ui-elements/commit/65cc5cb))
  * **preview-sidebar:** fix preview versions behavior ([#3203](https://github.com/box/box-ui-elements/issues/3203)) ([`d940782`](https://github.com/box/box-ui-elements/commit/d940782))
  * update source paths for test pages ([#3378](https://github.com/box/box-ui-elements/issues/3378)) ([`ff6b349`](https://github.com/box/box-ui-elements/commit/ff6b349))

  ### Features

  * **aci:** add `ACI` config to features prop ([#3410](https://github.com/box/box-ui-elements/issues/3410)) ([`e95a35e`](https://github.com/box/box-ui-elements/commit/e95a35e))
  * **activityitems:** new layout ([#3405](https://github.com/box/box-ui-elements/issues/3405)) ([`665d30a`](https://github.com/box/box-ui-elements/commit/665d30a))
  * **annotations:** editing an annotation reply ([#3412](https://github.com/box/box-ui-elements/issues/3412)) ([`025ad7e`](https://github.com/box/box-ui-elements/commit/025ad7e))
  * **assets:** add Box AI assets ([#3393](https://github.com/box/box-ui-elements/issues/3393)) ([`bc6b04d`](https://github.com/box/box-ui-elements/commit/bc6b04d))
  * **content-answers:** add `contentAnswers` Modal header and footer ([#3403](https://github.com/box/box-ui-elements/issues/3403)) ([`a7d0a3e`](https://github.com/box/box-ui-elements/commit/a7d0a3e))
  * **content-answers:** add inline error ([#3444](https://github.com/box/box-ui-elements/issues/3444)) ([`405cdb4`](https://github.com/box/box-ui-elements/commit/405cdb4))
  * **content-answers:** add modal body with initial welcome message ([#3415](https://github.com/box/box-ui-elements/issues/3415)) ([`6748e73`](https://github.com/box/box-ui-elements/commit/6748e73))
  * **content-answers:** add prop to control displaying `contentAnswers` ([#3399](https://github.com/box/box-ui-elements/issues/3399)) ([`f0b0922`](https://github.com/box/box-ui-elements/commit/f0b0922))
  * **content-answers:** add scrolling to bottom ([#3442](https://github.com/box/box-ui-elements/issues/3442)) ([`59c8c45`](https://github.com/box/box-ui-elements/commit/59c8c45))
  * **content-answers:** Avatar ([#3418](https://github.com/box/box-ui-elements/issues/3418)) ([`45166f4`](https://github.com/box/box-ui-elements/commit/45166f4))
  * **content-answers:** button focusing ([#3448](https://github.com/box/box-ui-elements/issues/3448)) ([`2358321`](https://github.com/box/box-ui-elements/commit/2358321))
  * **content-answers:** Content Answers Modal Error ([#3425](https://github.com/box/box-ui-elements/issues/3425)) ([`a5084a5`](https://github.com/box/box-ui-elements/commit/a5084a5))
  * **content-answers:** create initial content-answers modal button component ([#3395](https://github.com/box/box-ui-elements/issues/3395)) ([`217a393`](https://github.com/box/box-ui-elements/commit/217a393))
  * **content-answers:** Deactivate button when not allowed file type ([#3406](https://github.com/box/box-ui-elements/issues/3406)) ([`f950772`](https://github.com/box/box-ui-elements/commit/f950772))
  * **content-answers:** intelligence API ([#3420](https://github.com/box/box-ui-elements/issues/3420)) ([`76fd991`](https://github.com/box/box-ui-elements/commit/76fd991))
  * **content-answers:** Questions Answers Intelligence endpoint ([#3435](https://github.com/box/box-ui-elements/issues/3435)) ([`4c7c0c0`](https://github.com/box/box-ui-elements/commit/4c7c0c0))
  * **content-answers:** retry button ([#3451](https://github.com/box/box-ui-elements/issues/3451)) ([`e0976b8`](https://github.com/box/box-ui-elements/commit/e0976b8))
  * **content-explorer:** Add auto selected items to content explorer ([#3474](https://github.com/box/box-ui-elements/issues/3474)) ([`215cfdd`](https://github.com/box/box-ui-elements/commit/215cfdd))
  * **content-sidebar:** enable responsiveness for Preview and Sidebar ([#3497](https://github.com/box/box-ui-elements/issues/3497)) ([`1652982`](https://github.com/box/box-ui-elements/commit/1652982))
  * **label-primitive:** pass properties to label ([#3473](https://github.com/box/box-ui-elements/issues/3473)) ([`7e88772`](https://github.com/box/box-ui-elements/commit/7e88772))
  * **modal:** enable responsive behavior ([#3492](https://github.com/box/box-ui-elements/issues/3492)) ([`7fe59b8`](https://github.com/box/box-ui-elements/commit/7fe59b8))
  * **pill-selector:** added more options for text input ([#3440](https://github.com/box/box-ui-elements/issues/3440)) ([`d782e4a`](https://github.com/box/box-ui-elements/commit/d782e4a))
  * **preview:** Focus on comment form for replies and modifying ([#3407](https://github.com/box/box-ui-elements/issues/3407)) ([`69293d8`](https://github.com/box/box-ui-elements/commit/69293d8))
  * **threaded-replies:** added resolve/unresolve for annotations ([#3423](https://github.com/box/box-ui-elements/issues/3423)) ([`c489ad3`](https://github.com/box/box-ui-elements/commit/c489ad3))
  * **threaded-replies:** delete threaded reply comments ([#3402](https://github.com/box/box-ui-elements/issues/3402)) ([`37437c5`](https://github.com/box/box-ui-elements/commit/37437c5))
  * **uaa-integration:** Handle no comment permission ([#3394](https://github.com/box/box-ui-elements/issues/3394)) ([`5a28b49`](https://github.com/box/box-ui-elements/commit/5a28b49))
  * **uaa-integration:** Parse App Activity item ([#3386](https://github.com/box/box-ui-elements/issues/3386)) ([`44fd12b`](https://github.com/box/box-ui-elements/commit/44fd12b))
  * **uaa-integration:** Parse Versions Response from UAA ([#3385](https://github.com/box/box-ui-elements/issues/3385)) ([`0fa730f`](https://github.com/box/box-ui-elements/commit/0fa730f))
  * **usm:** enable responsive behavior ([#3494](https://github.com/box/box-ui-elements/issues/3494)) ([`76db2a5`](https://github.com/box/box-ui-elements/commit/76db2a5))
  * remove browser support for IE11 ([#3382](https://github.com/box/box-ui-elements/issues/3382)) ([`e151c87`](https://github.com/box/box-ui-elements/commit/e151c87))

  ### Reverts

  * "chore(codeowners): updated codeowners temporarily ([#3446](https://github.com/box/box-ui-elements/issues/3446))" ([#3476](https://github.com/box/box-ui-elements/issues/3476)) ([`3e38fa5`](https://github.com/box/box-ui-elements/commit/3e38fa5))

  ### BREAKING CHANGES

  * Internet Explorer 11 is no longer supported
</Update>

<Update label="2024-01-19">
  ## New event parameter for Shield Suspicious Location alert

  Along with the release of Shield Suspicious Location: Automated Response we added `rule_response_action` parameter in the [Shield Alert Event](/guides/events/event-triggers/shield-alert-events/#suspicious-locations-alert) response.
  This parameter is returned in the payload of each Shield Alert Event, but applicable only to **Suspicious Locations** alert event.

  The value of the parameter depends on the **Restrict Target User Access** rule settings in the Admin Console.

  * If active, the value of the parameter will be `true` when the alert is triggered.
  * If inactive, the value of the parameter will be `false` when the alert is triggered.

  For all other Shield Alerts (**Anomalous Download**, **Malicious Content**, **Suspicious Session**), the `rule_response_action` parameter is always `null`.

  For additional information, see [Suspicious Location rule settings](https://support.box.com/hc/en-us/articles/9090542213395-Shield-Threat-Detection-Rule-Settings#h_01GE85EWQ1TS5APY7RGN801QSC)

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2024-01-16">
  ## Box Java SDK v4.7.0 released

  ### New Features and Enhancements

  * Add `signer_group_id` for signer in sign request ([#1220](https://github.com/box/box-java-sdk/issues/1220)) ([`f560db8`](https://github.com/box/box-java-sdk/commit/f560db8d5587406099066803789d16374ec7dbb9))
  * Upgrade `BouncyCastle` to v.`1.70`.
    > **NOTE**: A new `BouncyCastle` version is not compliant with FIPS.
  * Introduce `IPrivateKeyDecryptor` to allow using custom cryptography provider ([#1226](https://github.com/box/box-java-sdk/issues/1226)) ([`727e6d7`](https://github.com/box/box-java-sdk/commit/727e6d71ee375a48b4241a26a093becfe0965898))

  ### Bug Fixes

  * Remove delete classification ([#1222](https://github.com/box/box-java-sdk/issues/1222)) ([`9814038`](https://github.com/box/box-java-sdk/commit/981403896b4cd16a42c9feeecf30e75e1e8fa072))
</Update>


# 2025
Source: https://developer.box.com/changelog/2025

Box Platform changelog: API, SDK, and product updates from 2025.

<Update label="2025-12-29">
  ## ChatGPT for remote Box MCP server released

  We’ve added the ability to [integrate ChatGPT with the Remote Box MCP Server](https://support.box.com/hc/en-us). This allows ChatGPT to securely access Box content through a custom Model Context Protocol (MCP) connector using OAuth and the MCP.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-12-19">
  ## Box Node SDK `v4.3.0` released

  ### Bug Fixes

  * **boxsdkgen:** add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-node-sdk/issues/572)) ([#1274](https://github.com/box/box-node-sdk/issues/1274)) ([`3850e6b`](https://github.com/box/box-node-sdk/commit/3850e6bf164d1a8778258afb54342833366a0b03))
  * **boxsdkgen:** fix `RetryAfter` function when there's no `Retry-After` header (box/box-codegen[#903](https://github.com/box/box-node-sdk/issues/903)) ([#1250](https://github.com/box/box-node-sdk/issues/1250)) ([`cd917ee`](https://github.com/box/box-node-sdk/commit/cd917eec7f785627952cebc32313ec192ade982f))

  ### New Features and Enhancements

  * **boxsdkgen:** add Metadata Taxonomies api (box/box-openapi[#569](https://github.com/box/box-node-sdk/issues/569)) ([#1256](https://github.com/box/box-node-sdk/issues/1256)) ([`12d8c9f`](https://github.com/box/box-node-sdk/commit/12d8c9f5a9748f871b1ca492b3acd388d103039f))
  * **boxsdkgen:** text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-node-sdk/issues/568)) ([#1253](https://github.com/box/box-node-sdk/issues/1253)) ([`5d4f8bf`](https://github.com/box/box-node-sdk/commit/5d4f8bf8ea3ca433c18150a0d4b474ec85ddc0ef))
  * **boxsdkgen:** treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-node-sdk/issues/906)) ([#1259](https://github.com/box/box-node-sdk/issues/1259)) ([`50d7080`](https://github.com/box/box-node-sdk/commit/50d70806c4e40ed56b2f8cfea5f5bcec7ec56159))
  * reuse auth and network settings between legacy and sdk-gen ([#1242](https://github.com/box/box-node-sdk/issues/1242)) ([`320c35e`](https://github.com/box/box-node-sdk/commit/320c35e8d4add6407cebc0d43bb7522fa980e9cf))
</Update>

<Update label="2025-12-19">
  ## Box Node SDK `v10.3.0` released

  ### Bug Fixes

  * Add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-node-sdk/issues/572)) ([#1269](https://github.com/box/box-node-sdk/issues/1275)) ([`7bb9bdc`](https://github.com/box/box-node-sdk/commit/0935d7116e0c5f7e0e4bc38f6a9f46344acaccba))
  * Fix `RetryAfter` function when there's no `Retry-After` header (box/box-codegen[#903](https://github.com/box/box-node-sdk/issues/903)) ([#1244](https://github.com/box/box-node-sdk/issues/1251)) ([`d7cc019`](https://github.com/box/box-node-sdk/commit/a334d81190d9f90c7c1cec5cee8187f1cd18dac9))

  ### New Features and Enhancements

  * Add Metadata Taxonomies API (box/box-openapi[#569](https://github.com/box/box-node-sdk/issues/569)) ([#1252](https://github.com/box/box-node-sdk/issues/1263)) ([`7850463`](https://github.com/box/box-node-sdk/commit/ee11f678724912ebf862edc47c4ab1a2ea348f2b))
  * Text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-node-sdk/issues/568)) ([#1246](https://github.com/box/box-node-sdk/issues/1260)) ([`f99512f`](https://github.com/box/box-node-sdk/commit/868690186705d657b2af07d8fb45a4e4b99b7877))
  * Treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-node-sdk/issues/906)) ([#1256](https://github.com/box/box-node-sdk/issues/1265)) ([`12c05dc`](https://github.com/box/box-node-sdk/commit/91d0c74f488948772e29116e668b69d2bdbbc1c8))
</Update>

<Update label="2025-12-19">
  ## Box Python SDK `v4.3.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** add Metadata Taxonomies api (box/box-openapi[#569](https://github.com/box/box-python-sdk/issues/569)) ([#1251](https://github.com/box/box-python-sdk/issues/1251)) ([`ebda615`](https://github.com/box/box-python-sdk/commit/ebda6156dabe997172d4fc28e8d279d2726147ad))
  * **boxsdkgen:** text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-python-sdk/issues/568)) ([#1245](https://github.com/box/box-python-sdk/issues/1245)) ([`974e9b3`](https://github.com/box/box-python-sdk/commit/974e9b3e39e48dbdcecea5936c6a4abab1ee3a0f))
  * **boxsdkgen:** treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-python-sdk/issues/906)) ([#1255](https://github.com/box/box-python-sdk/issues/1255)) ([`0c9929b`](https://github.com/box/box-python-sdk/commit/0c9929b48cf2c1386280f5290ddb9b74bafc399b))

  ### Bug Fixes

  * **boxsdkgen:** add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-python-sdk/issues/572)) ([#1267](https://github.com/box/box-python-sdk/issues/1267)) ([`d97f493`](https://github.com/box/box-python-sdk/commit/d97f493e29dd3dce349f3ee953784381b383e99e))
  * **boxsdkgen:** fix `RetryAfter` function when there's no Retry-After header (box/box-codegen[#903](https://github.com/box/box-python-sdk/issues/903)) ([#1243](https://github.com/box/box-python-sdk/issues/1243)) ([`4371cf3`](https://github.com/box/box-python-sdk/commit/4371cf3225e9c4e241d1feb62f94bddb61c4fc5e))
</Update>

<Update label="2025-12-19">
  ## Box Windows SDK `v6.4.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** add Metadata Taxonomies api (box/box-openapi[#569](https://github.com/box/box-windows-sdk-v2/issues/569)) ([#1329](https://github.com/box/box-windows-sdk-v2/issues/1329)) ([`5908cf2`](https://github.com/box/box-windows-sdk-v2/commit/5908cf22ffeb8c14bb727d44fd58b57a3f7d6ea0))
  * **boxsdkgen:** text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-windows-sdk-v2/issues/568)) ([#1323](https://github.com/box/box-windows-sdk-v2/issues/1323)) ([`d094726`](https://github.com/box/box-windows-sdk-v2/commit/d094726711e982b889d6caa4378736cb3dde673a))
  * **boxsdkgen:** treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-windows-sdk-v2/issues/906)) ([#1333](https://github.com/box/box-windows-sdk-v2/issues/1333)) ([`1b61619`](https://github.com/box/box-windows-sdk-v2/commit/1b61619142c0896856791a12cae709d5d0d138f6))

  ### **Bug Fixes:**

  * **boxsdkgen:** add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-windows-sdk-v2/issues/572)) ([#1343](https://github.com/box/box-windows-sdk-v2/issues/1343)) ([`8152df7`](https://github.com/box/box-windows-sdk-v2/commit/8152df75926b0ee5bad504b0707adb31f099ef9b))
  * **boxsdkgen:** fix convert to long in CSharp (box/box-codegen[#911](https://github.com/box/box-windows-sdk-v2/issues/911)) ([#1354](https://github.com/box/box-windows-sdk-v2/issues/1354)) ([`25433e5`](https://github.com/box/box-windows-sdk-v2/commit/25433e5a1044cc36ebdb604b4ead55d0db5d1158))
</Update>

<Update label="2025-12-19">
  ## Box Windows SDK `v10.5.0` released

  ### Bug Fixes

  * add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-windows-sdk-v2/issues/572)) ([#1344](https://github.com/box/box-windows-sdk-v2/issues/1344)) ([`03aea9b`](https://github.com/box/box-windows-sdk-v2/commit/03aea9b2aee4ff98d91d0ebdb477e8ebaa3ee22d))
  * fix convert to long in CSharp (box/box-codegen[#911](https://github.com/box/box-windows-sdk-v2/issues/911)) ([#1353](https://github.com/box/box-windows-sdk-v2/issues/1353)) ([`aacee77`](https://github.com/box/box-windows-sdk-v2/commit/aacee77366a76d18afbd1e7c19600ee4ddd21b54))

  ### New Features and Enhancements

  * add Metadata Taxonomies api (box/box-openapi[#569](https://github.com/box/box-windows-sdk-v2/issues/569)) ([#1330](https://github.com/box/box-windows-sdk-v2/issues/1330)) ([`e054a76`](https://github.com/box/box-windows-sdk-v2/commit/e054a76609c710a92d998ee1b8622edf495b7bc0))
  * text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-windows-sdk-v2/issues/568)) ([#1324](https://github.com/box/box-windows-sdk-v2/issues/1324)) ([`9710ac9`](https://github.com/box/box-windows-sdk-v2/commit/9710ac93223a18959fa30b49c1fcdc4913645dbb))
  * treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-windows-sdk-v2/issues/906)) ([#1334](https://github.com/box/box-windows-sdk-v2/issues/1334)) ([`0c53bda`](https://github.com/box/box-windows-sdk-v2/commit/0c53bda54c30b9afd0b48f7e22a6b7c8a09a770c))
</Update>

<Update label="2025-12-19">
  ## Box iOS SDK `6.3.0` released

  ### Bug Fixes

  * **boxsdkgen:** Add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-ios-sdk/issues/572)) ([#1334](https://github.com/box/box-ios-sdk/issues/1334)) ([`373240a`](https://github.com/box/box-ios-sdk/commit/373240ae0884f94c64a0caa2951f29212becd0fd))
  * **boxsdkgen:** Fix `RetryAfter` function when there's no `Retry-After` header (box/box-codegen[#903](https://github.com/box/box-ios-sdk/issues/903)) ([#1312](https://github.com/box/box-ios-sdk/issues/1312)) ([`783ef91`](https://github.com/box/box-ios-sdk/commit/783ef91c6744caeddb4fda3d83c070095733f6c1))

  ### New Features and Enhancements

  * **boxsdkgen:** Add Metadata Taxonomies API (box/box-openapi[#569](https://github.com/box/box-ios-sdk/issues/569)) ([#1320](https://github.com/box/box-ios-sdk/issues/1320)) ([`2b52332`](https://github.com/box/box-ios-sdk/commit/2b52332460bb03412bd96df77e8cf45bb8abf35f))
  * **boxsdkgen:** Text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-ios-sdk/issues/568)) ([#1314](https://github.com/box/box-ios-sdk/issues/1314)) ([`bebd148`](https://github.com/box/box-ios-sdk/commit/bebd148378927efc4d015f88914d2b0a5915c41d))
  * **boxsdkgen:** Treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-ios-sdk/issues/906)) ([#1324](https://github.com/box/box-ios-sdk/issues/1324)) ([`c17e23a`](https://github.com/box/box-ios-sdk/commit/c17e23af55829f182e3d302682d0444520693217))
</Update>

<Update label="2025-12-19">
  ## Box Java SDK `v5.3.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add Metadata Taxonomies API (box/box-openapi[#569](https://github.com/box/box-java-sdk/issues/569)) ([#1629](https://github.com/box/box-java-sdk/issues/1629)) ([`7236f16`](https://github.com/box/box-java-sdk/commit/7236f16bf39a3376eaad4ba6e143633cc5c2f4b2))
  * **boxsdkgen:** Text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-java-sdk/issues/568)) ([#1623](https://github.com/box/box-java-sdk/issues/1623)) ([`a5d74ee`](https://github.com/box/box-java-sdk/commit/a5d74eeb4b9b053ab00ebf33cf4f9b862ea4b586))
  * **boxsdkgen:** Treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-java-sdk/issues/906)) ([#1633](https://github.com/box/box-java-sdk/issues/1633)) ([`e14e97b`](https://github.com/box/box-java-sdk/commit/e14e97bb7a53c967851f7b92bc43400bdfc8da8b))

  ### Bug Fixes

  * **boxsdkgen:** Add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-java-sdk/issues/572)) ([#1643](https://github.com/box/box-java-sdk/issues/1643)) ([`492684e`](https://github.com/box/box-java-sdk/commit/492684e45730b7f56bc1539c4086be45b30127ae))
  * **boxsdkgen:** Fix `RetryAfter` function when there's no `Retry-After` header (box/box-codegen[#903](https://github.com/box/box-java-sdk/issues/903)) ([#1621](https://github.com/box/box-java-sdk/issues/1621)) ([`af4861f`](https://github.com/box/box-java-sdk/commit/af4861f832e03d68614d6bd3c9852ca48a49ae0f))
</Update>

<Update label="2025-12-19">
  ## Box iOS SDK `10.3.0` released

  ### Bug Fixes

  * Add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-ios-sdk/issues/572)) ([#1335](https://github.com/box/box-ios-sdk/issues/1335)) ([`3dae5b0`](https://github.com/box/box-ios-sdk/commit/3dae5b0335474a8b2a01f41d5ca71e21d0d77366))
  * Fix `RetryAfter` function when there's no `Retry-After` header (box/box-codegen[#903](https://github.com/box/box-ios-sdk/issues/903)) ([#1313](https://github.com/box/box-ios-sdk/issues/1313)) ([`52a72ad`](https://github.com/box/box-ios-sdk/commit/52a72ad706de7b9079df55d5be5dd9e1fab247c3))

  ### New Features and Enhancements

  * Add Metadata Taxonomies API (box/box-openapi[#569](https://github.com/box/box-ios-sdk/issues/569)) ([#1321](https://github.com/box/box-ios-sdk/issues/1321)) ([`20497cc`](https://github.com/box/box-ios-sdk/commit/20497cce040703560a686b5640b943fb3f363f0d))
  * Text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-ios-sdk/issues/568)) ([#1315](https://github.com/box/box-ios-sdk/issues/1315)) ([`7ffe641`](https://github.com/box/box-ios-sdk/commit/7ffe641fda1a0a3ffe5a3eded0c8cafc840bb76f))
  * Treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-ios-sdk/issues/906)) ([#1325](https://github.com/box/box-ios-sdk/issues/1325)) ([`af828ea`](https://github.com/box/box-ios-sdk/commit/af828ea1d2585b3d117035722028f28a2ad3dcbc))
</Update>

<Update label="2025-12-19">
  ## Box Java SDK `v10.4.0` released

  ### Bug Fixes

  * Add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-java-sdk/issues/572)) ([#1644](https://github.com/box/box-java-sdk/issues/1644)) ([`61235da`](https://github.com/box/box-java-sdk/commit/61235da7d51a64845d344a8286821e59b217a848))
  * Fix `RetryAfter` function when there's no `Retry-After` header (box/box-codegen[#903](https://github.com/box/box-java-sdk/issues/903)) ([#1622](https://github.com/box/box-java-sdk/issues/1622)) ([`f135e2b`](https://github.com/box/box-java-sdk/commit/f135e2b62d4b2d2d266ab40b3b366c8c7968d2db))

  ### New Features and Enhancements

  * Add Metadata Taxonomies API (box/box-openapi[#569](https://github.com/box/box-java-sdk/issues/569)) ([#1630](https://github.com/box/box-java-sdk/issues/1630)) ([`d1e8924`](https://github.com/box/box-java-sdk/commit/d1e8924ad123e5fcbf014be50fbbf52ea45d546b))
  * Text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-java-sdk/issues/568)) ([#1624](https://github.com/box/box-java-sdk/issues/1624)) ([`8c5b5c1`](https://github.com/box/box-java-sdk/commit/8c5b5c17285c1c0d4a644eb8187dac92f1f96f28))
  * Treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-java-sdk/issues/906)) ([#1634](https://github.com/box/box-java-sdk/issues/1634)) ([`cacc729`](https://github.com/box/box-java-sdk/commit/cacc729dc246c914eb1a6d8281f4261c96711dc1))
</Update>

<Update label="2025-12-19">
  ## Box Python SDK `v10.3.0` released

  ### Bug Fixes

  * Add taxonomy to Metadata Field (read) definition (box/box-openapi[#572](https://github.com/box/box-python-sdk/issues/572)) ([#1269](https://github.com/box/box-python-sdk/issues/1269)) ([`7bb9bdc`](https://github.com/box/box-python-sdk/commit/7bb9bdc894cb6d765a09ecbedda58b6edb9181d0))
  * Fix `RetryAfter` function when there's no `Retry-After` header (box/box-codegen[#903](https://github.com/box/box-python-sdk/issues/903)) ([#1244](https://github.com/box/box-python-sdk/issues/1244)) ([`d7cc019`](https://github.com/box/box-python-sdk/commit/d7cc019dd186ef3cdb6214a6cf1625ec49c1fd37))

  ### New Features and Enhancements

  * Add Metadata Taxonomies API (box/box-openapi[#569](https://github.com/box/box-python-sdk/issues/569)) ([#1252](https://github.com/box/box-python-sdk/issues/1252)) ([`7850463`](https://github.com/box/box-python-sdk/commit/7850463204ef9f7802a759ef69a3b7f4b6dd328b))
  * Text input validation for Box Sign (box/box-openapi[#568](https://github.com/box/box-python-sdk/issues/568)) ([#1246](https://github.com/box/box-python-sdk/issues/1246)) ([`f99512f`](https://github.com/box/box-python-sdk/commit/f99512fcfca75edae48bb5a1b6a1897d330f5dd3))
  * Treat `nullable` fields as Optional (box/box-codegen[#906](https://github.com/box/box-python-sdk/issues/906)) ([#1256](https://github.com/box/box-python-sdk/issues/1256)) ([`12c05dc`](https://github.com/box/box-python-sdk/commit/12c05dcebae13a696956288f41ec55fed8a4011e))
</Update>

<Update label="2025-12-16">
  ## New developer documentation site (beta)

  We are excited to announce the beta launch of the new Box developer documentation site. This release provides access to the redesigned, AI-first, purpose-built developer experience platform.

  ## What’s included in this launch

  New design aligned with developer workflows:

  * Refreshed homepage
  * Intuitive landing pages
  * Interactive API testing experience
  * Improved readability and accessibility:
    * Enhanced navigation
    * Clear, responsive book structure with global and single-page tables of contents
    * Light and dark modes

  AI-first functionality:

  * AI-powered search with generative answers and aggregated results from across Box sites
  * Contextual menu options to integrate with leading AI tools and copy pages as Markdown
  * Box Dev Docs MCP server

  ## Developer impact

  The new site delivers our up-to-date developer documentation in an entirely new experience. Some UX features are still in their beta shape and will continue to be refined in the next few weeks, so you may encounter occasional changes or improvements as we gather feedback and iterate. We encourage you to engage with the new functionality and share your comments.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/box-platform-5) for any help needed.
</Update>

<Update label="2025-12-12">
  ## Box Windows SDK `v6.3.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-windows-sdk-v2/issues/567)) ([#1314](https://github.com/box/box-windows-sdk-v2/issues/1314)) ([`1733727`](https://github.com/box/box-windows-sdk-v2/commit/1733727b25c9e7b5a8995daa0e5aa5c63860e77f))

  ### **Bug Fixes:**

  * **boxsdkgen:** fix `RetryAfter` function when there's no Retry-After header (box/box-codegen[#903](https://github.com/box/box-windows-sdk-v2/issues/903)) ([#1319](https://github.com/box/box-windows-sdk-v2/issues/1319)) ([`1647641`](https://github.com/box/box-windows-sdk-v2/commit/164764159a2f041253ebf0b665286a06526fb3b2))
  * **boxsdkgen:** remove duplicate optional tag (box/box-codegen[#898](https://github.com/box/box-windows-sdk-v2/issues/898)) ([#1313](https://github.com/box/box-windows-sdk-v2/issues/1313)) ([`5c3cca9`](https://github.com/box/box-windows-sdk-v2/commit/5c3cca937949a52502848d92080aa3d69f891208))
</Update>

<Update label="2025-12-12">
  ## Box Windows SDK `v10.4.0` released

  ### Bug Fixes

  * fix `RetryAfter` function when there's no Retry-After header (box/box-codegen[#903](https://github.com/box/box-windows-sdk-v2/issues/903)) ([#1320](https://github.com/box/box-windows-sdk-v2/issues/1320)) ([`5030d1c`](https://github.com/box/box-windows-sdk-v2/commit/5030d1c5747afd8f85a54fcccf5695ca5f3ea836))
  * remove duplicate optional tag (box/box-codegen[#898](https://github.com/box/box-windows-sdk-v2/issues/898)) ([#1312](https://github.com/box/box-windows-sdk-v2/issues/1312)) ([`17b2851`](https://github.com/box/box-windows-sdk-v2/commit/17b285197cf276870ec2f3f881e4e03b28d915cc))

  ### New Features and Enhancements

  * Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-windows-sdk-v2/issues/567)) ([#1315](https://github.com/box/box-windows-sdk-v2/issues/1315)) ([`b4af239`](https://github.com/box/box-windows-sdk-v2/commit/b4af2395e45a9a94083e689ff8c30c2c22bda669))
</Update>

<Update label="2025-12-11">
  ## Box Sign Text Input Validations for Public API and Template Tags

  We've extended Box Sign's text input validation capabilities to support both Public API and template tags. This enables developers and users to apply validation rules programmatically and through templates, closing a critical feature gap for enterprise workflows.

  ## What's new

  Text input validation is now supported through:

  * **Public API**: Create signature requests with validation rules using the Sign API endpoints.
  * **Template tags**: Apply validation rules directly in document templates for use with Public API, Doc Gen, and Salesforce integrations.
  * **Custom regex patterns**: Define custom validation patterns beyond the predefined validation types.

  ## Why it matters

  This update addresses key integration needs:

  * **Public API developers** can programmatically create signature requests with validation rules, including custom regex, ensuring data quality at scale.
  * **Salesforce integration** users can now leverage text input validation rules for fields that sync back to Salesforce.
  * **Doc Gen users** can apply validation to fields in automated document workflows.
    Template Tags with validation support particularly benefits workflows where templates are used programmatically through integrations, eliminating the previous gap where validation was only available through the web interface.

  ## API updates

  The following endpoints now support text input validation:

  * [`POST /sign_requests`](/reference/post-sign-requests) — Create sign request with validation.
  * [`GET /:sign_request_id`](/reference/get-sign-requests-id) — Get sign request details including validation.
  * [`GET /sign_requests`](/reference/get-sign-requests) — List sign requests with validation info.
  * [`GET /:template_id`](/reference/get-sign-templates-id) — Get template with validation rules.
  * [`GET /sign_templates`](/reference/get-sign-templates) — List templates with validation info.

  ## Getting started

  To use text input validation:

  1. Review the [Create sign request endpoint](/reference/post-sign-requests) for adding validation to signature requests.
  2. Check out the Box Sign documentation for [applying validation in Template Tags](https://support.box.com/hc/en-us/articles/4404085855251-Creating-templates-using-tags).
  3. Explore [custom regex patterns](https://support.box.com/hc/en-us/articles/42924560611603-Using-Input-Text-Validation) for advanced validation scenarios.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2025-12-10">
  ## Box Python SDK `v4.2.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-python-sdk/issues/567)) ([#1237](https://github.com/box/box-python-sdk/issues/1237)) ([`2ac9408`](https://github.com/box/box-python-sdk/commit/2ac9408be69a86b7f57e7efdb433c8c049568fad))
  * **boxsdkgen:** Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-python-sdk/issues/565)) ([#1221](https://github.com/box/box-python-sdk/issues/1221)) ([`56a93ac`](https://github.com/box/box-python-sdk/commit/56a93ac02fd746799ec8a831b61e06b2b7464479))
</Update>

<Update label="2025-12-10">
  ## Box Python SDK `v10.2.0` released

  ### New Features and Enhancements

  * Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-python-sdk/issues/567)) ([#1238](https://github.com/box/box-python-sdk/issues/1238)) ([`66267ba`](https://github.com/box/box-python-sdk/commit/66267bae7395ce2886cc4cd7504a51d22394b738))
  * Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-python-sdk/issues/565)) ([#1222](https://github.com/box/box-python-sdk/issues/1222)) ([`6c3d332`](https://github.com/box/box-python-sdk/commit/6c3d3325a19b3217225a80c2cd5d15c7bb068494))
</Update>

<Update label="2025-12-10">
  ## Box Node SDK `v4.2.0` released

  ### Bug Fixes

  * **boxsdkgen:** Remove duplicated  in union type (box/box-codegen[#898](https://github.com/box/box-node-sdk/issues/898)) ([#1241](https://github.com/box/box-node-sdk/issues/1241)) ([`c56f808`](https://github.com/box/box-node-sdk/commit/c56f808315fab6da134de17517bbb33067523859))
  * bump `jsonwebtoken` dependency ([#1244](https://github.com/box/box-node-sdk/issues/1244)) ([`49692e3`](https://github.com/box/box-node-sdk/commit/49692e3724c9aa40a855f85a7b0771db1c984b6f))

  ### New Features and Enhancements

  * **boxsdkgen:** Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-node-sdk/issues/567)) ([#1245](https://github.com/box/box-node-sdk/issues/1245)) ([`3a74388`](https://github.com/box/box-node-sdk/commit/3a74388b46e4842708c11ada8f931b810c0b3230))
  * **boxsdkgen:** support `includeConfidenceScore` and `includeConfidenceScore` fields in AI extract structured (box/box-openapi[#566](https://github.com/box/box-node-sdk/issues/566)) ([#1227](https://github.com/box/box-node-sdk/issues/1227)) ([`8e2b109`](https://github.com/box/box-node-sdk/commit/8e2b109ebacd48ed268a9310cb01d8f6ae5ebca4))
  * **boxsdkgen:** Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-node-sdk/issues/565)) ([#1225](https://github.com/box/box-node-sdk/issues/1225)) ([`955b6ba`](https://github.com/box/box-node-sdk/commit/955b6ba5df942c5c1c0340c307cefad70549db53))
  * **boxsdkgen:** update error message on exception (box/box-codegen[#896](https://github.com/box/box-node-sdk/issues/896)) ([#1232](https://github.com/box/box-node-sdk/issues/1232)) ([`b140428`](https://github.com/box/box-node-sdk/commit/b140428c303de789bc1cee49c1e8c03139602c65))
</Update>

<Update label="2025-12-10">
  ## Box Node SDK `v10.2.0` released

  ### Bug Fixes

  * Remove duplicated  in union type (box/box-codegen[#898](https://github.com/box/box-node-sdk/issues/898)) ([#1240](https://github.com/box/box-node-sdk/issues/1240)) ([`0b03b60`](https://github.com/box/box-node-sdk/commit/0b03b607789ccf6a94253101760aa530a9737e78))

  ### New Features and Enhancements

  * Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-node-sdk/issues/567)) ([#1243](https://github.com/box/box-node-sdk/issues/1243)) ([`55d6cd0`](https://github.com/box/box-node-sdk/commit/55d6cd00790a81fa5c54379c045b4e652173dcb8))
  * support `includeConfidenceScore` and `includeConfidenceScore` fields in AI extract structured (box/box-openapi[#566](https://github.com/box/box-node-sdk/issues/566)) ([#1228](https://github.com/box/box-node-sdk/issues/1228)) ([`4bf9f46`](https://github.com/box/box-node-sdk/commit/4bf9f46baaeaa213878c9102c0628e3c351c7b3c))
  * Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-node-sdk/issues/565)) ([#1226](https://github.com/box/box-node-sdk/issues/1226)) ([`8dfc1cc`](https://github.com/box/box-node-sdk/commit/8dfc1ccc9c600c24d4d5e7879eaebfd6bf1f9a0e))
  * update error message on exception (box/box-codegen[#896](https://github.com/box/box-node-sdk/issues/896)) ([#1233](https://github.com/box/box-node-sdk/issues/1233)) ([`b298afa`](https://github.com/box/box-node-sdk/commit/b298afa69fce884f7def10a8022aa67dc58ac949))
</Update>

<Update label="2025-12-10">
  ## Box Java SDK `v5.2.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-java-sdk/issues/567)) ([#1614](https://github.com/box/box-java-sdk/issues/1614)) ([`e5e9545`](https://github.com/box/box-java-sdk/commit/e5e9545cc539c6c8f3ce4e99926840529437039b))
  * **boxsdkgen:** Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-java-sdk/issues/565)) ([#1598](https://github.com/box/box-java-sdk/issues/1598)) ([`87d1182`](https://github.com/box/box-java-sdk/commit/87d1182ec362bfbf800edda79360a2446ba7eaab))
</Update>

<Update label="2025-12-10">
  ## Box Java SDK `v10.3.0` released

  ### New Features and Enhancements

  * Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-java-sdk/issues/567)) ([#1615](https://github.com/box/box-java-sdk/issues/1615)) ([`0a069cd`](https://github.com/box/box-java-sdk/commit/0a069cdecc4837d8bdb6f1e91401d88c58af5a92))
  * Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-java-sdk/issues/565)) ([#1599](https://github.com/box/box-java-sdk/issues/1599)) ([`b3c46bb`](https://github.com/box/box-java-sdk/commit/b3c46bbf2f2f7b9b25befcd6442a4e5c9a92e790))
</Update>

<Update label="2025-12-10">
  ## Box iOS SDK `6.2.0` released

  ### Bug Fixes

  * **boxsdkgen:** Remove duplicate optional wrapping (box/box-codegen[#898](https://github.com/box/box-ios-sdk/issues/898)) ([#1302](https://github.com/box/box-ios-sdk/issues/1302)) ([`4fae34a`](https://github.com/box/box-ios-sdk/commit/4fae34add0569ac907d2f50e1ab2a7da7a223f6b))

  ### New Features and Enhancements

  * **boxsdkgen:** Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-ios-sdk/issues/567)) ([#1304](https://github.com/box/box-ios-sdk/issues/1304)) ([`143ef03`](https://github.com/box/box-ios-sdk/commit/143ef03119c6ac6f7f4bff198ce8578a78abd353))
  * **boxsdkgen:** Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-ios-sdk/issues/565)) ([#1286](https://github.com/box/box-ios-sdk/issues/1286)) ([`e6c0826`](https://github.com/box/box-ios-sdk/commit/e6c082659f65bfcc8eb17de1552d23d07eeb7d56))
</Update>

<Update label="2025-12-10">
  ## Box iOS SDK `10.2.0` released

  ### Bug Fixes

  * Remove duplicate optional wrapping (box/box-codegen[#898](https://github.com/box/box-ios-sdk/issues/898)) ([#1301](https://github.com/box/box-ios-sdk/issues/1301)) ([`0fff45e`](https://github.com/box/box-ios-sdk/commit/0fff45ed3139ffebaafc9af4113bbb61d7fd3945))

  ### New Features and Enhancements

  * Remove `confidence_score` and `include_confidence_score` from AI extract (box/box-openapi[#567](https://github.com/box/box-ios-sdk/issues/567)) ([#1305](https://github.com/box/box-ios-sdk/issues/1305)) ([`702de7b`](https://github.com/box/box-ios-sdk/commit/702de7b8bba3e423b749b9cf11a5bbb77fc1ad41))
  * Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-ios-sdk/issues/565)) ([#1285](https://github.com/box/box-ios-sdk/issues/1285)) ([`d541f12`](https://github.com/box/box-ios-sdk/commit/d541f128badac0929d586fe2de2f8e2a2c5a786b))
</Update>

<Update label="2025-12-09">
  ## Box UI Elements `v25.4.0` released

  ### [25.4.0](https://github.com/box/box-ui-elements/compare/v25.3.0...v25.4.0) (2025-12-09)

  ### Bug Fixes

  * bump node-forge version ([#4386](https://github.com/box/box-ui-elements/issues/4386)) ([`5f46b8b`](https://github.com/box/box-ui-elements/commit/5f46b8bb57c879f1fb5ca0a0dfc00138b90e8273))
  * **i18n:** update translations ([#4369](https://github.com/box/box-ui-elements/issues/4369)) ([`abc11ee`](https://github.com/box/box-ui-elements/commit/abc11eeb509583c80e3d76d8fb6341eeb3cbcf24))
  * **i18n:** update translations ([#4372](https://github.com/box/box-ui-elements/issues/4372)) ([`8dd5f9f`](https://github.com/box/box-ui-elements/commit/8dd5f9feab11b5214a9f1038717916f80d89f697))
  * **i18n:** update translations ([#4374](https://github.com/box/box-ui-elements/issues/4374)) ([`7f37b4b`](https://github.com/box/box-ui-elements/commit/7f37b4bdf0059f40eea2182f85a5579b06884740))
  * **i18n:** update translations ([#4375](https://github.com/box/box-ui-elements/issues/4375)) ([`df948b4`](https://github.com/box/box-ui-elements/commit/df948b4042fa706b944e2a1c2532c8e2827f8f24))
  * **i18n:** update translations ([#4377](https://github.com/box/box-ui-elements/issues/4377)) ([`7e61a9c`](https://github.com/box/box-ui-elements/commit/7e61a9c45b2da90af47723b14b7d5f04cce6322f))
  * improve accessibility in sidebar content and tags components ([#4363](https://github.com/box/box-ui-elements/issues/4363)) ([`35080aa`](https://github.com/box/box-ui-elements/commit/35080aababcf3457f9d9d898709b9ef8a4acf743))
  * **metadata-editor:** Preserve field order when fetching taxonomy levels for fields ([#4378](https://github.com/box/box-ui-elements/issues/4378)) ([`fbd155e`](https://github.com/box/box-ui-elements/commit/fbd155e170cf5f5ea3e77d78e9614a3055cb7fe0))
  * **video-annotations:** Add version links for video annotations ([#4379](https://github.com/box/box-ui-elements/issues/4379)) ([`8bf7c63`](https://github.com/box/box-ui-elements/commit/8bf7c631acbebf37674d556c5c1480c7fa626ce4))

  ### Features

  * **deps:** No-op to trigger release for blueprint-web upgrades ([#4368](https://github.com/box/box-ui-elements/issues/4368)) ([`58b9697`](https://github.com/box/box-ui-elements/commit/58b9697331a5d913a83acd1d78ed71ebab8d2835))
  * **form-elements:** Remove Form legacy context ([#4383](https://github.com/box/box-ui-elements/issues/4383)) ([`62c77b4`](https://github.com/box/box-ui-elements/commit/62c77b4ce9f1995e1194319343fd39fb6371bf80))
  * **hotkeys:** Remove legacy context from Hotkeys ([#4382](https://github.com/box/box-ui-elements/issues/4382)) ([`5db66df`](https://github.com/box/box-ui-elements/commit/5db66df5d4335531ce829e51a1e83e4ab3abb35a))
  * **presence-avatar-list:** add BP tooltip to `presenceAvatarList` (`WEBAPP-41740`) ([#4384](https://github.com/box/box-ui-elements/issues/4384)) ([`5653500`](https://github.com/box/box-ui-elements/commit/565350009c5f8b94c4ad01bad5232931997cc0c0))
  * **preview-modernization:** BP `AddTaskButton` ([#4366](https://github.com/box/box-ui-elements/issues/4366)) ([`f76ed73`](https://github.com/box/box-ui-elements/commit/f76ed73eb99176c80393a42d4d80ba75025e6f1f))
  * **preview-modernization:** Update Sidebar Nav icons and tooltips ([#4373](https://github.com/box/box-ui-elements/issues/4373)) ([`60eda40`](https://github.com/box/box-ui-elements/commit/60eda4000ba9884c70696d829f42c1b3fd6f7423))
  * **preview-modernization:** Update Sidebar Nav overflow separator ([#4370](https://github.com/box/box-ui-elements/issues/4370)) ([`671a067`](https://github.com/box/box-ui-elements/commit/671a0676fbfa9a86c07a381691c9938880934aee))
  * **preview-optimizations:** modernize Versions sidebar ([#4381](https://github.com/box/box-ui-elements/issues/4381)) ([`2b136e4`](https://github.com/box/box-ui-elements/commit/2b136e46398ddaeb8b773e8a23323a986220dfd7))
  * **`SecurityControls`:** Add Shared Link Auto-Expiration restriction ([#4365](https://github.com/box/box-ui-elements/issues/4365)) ([`40ff462`](https://github.com/box/box-ui-elements/commit/40ff462fb4630911d7ab7e2f0d36d415ead010af))
</Update>

<Update label="2025-12-08">
  ## Box Windows SDK `v6.2.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Support long polling event for dotnet (box/box-codegen[#893](https://github.com/box/box-windows-sdk-v2/issues/893)) ([#1297](https://github.com/box/box-windows-sdk-v2/issues/1297)) ([`d064e76`](https://github.com/box/box-windows-sdk-v2/commit/d064e76e5d047a4f28cad5c4aa597365e46aba26))
  * **boxsdkgen:** Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-windows-sdk-v2/issues/565)) ([#1293](https://github.com/box/box-windows-sdk-v2/issues/1293)) ([`3efe490`](https://github.com/box/box-windows-sdk-v2/commit/3efe4903bfe94984db2b29f8ec80eb7c32cb1038))

  ### **Bug Fixes:**

  * **boxsdkgen:** fix string extension in dotnet (box/box-codegen[#899](https://github.com/box/box-windows-sdk-v2/issues/899)) ([#1306](https://github.com/box/box-windows-sdk-v2/issues/1306)) ([`b97f971`](https://github.com/box/box-windows-sdk-v2/commit/b97f971dc50ffcabc3376c73ca83290ff70f0899))
</Update>

<Update label="2025-12-08">
  ## Box Windows SDK `v10.3.0` released

  ### Bug Fixes

  * fix string extension in dotnet (box/box-codegen[#899](https://github.com/box/box-windows-sdk-v2/issues/899)) ([#1307](https://github.com/box/box-windows-sdk-v2/issues/1307)) ([`8c46af4`](https://github.com/box/box-windows-sdk-v2/commit/8c46af45398c2002b5de8475672923bac524e4d1))

  ### New Features and Enhancements

  * Support long polling event for dotnet (box/box-codegen[#893](https://github.com/box/box-windows-sdk-v2/issues/893)) ([#1298](https://github.com/box/box-windows-sdk-v2/issues/1298)) ([`e35cd67`](https://github.com/box/box-windows-sdk-v2/commit/e35cd67fe29d9af969ac88dee30896303d4fdc79))
  * Support new sign request metadata (box/box-openapi[#565](https://github.com/box/box-windows-sdk-v2/issues/565)) ([#1294](https://github.com/box/box-windows-sdk-v2/issues/1294)) ([`da19f7c`](https://github.com/box/box-windows-sdk-v2/commit/da19f7cdd4df6537acec50463330944e9d6d4632))
</Update>

<Update label="2025-12-03">
  ## Ransomware Activity detection rule

  The Ransomware Activity detection rule, available in Box Shield Pro, monitors user activity and leverages Box machine learning to identify suspicious file extensions that may indicate a ransomware attack.

  ### Fighting ransomware

  With the Ransomware Activity detection rule, you can better protect yourself by:

  * [Creating and editing the detection rule](https://support.box.com/hc/en-us/articles/46976660378643-Create-Edit-and-Delete-a-Threat-Detection-Rule)
  * [Viewing alerts](https://support.box.com/hc/en-us/articles/44263782754323-Ransomware-Activity-Detection-Rule#h_01KBCKYECWTA6RCBSZYMD2CNTX)
  * [Taking action to remediate threats](https://support.box.com/hc/en-us/articles/44263782754323-Ransomware-Activity-Detection-Rule#h_01KBCKYPP2R903PZMB1VBA5XEM)

  To learn more about using the Ransomware Activity detection rule, visit our [support documentation](https://support.box.com/hc/en-us/articles/44263782754323-Ransomware-Activity-Detection-Rule).
</Update>

<Update label="2025-11-27">
  ## Box AI API — new AI models available and default models update

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with the following models:

  * [OpenAI GPT-5.1](https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-1-model-card/)
  * [OpenAI GPT-5 mini](https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-mini-model-card/)
  * [Gemini 3 Pro](https://developer.box.com/guides/box-ai/ai-models/google-gemini-3-pro-model-card/) (Beta)
  * [Llama 4 Maverick](https://developer.box.com/guides/box-ai/ai-models/ibm-llama-4-maverick-model-card/)

  Additionally, default AI models have been updated for Box AI features:

  * [Gemini 2.5 Pro](https://developer.box.com/guides/box-ai/ai-models/google-gemini-2-5-pro-model-card/) is now the default model for Box AI Enhanced Extract.
  * [Gemini 2.5 Flash](https://developer.box.com/guides/box-ai/ai-models/google-gemini-2-5-flash-model-card/) is now the default model for Box AI Standard Extract.
  * [OpenAI GPT-5](https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-model-card/) is now the default model for Box AI Advanced Agent for Hubs, Documents, and Notes Q\&A.
  * [OpenAI GPT-5 mini](https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-mini-model-card/) is now the default model for Box AI for Hubs, Documents, and Notes Q\&A.

  **Note:** Models offered in **Beta** mode have not been fully performance-tested at scale and are provided on an as-is basis.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-agents/ai-agent-overrides/) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-11-20">
  ## Box iOS SDK 6.1.0 released

  ### New Features and Enhancements

  * **boxsdkgen:** Support GET enterprise configuration API (box/box-openapi[#559](https://github.com/box/box-ios-sdk/issues/559)) ([#1190](https://github.com/box/box-ios-sdk/issues/1190)) ([`c91bb4f`](https://github.com/box/box-ios-sdk/commit/c91bb4fa1b5907698fd6d0fd38560501c4d0274b))
  * **boxsdkgen:** Support Archive API (box/box-openapi[#563](https://github.com/box/box-ios-sdk/issues/563)) ([#1237](https://github.com/box/box-ios-sdk/issues/1237)) ([`07aaf3a`](https://github.com/box/box-ios-sdk/commit/07aaf3adde1ec46ed6f2423093b451b975005368))
</Update>

<Update label="2025-11-20">
  ## Box iOS SDK 10.1.0 released

  ### New Features and Enhancements

  * Support GET enterprise configuration API (box/box-openapi[#559](https://github.com/box/box-ios-sdk/issues/559)) ([#1179](https://github.com/box/box-ios-sdk/issues/1179)) ([`936edf7`](https://github.com/box/box-ios-sdk/commit/936edf7532765dfe3c0ccb7175966ee4ec265cf3))
  * Support Archive API (box/box-openapi[#563](https://github.com/box/box-ios-sdk/issues/563)) ([#1238](https://github.com/box/box-ios-sdk/issues/1238)) ([`a2662e3`](https://github.com/box/box-ios-sdk/commit/a2662e3bd088956769ed95d588e71623d0537c40))
</Update>

<Update label="2025-11-20">
  ## Box CLI v4.5.0 released

  ### New Features and Enhancements

  * support auto update using Github releases ([#603](https://github.com/box/boxcli/issues/603)) ([`2460e1b`](https://github.com/box/boxcli/commit/2460e1b51002e94c3a16356099c4511faa96b87c))

  ### Bug Fixes

  * update dependencies to fix `tmp` vulnerability ([#600](https://github.com/box/boxcli/issues/600)) ([`7e270eb`](https://github.com/box/boxcli/commit/7e270eb8daf254a64eb3ce373444e9ad96e5e5be))
</Update>

<Update label="2025-11-19">
  ## Box Windows SDK v6.1.0 released

  ### New Features and Enhancements

  * **boxsdkgen:** Support Archive API (box/box-codegen[#865](https://github.com/box/box-windows-sdk-v2/issues/865)) ([#1270](https://github.com/box/box-windows-sdk-v2/issues/1270)) ([`307a5d4`](https://github.com/box/box-windows-sdk-v2/commit/307a5d43f8ba2b93ce35b3607026b4232cc92042))
  * **boxsdkgen:** Support GET enterprise configuration API (box/box-openapi[#559](https://github.com/box/box-windows-sdk-v2/issues/559)) ([#1212](https://github.com/box/box-windows-sdk-v2/issues/1212)) ([`0d97d4d`](https://github.com/box/box-windows-sdk-v2/commit/0d97d4d858c4bba8b3df0d01234691294a7c8998))
  * **boxsdkgen:** Use generated `RetryStrategy` for retrying requests (box/box-codegen[#872](https://github.com/box/box-windows-sdk-v2/issues/872)) ([#1227](https://github.com/box/box-windows-sdk-v2/issues/1227)) ([`5b42a3e`](https://github.com/box/box-windows-sdk-v2/commit/5b42a3e666751f1a1e529b875eafa8e7b0fbe930))
</Update>

<Update label="2025-11-19">
  ## Box Windows SDK v10.2.0 released

  ### New Features and Enhancements

  * Support Archive API (box/box-codegen[#865](https://github.com/box/box-windows-sdk-v2/issues/865)) ([#1266](https://github.com/box/box-windows-sdk-v2/issues/1266)) ([`bca0473`](https://github.com/box/box-windows-sdk-v2/commit/bca0473d9ff02f286f3face267a30c2ab17d5b7b))
  * Support GET enterprise configuration API (box/box-openapi[#559](https://github.com/box/box-windows-sdk-v2/issues/559)) ([#1198](https://github.com/box/box-windows-sdk-v2/issues/1198)) ([`426aaed`](https://github.com/box/box-windows-sdk-v2/commit/426aaed8418baf6cbd31dbe884aa91ce9bb7ef52))
  * Include `pdb` files when packing .net root project (box/box-codegen[#859](https://github.com/box/box-windows-sdk-v2/issues/859)) ([#1169](https://github.com/box/box-windows-sdk-v2/issues/1169)) ([`8b7e7c8`](https://github.com/box/box-windows-sdk-v2/commit/8b7e7c89f9f533ee09a8c096afd141abbbc72080))
  * Use generated `RetryStrategy` for retrying requests (box/box-codegen[#872](https://github.com/box/box-windows-sdk-v2/issues/872)) ([#1232](https://github.com/box/box-windows-sdk-v2/issues/1232)) ([`5567fef`](https://github.com/box/box-windows-sdk-v2/commit/5567feff459b91e7b018bda5def60ad45548599f))
</Update>

<Update label="2025-11-19">
  ## Box Python SDK v10.1.0 released

  ### New Features and Enhancements

  * Support GET enterprise configuration API (box/box-openapi[#559](https://github.com/box/box-python-sdk/issues/559)) ([#1134](https://github.com/box/box-python-sdk/issues/1134)) ([`1106d32`](https://github.com/box/box-python-sdk/commit/1106d325973df9704f5102538ac0130bda6e9c38))
  * Support Archive API (box/box-openapi[#563](https://github.com/box/box-python-sdk/issues/563)) ([#1174](https://github.com/box/box-python-sdk/issues/1174)) ([`d21ec4d`](https://github.com/box/box-python-sdk/commit/d21ec4df82ab43539ff07d306cf304f86bbb0593))
</Update>

<Update label="2025-11-12">
  ## Box Node SDK v4.1.1 released

  ### Bug Fixes

  * **boxsdkgen:** Fix error propagation and empty fetch response handling in node SDK (box/box-codegen[#883](https://github.com/box/box-node-sdk/issues/883)) ([#1196](https://github.com/box/box-node-sdk/issues/1196)) ([`9615a34`](https://github.com/box/box-node-sdk/commit/9615a3480686eb8af9374691a2ec1de82688eaa1))
</Update>

<Update label="2025-11-10">
  ## Box Node SDK v10.1.0 released

  ### Bug Fixes

  * Fix error handling in TS (box/box-codegen[#882](https://github.com/box/box-node-sdk/issues/882)) ([#1180](https://github.com/box/box-node-sdk/issues/1180)) ([`2b68145`](https://github.com/box/box-node-sdk/commit/2b68145d9d8e46e26d08b8bc774ba757ef3b444f))
  * Fix error propagation and empty fetch response handling in node SDK (box/box-codegen[#883](https://github.com/box/box-node-sdk/issues/883)) ([#1192](https://github.com/box/box-node-sdk/issues/1192)) ([`5664231`](https://github.com/box/box-node-sdk/commit/56642319c5b77ab0113ed4e1af5df30100449fcd))
  * Remove enum types from GET enterprise configurations endpoint (box/box-openapi[#560](https://github.com/box/box-node-sdk/issues/560)) ([#1155](https://github.com/box/box-node-sdk/issues/1155)) ([`3ba01aa`](https://github.com/box/box-node-sdk/commit/3ba01aaac7861ce3f0578af65d838f61b78b7dcb)), closes [`box/box-openapi#558`](https://github.com/box/box-openapi/issues/558) [`box/box-openapi#558`](https://github.com/box/box-openapi/issues/558) [`box/box-openapi#559`](https://github.com/box/box-openapi/issues/559) [`box/box-codegen#869`](https://github.com/box/box-node-sdk/issues/869) [`box/box-codegen#871`](https://github.com/box/box-node-sdk/issues/871) [`box/box-codegen#872`](https://github.com/box/box-node-sdk/issues/872)

  ### New Features and Enhancements

  * Add GET enterprise configuration endpoint (box/box-openapi[#559](https://github.com/box/box-node-sdk/issues/559)) ([#1143](https://github.com/box/box-node-sdk/issues/1143)) ([`5eeeb4f`](https://github.com/box/box-node-sdk/commit/5eeeb4fe7d0fff376cb31b820597e63d71dd0b69))
  * support delete Archive endpoint (box/box-openapi[#563](https://github.com/box/box-node-sdk/issues/563)) ([#1173](https://github.com/box/box-node-sdk/issues/1173)) ([`7dc774d`](https://github.com/box/box-node-sdk/commit/7dc774d8764a3a0b3f60525e416ed5345d4a71b1))
</Update>

<Update label="2025-11-07">
  ## Box UI Elements v25.3.0 released

  ### [25.3.0](https://github.com/box/box-ui-elements/compare/v25.2.0...v25.3.0) (2025-11-07)

  ### Features

  * **deps:** Upgrade blueprint-web to 12.93.5 ([#4362](https://github.com/box/box-ui-elements/issues/4362)) ([`84aaf2f`](https://github.com/box/box-ui-elements/commit/84aaf2ffc0234b5728188df6944a48679eca4976))
  * **metadata:** enable multilevel taxonomy field filter in preview ([#4354](https://github.com/box/box-ui-elements/issues/4354)) ([`4851c37`](https://github.com/box/box-ui-elements/commit/4851c3776fbbef1220029234d01bc0ab6354b17c))
</Update>

<Update label="2025-11-04">
  ## Box UI Elements v25.2.0 released

  ### [25.2.0](https://github.com/box/box-ui-elements/compare/v25.1.0...v25.2.0) (2025-11-04)

  ### Bug Fixes

  * **classification:** Fix flaky ai-icon check ([#4323](https://github.com/box/box-ui-elements/issues/4323)) ([`0061f34`](https://github.com/box/box-ui-elements/commit/0061f34e9e7f4613f5b15f83eeccde3b518940cb))
  * **content-picker:** folder nav ([#4329](https://github.com/box/box-ui-elements/issues/4329)) ([`8053fa7`](https://github.com/box/box-ui-elements/commit/8053fa70127203f5d70818228b70272d869965ff))
  * **content-picker:** Upgrade blueprint to fix scrolling issue ([#4349](https://github.com/box/box-ui-elements/issues/4349)) ([`d0ce8a6`](https://github.com/box/box-ui-elements/commit/d0ce8a60056cc2272c96828219897189449fb6ad))
  * **content-sharing:** Collaborator current user ([#4328](https://github.com/box/box-ui-elements/issues/4328)) ([`2e9dd6a`](https://github.com/box/box-ui-elements/commit/2e9dd6ab3ce63b974241566f3d1c24e401005e96))
  * **content-sharing:** null sharingServiceProps ([#4352](https://github.com/box/box-ui-elements/issues/4352)) ([`4ea0f83`](https://github.com/box/box-ui-elements/commit/4ea0f8376ff34a650b4ad16af91a39e1becbe4d7))
  * **content-sharing:** Shared link modal and collaborators ([#4360](https://github.com/box/box-ui-elements/issues/4360)) ([`76e94f1`](https://github.com/box/box-ui-elements/commit/76e94f12fcc6a57809165bebb145fa57560afe56))
  * Fix modernization hook for ContentSharing v2 ([#4339](https://github.com/box/box-ui-elements/issues/4339)) ([`e0a67e0`](https://github.com/box/box-ui-elements/commit/e0a67e0618fdbfa6f13cdb58fdba6a6c18a89c47))
  * **i18n:** update translations ([#4321](https://github.com/box/box-ui-elements/issues/4321)) ([`4d89663`](https://github.com/box/box-ui-elements/commit/4d89663b5481463353cb39f0828304ca1744a07c))
  * **i18n:** update translations ([#4325](https://github.com/box/box-ui-elements/issues/4325)) ([`3e8eeea`](https://github.com/box/box-ui-elements/commit/3e8eeea3d203d316b9e3f099f6de06759a56810b))
  * **i18n:** update translations ([#4330](https://github.com/box/box-ui-elements/issues/4330)) ([`bd0dd5f`](https://github.com/box/box-ui-elements/commit/bd0dd5fa8778e77eb53785fb91b4ab0bdfcb2adf))
  * **i18n:** update translations ([#4333](https://github.com/box/box-ui-elements/issues/4333)) ([`b2a4e01`](https://github.com/box/box-ui-elements/commit/b2a4e01003f4b66faea00633e2bc2b3f4c7e13f7))
  * **i18n:** update translations ([#4343](https://github.com/box/box-ui-elements/issues/4343)) ([`847557b`](https://github.com/box/box-ui-elements/commit/847557b53bf89ad591e4cb2116d3b0f267b8e757))
  * **i18n:** update translations ([#4348](https://github.com/box/box-ui-elements/issues/4348)) ([`d4eae4b`](https://github.com/box/box-ui-elements/commit/d4eae4bed33a7ae4e01565eb7809b2f579bd6066))
  * **i18n:** update translations ([#4353](https://github.com/box/box-ui-elements/issues/4353)) ([`e3f4cf9`](https://github.com/box/box-ui-elements/commit/e3f4cf90382c2ef531df909c4d7202dfab1126d8))
  * **i18n:** update translations ([#4355](https://github.com/box/box-ui-elements/issues/4355)) ([`094e633`](https://github.com/box/box-ui-elements/commit/094e633f76df79bb14d0f193f1a126d93e371324))
  * **i18n:** update translations ([#4357](https://github.com/box/box-ui-elements/issues/4357)) ([`a817d9c`](https://github.com/box/box-ui-elements/commit/a817d9c616f9100f9f6fbe21dadb1cd578a45f39))
  * **i18n:** update translations ([#4358](https://github.com/box/box-ui-elements/issues/4358)) ([`33a5861`](https://github.com/box/box-ui-elements/commit/33a5861d34e914e037e3a35597b28956f69db6ab))
  * **storybook:** update brand url ([#4337](https://github.com/box/box-ui-elements/issues/4337)) ([`c73965b`](https://github.com/box/box-ui-elements/commit/c73965b87c172bbe59adc456fe64a9d92dd7316d))
  * **video-annotations:** fixing mentions not being properly parsed ([#4351](https://github.com/box/box-ui-elements/issues/4351)) ([`6bb2b15`](https://github.com/box/box-ui-elements/commit/6bb2b15c5e0886861c73c1478a05fd30b3bf1832))

  ### Features

  * **api:** respect hidden collaborators ([#4346](https://github.com/box/box-ui-elements/issues/4346)) ([`955e6cb`](https://github.com/box/box-ui-elements/commit/955e6cb06cd2d903c7c85e47f005f83c2818c890))
  * **content-explorer:** Disable selection while editing ([#4317](https://github.com/box/box-ui-elements/issues/4317)) ([`c08d9b5`](https://github.com/box/box-ui-elements/commit/c08d9b5fdd8b20d95f747198c5bbac8204e97bf2))
  * **content-sharing:** convert api response for collabs ([#4322](https://github.com/box/box-ui-elements/issues/4322)) ([`6937b60`](https://github.com/box/box-ui-elements/commit/6937b60ba181e2300eab98934a930d1456ce50e0))
  * **content-sharing:** Create contact service getContactByEmail ([#4342](https://github.com/box/box-ui-elements/issues/4342)) ([`05b50cd`](https://github.com/box/box-ui-elements/commit/05b50cdd62e7e7d4a59073cf152305fa7ff969fb))
  * **content-sharing:** Create contact service getContacts ([#4338](https://github.com/box/box-ui-elements/issues/4338)) ([`8ae6ccc`](https://github.com/box/box-ui-elements/commit/8ae6cccf0c11b1ebc750934c5d23c42a99dae41d))
  * **content-sharing:** Create contact service getContactsAvatarUrls ([#4345](https://github.com/box/box-ui-elements/issues/4345)) ([`6f9260b`](https://github.com/box/box-ui-elements/commit/6f9260b8256aee8c710f24e3e10d5711c5abc19a))
  * **content-sharing:** Create sharing service changeSharedLinkPermission ([#4332](https://github.com/box/box-ui-elements/issues/4332)) ([`e64a61b`](https://github.com/box/box-ui-elements/commit/e64a61bcb92f2de6b75e218ae99a55dde82835c4))
  * **content-sharing:** Create sharing service sendInvitations ([#4344](https://github.com/box/box-ui-elements/issues/4344)) ([`d497350`](https://github.com/box/box-ui-elements/commit/d49735065dd73c4a6e3a85ffa99f3b24537c4b48))
  * **content-sharing:** Define sharing service for shared link and access ([#4340](https://github.com/box/box-ui-elements/issues/4340)) ([`2f7185d`](https://github.com/box/box-ui-elements/commit/2f7185de2d10fe62dba8e8a4f2bc8235009e0b5e))
  * **content-sharing:** Handle error when fetch init data failed ([#4350](https://github.com/box/box-ui-elements/issues/4350)) ([`f0c9efd`](https://github.com/box/box-ui-elements/commit/f0c9efd404abfe29b69bb28e7d3caeba367a9b92))
  * **content-sharing:** Render notification for sendInvitations ([#4347](https://github.com/box/box-ui-elements/issues/4347)) ([`051bd7c`](https://github.com/box/box-ui-elements/commit/051bd7c5cccdaebd1d7bcda55de014c6db75f75f))
  * **content-sharing:** Sharing service updateSharedLink ([#4336](https://github.com/box/box-ui-elements/issues/4336)) ([`b39a482`](https://github.com/box/box-ui-elements/commit/b39a4824486062c34378ce9a8fbbe34cd6042d3c))
  * **deps:** upgrade package dependencies ([#4359](https://github.com/box/box-ui-elements/issues/4359)) ([`2f025e3`](https://github.com/box/box-ui-elements/commit/2f025e3765c26bc206440458aaa632dddd36d83b))

  ### Reverts

  * "feat(content-sidebar): implement for custom sidebar panels (#… ([#4320](https://github.com/box/box-ui-elements/issues/4320)) ([`230f417`](https://github.com/box/box-ui-elements/commit/230f417c9407c4bbe4705ec8f200c53f572a798a)), closes [#4239](https://github.com/box/box-ui-elements/issues/4239)
</Update>

<Update label="2025-10-23">
  ## Box AI API — new AI models available and default model update

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with the following models:

  * [Mistral Medium 3](https://developer.box.com/guides/box-ai/ai-models/ibm-mistral-medium-3-model-card/)
  * [Mistral Small 3.1](https://developer.box.com/guides/box-ai/ai-models/ibm-mistral-small-3-1-model-card/)
  * [Claude Haiku 4.5](https://developer.box.com/guides/box-ai/ai-models/aws-claude-4-5-haiku-model-card/)

  Additionally, [OpenAI GPT 5](https://developer.box.com/guides/box-ai/ai-models/openai-gpt-5-model-card/) is now the default model for Box AI (Box AI for Hubs, Box AI for Documents, and Box AI for Notes Q\&A).

  **Note:** Models offered in **Preview** mode have not been fully performance-tested at scale and are provided on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-agents/ai-agent-overrides/) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-10-23">
  ## Box Windows SDK v6.0.0 released

  Introducing a new major version of Box Windows SDK V2 `v6` that includes two `namespaces` - the manually maintained `namespace` and the generated `namespace`. The coexisting `namespaces` provide easier access to the latest Box API features and support gradual migration to the standalone generated `namespace`.

  ### Breaking Changes

  * With `v6` of Box Windows SDK V2, support for .NET 6 has been dropped. We follow the official [.NET Release Lifecycle](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core). Since November 12, 2024, .NET 6 is no longer officially supported. While it may still be possible to compile and use this SDK under .NET 6, we do not provide support for issues encountered on that version.

  For more information about migrating to `v6` visit [`v5` to `v6` migration guide](https://github.com/box/box-windows-sdk-v2/blob/combined-sdk/migration-guides/from-v5-to-v6.md)

  ### What's New in `v6`

  With this SDK version, alongside the existing `Box.V2` `namespace`, we're introducing a new `Box.Sdk.Gen` `namespace`, which gives you access to:

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version allows you to gradually migrate your code base to the `Box.Sdk.Gen` `namespace`. The key differences between the `namespaces` are documented in the [`namespace` migration guide](https://github.com/box/box-windows-sdk-v2/blob/combined-sdk/migration-guides/from-box-v2-to-box-sdk-gen-namespace.md).

  Ultimately, we recommend to migrate to `v10` which includes only the generated `namespace` `Box.Sdk.Gen`. To migrate from `v6` to `v10` follow this [migration guide](https://github.com/box/box-windows-sdk-v2/blob/combined-sdk/migration-guides/from-v6-to-v10.md).

  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning/). Follow developer changelog for future updates.
</Update>

<Update label="2025-10-23">
  ## Box SDKs major version

  Introducing a new major release of Box SDKs that includes two packages — the manually maintained package and the generated package. The coexisting packages provide easier access to the latest Box API features and support gradual migration to the standalone generated package.

  ## Overview

  To facilitate this migration process, there are two actively maintained major Box core SDK versions:

  * **The latest major version that follows sequential versioning and includes** the manually maintained package and the generated one. This SDK version enables leveraging coexisting packages at the same time, and serves as a transition phase. Support for the consolidated version of each Box core SDK will continue in 2027.
  * `v10` that includes **only the generated package**, a consistent version number across all Box SDK artifacts.

  ## Additional information and migration guides

  For additional information on recommended actions and migration guides, visit [Box SDK versioning strategy page](https://developer.box.com/guides/tooling/sdks/sdk-versioning/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) or report issues directly in the individual Box SDK repositories on GitHub.
</Update>

<Update label="2025-10-23">
  ## Box Python SDK v4.0.0 released

  Introducing a new major version of Box Python SDK `v4` that includes two packages — the manually maintained `boxsdk` package and the generated `box_sdk_gen` package. The coexisting packages provide easier access to the latest Box API features and support gradual migration to the standalone generated package.

  ### Breaking Changes

  * `v4` of Box Python SDK  supports Python versions: 3.8+. Compared to `v3`, Python 3.6 and 3.7 are no longer supported.

  For more information about migrating to `v4` visit [`v3` to `v4` migration guide](https://github.com/box/box-python-sdk/blob/combined-sdk/migration-guides/from-v3-to-v4.md)

  ### What's New in `v4`

  With this SDK version, alongside the existing `boxsdk` package, we’re introducing a new `box_sdk_gen` package, which gives you access to:

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version allows you to gradually migrate your code base to the `box_sdk_gen` package. The key differences between the packages are documented in the [package migration guide](https://github.com/box/box-python-sdk/blob/combined-sdk/migration-guides/from-boxsdk-to-box_sdk_gen.md).

  Ultimately, we recommend to migrate to `v10` which includes only the generated `box_sdk_gen` package. To migrate from `v4` to `v10` follow this [migration guide](https://github.com/box/box-python-sdk/blob/combined-sdk/migration-guides/from-v4-to-v10.md).

  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning/). Follow developer changelog for future updates.
</Update>

<Update label="2025-10-23">
  ## Box Node SDK v4.0.0 released

  Introducing a new major version of Box Node SDK `v4` that includes two modules — the manually maintained module and the generated module. The coexisting modules provide easier access to the latest Box API features and support gradual migration to the standalone generated module.

  ### Breaking Changes

  * With `v4` of Box Node SDK, support for Node version below 18 has been dropped. While it may still be possible to download and use this SDK under Node below 18, we do not provide support for issues encountered on that version.

  * We have updated the module export style in the manually maintained `box-node-sdk` module to support the ES module and be more consistent with the generated `sdk-gen` module. Classes in the manual SDK are now exported as default exports from their respective files. When importing with `CommonJS` (`require`), use `.default` to access the class (e.g., `const BoxSDK = require('box-node-sdk').default;`).

  For more information about migrating to `v4` visit [`v3` to `v4` migration guide](https://github.com/box/box-node-sdk/blob/combined-sdk/migration-guides/from-v3-to-v4.md)

  ### What's New in `v4`

  With this SDK version, alongside the existing manually maintained module, we’re introducing a new generated `sdk-gen` module under `box-node-sdk/sdk-gen` import path, which gives you access to:

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version allows you to gradually migrate your code base to the `sdk-gen` module. The key differences between the modules are documented in the [module migration guide](https://github.com/box/box-node-sdk/blob/combined-sdk/migration-guides/from-box-node-sdk-to-sdk-gen.md).

  Ultimately, we recommend to migrate to `v10` which includes only the generated `sdk-gen` module. To migrate from `v4` to `v10` follow this [migration guide](https://github.com/box/box-node-sdk/blob/combined-sdk/migration-guides/from-v4-to-v10.md).

  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning/). Follow developer changelog for future updates.
</Update>

<Update label="2025-10-23">
  ## Box Java SDK v5.0.0 released

  Introducing a new major version of Box Java SDK `v5` that includes two packages — the manually maintained `com.box.sdk` package and the generated `com.box.sdkgen` package. The coexisting packages provide easier access to the latest Box API features and support gradual migration to the standalone generated package.

  There are no breaking changes between `v4` and `v5` of Box Java SDK. For more information about migrating to `v5` visit [`v4` to `v5` migration guide](https://github.com/box/box-java-sdk/blob/combined-sdk/migration-guides/from-v4-to-v5.md)

  ### What's New in `v5`

  With this SDK version, alongside the existing `com.box.sdk` package, we’re introducing a new `com.box.sdkgen` package, which gives you access to:

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version allows you to gradually migrate your code base to the `com.box.sdkgen` package. The key differences between the packages are documented in the [package migration guide](https://github.com/box/box-java-sdk/blob/combined-sdk/migration-guides/from-com-box-sdk-to-com-box-sdkgen.md).

  Ultimately, we recommend to migrate to `v10` which includes only the generated `com.box.sdkgen` package. To migrate from `v5` to `v10` follow this [migration guide](https://github.com/box/box-java-sdk/blob/combined-sdk/migration-guides/from-v5-to-v10.md).

  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning/). Follow developer changelog for future updates.
</Update>

<Update label="2025-10-23">
  ## Box iOS SDK 6.0.0 released

  Introducing a new major version of Box iOS SDK `v6` that includes two modules — the manually maintained module and the generated module. The coexisting modules provide easier access to the latest Box API features and support gradual migration to the standalone generated module.

  ### Breaking Changes

  * With `v6` of Box iOS SDK, support for `iOS 11.0`, `macOS 10.13`, `tvOS 11.0` and `watchOS 4.0` has been dropped.

  Starting with `v6`, the minimum supported versions are `iOS 13.0`, `macOS 10.15`, `tvOS 13.0`, and `watchOS 6.0`.

  This update aligns the SDK with current Apple development standards and is required to adopt the new features available in the BoxSdkGen module.

  For the latest submission and SDK `toolchain` requirements, see Apple’s SDK minimum requirements [Apple Developer](https://developer.apple.com/news/upcoming-requirements/?id=02212025a).

  For more information about migrating to `v6` visit [`v5` to `v6` migration guide](https://github.com/box/box-ios-sdk/blob/combined-sdk/migration-guides/from-v5-to-v6.md).

  ### What's New in `v6`

  With this SDK version, alongside the existing `BoxSDK` module, we’re introducing a new `BoxSdkGen` module, which gives you access to:

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version allows you to gradually migrate your code base to the `BoxSdkGen` module. The key differences between the modules are documented in the [module migration guide](https://github.com/box/box-ios-sdk/blob/combined-sdk/migration-guides/from-BoxSDK-to-BoxSdkGen.md).

  Ultimately, we recommend to migrate to `v10` which includes only the generated module `BoxSdkGen`. To migrate from `v6` to `v10` follow this [migration guide](https://github.com/box/box-ios-sdk/blob/combined-sdk/migration-guides/from-v6-to-v10.md).

  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning/). Follow developer changelog for future updates.
</Update>

<Update label="2025-10-21">
  ## Box CLI v4.4.1 released

  ### Bug Fixes

  * Fix the `--exempt-from-2fa` flag in `create` and `update` users commands ([#598](https://github.com/box/boxcli/issues/598)) ([`8f897fe`](https://github.com/box/boxcli/commit/8f897feb677a0089e7854aaf8ef6b2babb70ab16))
</Update>

<Update label="2025-10-14">
  ## Box CLI v4.4.0 released

  ### New Features and Enhancements

  * Support update users notification email ([#596](https://github.com/box/boxcli/issues/596)) ([`49356f4`](https://github.com/box/boxcli/commit/49356f4ad954caf0c0d60646debc2bc047bddf7a))
</Update>

<Update label="2025-10-06">
  ## Box Windows SDK v10.1.0 released

  ### Bug Fixes

  * Allow flexible key-value data in `AiExtractResponse.answer` and `Event.additionalDetails` (box/box-openapi[#556](https://github.com/box/box-windows-sdk-v2/issues/556)) ([#1147](https://github.com/box/box-windows-sdk-v2/issues/1147)) ([`c41a444`](https://github.com/box/box-windows-sdk-v2/commit/c41a4449a27be4484f986c3260950ae863c1285c))
  * Make `role` parameter of update collaboration optional (box/box-openapi[#557](https://github.com/box/box-windows-sdk-v2/issues/557)) ([#1156](https://github.com/box/box-windows-sdk-v2/issues/1156)) ([`8247918`](https://github.com/box/box-windows-sdk-v2/commit/824791817bd4c65770f2ef65bb7b0eb3b48b892b))

  ### New Features and Enhancements

  * Handle Dictionary with object values deserialization (box/box-codegen[#850](https://github.com/box/box-windows-sdk-v2/issues/850)) ([#1144](https://github.com/box/box-windows-sdk-v2/issues/1144)) ([`611b474`](https://github.com/box/box-windows-sdk-v2/commit/611b47424ff8773b9aabfb772a65f0ebca754e9e))
</Update>

<Update label="2025-10-06">
  ## Box Python SDK v10.0.1 released

  ### Bug Fixes

  * Allow flexible key-value data in `AiExtractResponse.answer` and `Event.additionalDetails` (box/box-openapi[#556](https://github.com/box/box-python-sdk/issues/556)) ([#1084](https://github.com/box/box-python-sdk/issues/1084)) ([`f63cffe`](https://github.com/box/box-python-sdk/commit/f63cffec92ccf98af21d6227328aab00fa159187))
  * Make `role` parameter of update collaboration optional (box/box-openapi[#557](https://github.com/box/box-python-sdk/issues/557)) ([#1093](https://github.com/box/box-python-sdk/issues/1093)) ([`5c21907`](https://github.com/box/box-python-sdk/commit/5c21907869d359fdb8fe4c83317a9eca5aeffdc3))
</Update>

<Update label="2025-10-06">
  ## Box Node SDK v10.0.1 released

  ### Bug Fixes

  * Allow flexible key-value data in `AiExtractResponse.answer` and `Event.additionalDetails` (box/box-openapi[#556](https://github.com/box/box-node-sdk/issues/556)) ([#1051](https://github.com/box/box-node-sdk/issues/1051)) ([`70a2275`](https://github.com/box/box-node-sdk/commit/70a2275ada40f079178166d60c7f5d0a48bd5e40))
  * Make `role` parameter of update collaboration optional (box/box-openapi[#557](https://github.com/box/box-node-sdk/issues/557)) ([#1068](https://github.com/box/box-node-sdk/issues/1068)) ([`3992171`](https://github.com/box/box-node-sdk/commit/3992171af8587d9f43888ecd2fcbcd70a9f1b2b6))
  * Relax JSON deserialization guard by removing strict `content-type` check (box/box-codegen[#844](https://github.com/box/box-node-sdk/issues/844)) ([#1033](https://github.com/box/box-node-sdk/issues/1033)) ([`1eb2c32`](https://github.com/box/box-node-sdk/commit/1eb2c32a923be1762bf9dfbb2dfdb9e5b3e78af5))
</Update>

<Update label="2025-10-06">
  ## Box Java SDK v10.1.0 released

  ### Bug Fixes

  * Allow flexible key-value data in `AiExtractResponse.answer` and `Event.additionalDetails` (box/box-openapi[#556](https://github.com/box/box-java-sdk/issues/556)) ([#1470](https://github.com/box/box-java-sdk/issues/1470)) ([`e215a5f`](https://github.com/box/box-java-sdk/commit/e215a5f2502e694421a05d8da550d2b305c09460))
  * Make `role` parameter of update collaboration optional (box/box-openapi[#557](https://github.com/box/box-java-sdk/issues/557)) ([#1479](https://github.com/box/box-java-sdk/issues/1479)) ([`6896386`](https://github.com/box/box-java-sdk/commit/6896386c6086996399066b09b5afc998a5a95ca4))

  ### New Features and Enhancements

  * Add `Javadoc` comments (box/box-codegen[#839](https://github.com/box/box-java-sdk/issues/839)) ([#1465](https://github.com/box/box-java-sdk/issues/1465)) ([`c72407d`](https://github.com/box/box-java-sdk/commit/c72407dc77cc67f3a178d607a2b1bd4e90e832a8))
</Update>

<Update label="2025-10-06">
  ## Box iOS SDK 10.0.1 released

  ### Bug Fixes

  * Allow flexible key-value data in `AiExtractResponse.answer` and `Event.additionalDetails` (box/box-openapi[#556](https://github.com/box/box-ios-sdk/issues/556)) ([#1128](https://github.com/box/box-ios-sdk/issues/1128)) ([`3e9a78c`](https://github.com/box/box-ios-sdk/commit/3e9a78ce710b0161e0912d1ee6af0b7758875fbc))
  * Make `role` parameter of update collaboration optional (box/box-openapi[#557](https://github.com/box/box-ios-sdk/issues/557)) ([#1138](https://github.com/box/box-ios-sdk/issues/1138)) ([`3fc5dc9`](https://github.com/box/box-ios-sdk/commit/3fc5dc9a62bd0cabc8987d56c0d63b94fa7ef14d))
</Update>

<Update label="2025-10-03">
  ## Box Java SDK v4.16.4 released

  ### Bug Fixes

  * Bump Bouncy Castle to fix `CVE-2025-8916` ([#1454](https://github.com/box/box-java-sdk/issues/1454)) ([`a3605f4`](https://github.com/box/box-java-sdk/commit/a3605f47b4c5ee6b053f0940f9a06cba0a5c2584))
</Update>

<Update label="2025-10-01">
  ## Salesforce Developer Toolkit updates

  The developer guides for the [Salesforce Developer Toolkit](https://developer.box.com/guides/tooling/salesforce-toolkit/) have been updated to include:

  * Methods and operations for [Box Sign](https://developer.box.com/guides/tooling/salesforce-toolkit/methods/#box-sign) and [Box Hubs](https://developer.box.com/guides/tooling/salesforce-toolkit/methods/#box-hubs)
  * Code samples for [Box Sign](https://developer.box.com/guides/tooling/salesforce-toolkit/samples/#create-a-sign-request) and [Box Hubs](https://developer.box.com/guides/tooling/salesforce-toolkit/samples/#get-box-hubs)
  * All methods that can be invoked in [Salesforce Flows](https://developer.box.com/guides/tooling/salesforce-toolkit/flow-actions/#methods-in-salesforce-flows)
  * Methods in Agentforce Flows for [Box Hubs](https://developer.box.com/guides/tooling/salesforce-toolkit/box-agentforce-package/#box-hubs)
</Update>

<Update label="2025-10-01">
  ## Box UI Elements v25.1.0 released

  ### [25.1.0](https://github.com/box/box-ui-elements/compare/v25.0.0...v25.1.0) (2025-10-01)

  ### Bug Fixes

  * **i18n:** update translations ([#4298](https://github.com/box/box-ui-elements/issues/4298)) ([`86df699`](https://github.com/box/box-ui-elements/commit/86df69972d8e2ea1c176daf4ba9b2b8484fd8504))
  * **security-cloud-game:** Use nodeRef in DragCloud for React 19 ([#4286](https://github.com/box/box-ui-elements/issues/4286)) ([`ee8cba8`](https://github.com/box/box-ui-elements/commit/ee8cba848001708bd98ec889523527185a12c1ff))

  ### Features

  * **content-sharing:** Convert Content Sharing V2 API Response ([#4285](https://github.com/box/box-ui-elements/issues/4285)) ([`6730ffe`](https://github.com/box/box-ui-elements/commit/6730ffe42cbdddae325f196875b8765405ca3186))
  * **content-sidebar:** handle success event for creating metadata instance ([#4284](https://github.com/box/box-ui-elements/issues/4284)) ([`371c1a9`](https://github.com/box/box-ui-elements/commit/371c1a9843f31af78b667b3f80dd6319b1c5d6ff))
  * **content-sidebar:** implement for custom sidebar panels ([#4239](https://github.com/box/box-ui-elements/issues/4239)) ([`750737c`](https://github.com/box/box-ui-elements/commit/750737cb6c0b3fb10e7794183fde8c63373ee673))
  * **item-properties:** Add files count for folder in item properties ([#4283](https://github.com/box/box-ui-elements/issues/4283)) ([`f12340a`](https://github.com/box/box-ui-elements/commit/f12340a30286781d5a35ed57dcf59ccca2499c99))
  * **video-annotations:** sidebar support for video annotations ([#4318](https://github.com/box/box-ui-elements/issues/4318)) ([`aa5fc16`](https://github.com/box/box-ui-elements/commit/aa5fc1667f8693ba11b072aa35075e1f073a0241))

  ### Reverts

  * "chore(mergify): update circleci and mergify configuration ([#4](https://github.com/box/box-ui-elements/issues/4)… ([#4296](https://github.com/box/box-ui-elements/issues/4296)) ([`b915e45`](https://github.com/box/box-ui-elements/commit/b915e45fd8abc702fbdd99eb0bb4b411e00e7ef2)), closes [#4295](https://github.com/box/box-ui-elements/issues/4295)
</Update>

<Update label="2025-09-30">
  ## Box AI API - AWS Claude 4.5 Sonnet now available

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with AWS Claude 4.5 Sonnet.

  Models offered in **Preview** mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-models) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-09-29">
  ## Box CLI v4.3.1 released

  ### Bug Fixes

  * Fix multi item mode in `ai:ask` command ([#593](https://github.com/box/boxcli/issues/593)) ([`5081d43`](https://github.com/box/boxcli/commit/5081d432d8ded16c8bf759352d28be0214fbe4ec))
</Update>

<Update label="2025-09-26">
  ## Box UI Elements v25.0.0 released

  ### [25.0.0](https://github.com/box/box-ui-elements/compare/v24.0.0...v25.0.0) (2025-09-26)

  ### Bug Fixes

  * **classification:** use `AsyncLoad` for `AppliedByAiClassificationReason` ([#4274](https://github.com/box/box-ui-elements/issues/4274)) ([`b80df38`](https://github.com/box/box-ui-elements/commit/b80df3853c94a93fecac1d242bea11fce51cef00))
  * **common:** Remove `findDOMNode` from `makeDroppable` (BREAKING CHANGE) ([#4276](https://github.com/box/box-ui-elements/issues/4276)) ([`c3bcad3`](https://github.com/box/box-ui-elements/commit/c3bcad39d81692c1d831e090ff3664c07e0ae987))
  * **i18n:** update translations ([#4269](https://github.com/box/box-ui-elements/issues/4269)) ([`d27c054`](https://github.com/box/box-ui-elements/commit/d27c054e985386fcce723c8929a33eb5c0f1500f))
  * **i18n:** update translations ([#4272](https://github.com/box/box-ui-elements/issues/4272)) ([`9f3520b`](https://github.com/box/box-ui-elements/commit/9f3520b8f63aa7445a83ece2cf0e12610484c506))
  * **i18n:** update translations ([#4277](https://github.com/box/box-ui-elements/issues/4277)) ([`23b27f6`](https://github.com/box/box-ui-elements/commit/23b27f6ef48d4928a7f685ec084174f4b0e7e322))
  * **i18n:** update translations ([#4280](https://github.com/box/box-ui-elements/issues/4280)) ([`7c633b8`](https://github.com/box/box-ui-elements/commit/7c633b85f7c75e0948e7d38db0417f40e7c79f7c))
  * **i18n:** update translations ([#4289](https://github.com/box/box-ui-elements/issues/4289)) ([`8453128`](https://github.com/box/box-ui-elements/commit/8453128761a7d239f24654d59992ab38ac9ca501))
  * **metadata-view:** show error state when exception is thrown ([#4270](https://github.com/box/box-ui-elements/issues/4270)) ([`246f2df`](https://github.com/box/box-ui-elements/commit/246f2dfb3d12f1805ffac279eeceb1f9d59daef8))
  * **metadataeditor:** portal dropdown to preview container ([#4273](https://github.com/box/box-ui-elements/issues/4273)) ([`540a957`](https://github.com/box/box-ui-elements/commit/540a9575b3e16b23a8affb7ec12dad0ad7406735))

  ### Features

  * **classification:** `AppliedByAiClassificationReason` card to support empty reason ([#4279](https://github.com/box/box-ui-elements/issues/4279)) ([`cb04234`](https://github.com/box/box-ui-elements/commit/cb04234576cfc65c61402035c03d4a026a5eb08b))
  * **classification:** support AI reasoning and new applied by labels ([#4271](https://github.com/box/box-ui-elements/issues/4271)) ([`681bace`](https://github.com/box/box-ui-elements/commit/681bace22e3b2c7cc381c73855c1d1dd6b4f1548))
  * **content-sharing:** Create `ContentSharingV2` component ([#4282](https://github.com/box/box-ui-elements/issues/4282)) ([`ef49c77`](https://github.com/box/box-ui-elements/commit/ef49c773b63fb240c115308c48030f46d46971a5))
  * **metadata-view:** bump metadata view version ([#4287](https://github.com/box/box-ui-elements/issues/4287)) ([`f5887d7`](https://github.com/box/box-ui-elements/commit/f5887d74f689dd79e41ca2979d3a2430fc8b8bda))
  * **metadata-view:** update blueprint web version ([#4288](https://github.com/box/box-ui-elements/issues/4288)) ([`6d599a3`](https://github.com/box/box-ui-elements/commit/6d599a3f7a3cc7f8f9f7a724e1d5a7b29522351a))
  * **timestamped-comments:** enable timestamp handling in sidebar ([#4275](https://github.com/box/box-ui-elements/issues/4275)) ([`7f9defa`](https://github.com/box/box-ui-elements/commit/7f9defa1dae1faff823b414b708f164913aa701e)), closes [#4226](https://github.com/box/box-ui-elements/issues/4226) [#4230](https://github.com/box/box-ui-elements/issues/4230) [#4274](https://github.com/box/box-ui-elements/issues/4274)
  * **timestamped-comments:** timestamped comments editor updates ([#4244](https://github.com/box/box-ui-elements/issues/4244)) ([`6e1bd80`](https://github.com/box/box-ui-elements/commit/6e1bd8060212d35529fcb0dcc4b7abd77470941d)), closes [#4226](https://github.com/box/box-ui-elements/issues/4226) [#4230](https://github.com/box/box-ui-elements/issues/4230)

  ### BREAKING CHANGES

  * **common:** Wrapped component of `makeDroppable` must have ref prop,
    for example with `React.forwardRef`

  * fix: Clean up tests
</Update>

<Update label="2025-09-05">
  ## Metadata view v2 in Content Explorer

  We introduced `v2` of the [metadata view in the Box Content Explorer](/guides/embed/ui-elements/explorer-metadata-v2) UI element.
  It's a ground-up redesign of the original version, introducing a streamlined interface tailored for metadata-driven workflows.

  ## Key features

  * filtering and editing interfaces with dedicated UI for each metadata field type,
  * flexible display options with list and grid views,
  * pagination support.

  ## Migration from `v1` to `v2`

  The `v1` of the metadata view Content Explorer has reached end of support and it will no longer receive bug fixes or new features.
  We recommend to migrate to the new `v2` metadata view. See the [migration guide](/guides/embed/ui-elements/explorer-metadata-v2/#migrating-from-v1-to-v2) for a detailed instruction.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/) for any help needed.
</Update>

<Update label="2025-09-17">
  ## Box Windows SDK v10.0.0 released

  Introducing **`Box SDK v10`**, a major release designed to elevate your developer experience and streamline integration with Box Content Cloud. Currently available as a separate [`sdk-gen`](https://github.com/box/box-windows-sdk-v2/tree/sdk-gen) branch, `v10` will ultimately become the main branch.

  ### Breaking Changes

  * This SDK version is auto-generated and introduces a new interface for all methods. Extensive documentation is available [here](https://github.com/box/box-windows-sdk-v2/tree/sdk-gen/docs).

  ### What's New in `v10`

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version includes the Box Next Generation SDK artifact, previously developed in parallel to core Box SDKs. To facilitate migration and provide access to the newest features, we'll soon release an additional major version combining both artifacts. Migration to `v10` includes breaking changes, please review the [migration guide](https://github.com/box/box-windows-sdk-v2/blob/sdk-gen/migration-guides/from-v5-to-v10.md) for details.  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning/). Follow developer changelog for future updates.

  ***

  ### What’s New Compared to [Dotnet SDK Gen](https://github.com/box/box-dotnet-sdk-gen) `v1.12.0`

  #### ⚠ BREAKING CHANGES

  * Change names of unions (box/box-openapi[#549](https://github.com/box/box-windows-sdk-v2/issues/549)) ([#1007](https://github.com/box/box-windows-sdk-v2/issues/1007)) ([`fcef4ec`](https://github.com/box/box-windows-sdk-v2/commit/fcef4ecab38435fb4a79e2db8fcf2c5ad931986b))
  * Remove unused models from schemas (box/box-openapi[#547](https://github.com/box/box-windows-sdk-v2/issues/547)) ([#999](https://github.com/box/box-windows-sdk-v2/issues/999)) ([`ffcb488`](https://github.com/box/box-windows-sdk-v2/commit/ffcb4888e6ad52f10028f92c49b5d919cb1ac620))

  #### Bug Fixes

  * Fix `net462` debug build ([#1020](https://github.com/box/box-windows-sdk-v2/issues/1020)) ([`04f8343`](https://github.com/box/box-windows-sdk-v2/commit/04f8343c200e45ebe65bd29f03f55a44e76bcbde))
  * Rename external user deletion method (box/box-codegen[#796](https://github.com/box/box-windows-sdk-v2/issues/796)) ([#1024](https://github.com/box/box-windows-sdk-v2/issues/1024)) ([`13928c5`](https://github.com/box/box-windows-sdk-v2/commit/13928c559bd3e97d060c48997b05ca384333d03d))

  #### New Features and Enhancements

  * Add External User Deletion API (box/box-openapi[#550](https://github.com/box/box-windows-sdk-v2/issues/550)) ([#1009](https://github.com/box/box-windows-sdk-v2/issues/1009)) ([`2178bc8`](https://github.com/box/box-windows-sdk-v2/commit/2178bc87c8b724598616e99f0a528c7b21ff12c6))
  * Add missing webhook events (box/box-openapi[#554](https://github.com/box/box-windows-sdk-v2/issues/554)) ([#1068](https://github.com/box/box-windows-sdk-v2/issues/1068)) ([`7fe3b99`](https://github.com/box/box-windows-sdk-v2/commit/7fe3b99cae1cf5be9ad3ec7bec54c97f198fd8c7))
  * Add Net Framework 462 support for `v10` (box/box-codegen[#773](https://github.com/box/box-windows-sdk-v2/issues/773)) ([#986](https://github.com/box/box-windows-sdk-v2/issues/986)) ([`67366c7`](https://github.com/box/box-windows-sdk-v2/commit/67366c7274faa5c758490d393605c76220aa6a79))
  * Allow injecting custom decryption mechanism for `jwt` ([#974](https://github.com/box/box-windows-sdk-v2/issues/974)) ([`b877355`](https://github.com/box/box-windows-sdk-v2/commit/b877355493b60dc6f9c1a576927d6e0c62ec27f3))

  For more details check [migration guide](https://github.com/box/box-windows-sdk-v2/blob/sdk-gen/migration-guides/from-dotnet-sdk-gen-v1-to-box-windows-sdk-v10.md) from `box-dotnet-sdk-gen` `v1` to `box-windows-sdk-v2` `v10`.
</Update>

<Update label="2025-09-17">
  ## Box SDKs v10

  Introducing Box SDKs `v10`, a major release designed to elevate your developer experience and streamline integration with Box Content Cloud. Currently available as a separate branch for each SDK, `v10` will ultimately become the main branch.

  What's new in `v10`:

  * Full API support — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.
  * Rapid API updates — Our new auto-generation approach enables Box API additions within days, ensuring that you can leverage the most up-to-date features without delay.
  * Embedded documentation — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.
  * Enhanced convenience methods — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  This version includes the Box Next Generation SDK artifact, previously developed in parallel to Box core SDKs. To facilitate migration and provide access to the newest features, we'll soon release an additional major version containing both artifacts.
  No immediate action required — If you're using the current SDK version, your existing code will continue to work without changes. However, migrating to `v10` includes breaking changes. For more information and migration guides, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning). Follow the developer changelog for future updates.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/) for any help needed.
</Update>

<Update label="2025-09-17">
  ## Box Next Generation SDK deprecation

  As of September 17, 2025 Box Next Generation SDKs are no longer supported as separate artifacts. Don’t worry, your existing code will continue to work without changes. You can still use your applications based on Box Next Generation SDKs with no impact, but you won't receive new features, updates, or bug fixes.

  In keeping with industry best practices, we are consolidating the Box Next Generation SDKs and Box core SDKs into a single package for each programming language. This makes migration efforts much easier and allows seamless addition of new capabilities to existing applications still powered by Box core SDKs, which were maintained manually.

  All future development, including new features and updates for the Next Generation SDKs, will be delivered through Box core SDKs starting with version `v10`. Currently, `v10` is available as a separate branch.

  For more information and migration guides, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning). Follow the developer changelog for future updates.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/) for any help needed.
</Update>

<Update label="2025-09-17">
  ## Box Java SDK v10.0.0 released

  Introducing **`Box SDK v10`**, a major release designed to elevate your developer experience and streamline integration with Box Content Cloud. Currently available as a separate [`sdk-gen`](https://github.com/box/box-java-sdk/tree/sdk-gen) branch, `v10` will ultimately become the main branch.

  ### Breaking Changes

  * This SDK version is auto-generated and introduces a new interface for all methods. Extensive documentation is available [here](https://github.com/box/box-java-sdk/tree/sdk-gen/docs).

  ### What's New in `v10`

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version includes the Box Next Generation SDK artifact, previously developed in parallel to core Box SDKs. To facilitate migration and provide access to the newest features, we'll soon release an additional major version combining both artifacts. Migration to `v10` includes breaking changes, please review the [migration guide](https://github.com/box/box-java-sdk/blob/sdk-gen/migration-guides/from-v4-to-v10.md) for details.  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning). Follow developer changelog for future updates.

  ***

  ### What’s New Compared to [Java SDK Gen](https://github.com/box/box-java-sdk-gen) `v0.8.1`

  #### ⚠ BREAKING CHANGES

  * Change names of unions (box/box-codegen[#787](https://github.com/box/box-java-sdk/issues/787)) ([#1359](https://github.com/box/box-java-sdk/issues/1359)) ([`114e778`](https://github.com/box/box-java-sdk/commit/114e7785031e19fb58933f231e656a991b5effb7))
  * Remove unused models from schemas (box/box-openapi[#547](https://github.com/box/box-java-sdk/issues/547)) ([#1354](https://github.com/box/box-java-sdk/issues/1354)) ([`e031308`](https://github.com/box/box-java-sdk/commit/e031308f102137351238bf3823372150d3927442)), closes [box/`box-openapi#542`](https://github.com/box/box-openapi/issues/542) [box/`box-openapi#544`](https://github.com/box/box-openapi/issues/544) [box/`box-codegen#781`](https://github.com/box/box-java-sdk/issues/781) [box/`box-openapi#545`](https://github.com/box/box-openapi/issues/545) [`box/box-codegen#782`](https://github.com/box/box-java-sdk/issues/782)
  * Replace `Date` with `OffsetDateTime` (box/box-codegen[#826](https://github.com/box/box-java-sdk/issues/826)) ([#1419](https://github.com/box/box-java-sdk/issues/1419)) ([`ed04407`](https://github.com/box/box-java-sdk/commit/ed04407e8effa8811bc85023783097f8a95e5223))

  #### New Features and Enhancements

  * Add proxy support (box/box-codegen[#830](https://github.com/box/box-java-sdk/issues/830)) ([#1424](https://github.com/box/box-java-sdk/issues/1424)) ([`cc53247`](https://github.com/box/box-java-sdk/commit/cc532475cdaf5ec3fd710149b41a6e7b04dcd32f))

  For more details check [migration guide](https://github.com/box/box-java-sdk/blob/sdk-gen/migration-guides/from-box-java-sdk-gen-v0-to-box-java-sdk-v10.md) from `box-java-sdk-gen` `v0` to `box-java-sdk` `v10`.
</Update>

<Update label="2025-09-17">
  ## Box iOS SDK 10.0.0 released

  Introducing **`Box iOS SDK v10`**, a major release designed to elevate your developer experience and streamline integration with Box Content Cloud. Currently available as a separate [`sdk-gen`](https://github.com/box/box-ios-sdk/tree/sdk-gen) branch, `v10` will ultimately become the main branch.

  ### Breaking Changes

  * This SDK version is auto-generated and introduces a new interface for all methods. Extensive documentation is available [here](https://github.com/box/box-ios-sdk/tree/sdk-gen/docs).

  ### What's New in `v10`

  * **Full API Support** — Complete coverage of the Box API ecosystem, giving you access to all the latest features and functionalities to build feature-rich applications.

  * **Rapid API Updates** — Our new auto-generation approach enables Box API additions within days, ensuring you can leverage the most up-to-date features without delay.

  * **Embedded Documentation** — All objects and parameters are documented directly in the SDK source code, keeping essential information in one place.

  * **Enhanced Convenience Methods** — New methods for authentication, chunk uploads, automatic retries, retry strategy, and more.

  ### Important Notes

  This version includes the Box Next Generation SDK artifact, previously developed in parallel to core Box SDKs. To facilitate migration and provide access to the newest features, we'll soon release an additional major version combining both artifacts. Migration to `v10` includes breaking changes, please review the [migration guide](https://github.com/box/box-ios-sdk/blob/sdk-gen/migration-guides/from-v5-to-v10.md) for details.  For more information, see the [SDK versioning strategy document](https://developer.box.com/guides/tooling/sdks/sdk-versioning). Follow developer changelog for future updates.

  ***

  ### What’s New Compared to [Box Swift SDK Gen](https://github.com/box/box-swift-sdk-gen) `v0.6.3`

  ### New Features and Enhancements

  * Add External User Deletion API (box/box-codegen[#550](https://github.com/box/box-ios-sdk/issues/969)) ([`74571fb`](https://github.com/box/box-ios-sdk/commit/74571fb6675d0ff90d0ec4ef2baf7113816093f8))
  * Add missing webhook events (box/box-openapi[#554](https://github.com/box/box-ios-sdk/issues/554)) ([#1048](https://github.com/box/box-ios-sdk/issues/1048)) ([`b8bf1ad`](https://github.com/box/box-ios-sdk/commit/b8bf1add360119f70a626f663cd810f9598ec794))
  * Retry requests for network errors in Swift (box/box-codegen[#820](https://github.com/box/box-ios-sdk/issues/820)) ([#1051](https://github.com/box/box-ios-sdk/issues/1051)) ([`ba21450`](https://github.com/box/box-ios-sdk/commit/ba214507b37d2a842bcf044b5b4392b442486d6f))

  For more details check [migration guide](https://github.com/box/box-ios-sdk/blob/sdk-gen/migration-guides/from-box-swift-sdk-gen-v0-to-box-ios-sdk-v10.md) from `box-swift-sdk-gen` `v0` to `box-ios-sdk` `v10`.
</Update>

<Update label="2025-09-16">
  ## Box TypeScript SDK Generated v1.19.1 released

  ### Bug Fixes

  * Fix ESM build and add test set (box/box-codegen[#828](https://github.com/box/box-typescript-sdk-gen/issues/828)) ([#768](https://github.com/box/box-typescript-sdk-gen/issues/768)) ([`c198527`](https://github.com/box/box-typescript-sdk-gen/commit/c19852701d4e14eb6f6a9c7f24b4621d57a08b60))
</Update>

<Update label="2025-09-05">
  ## Box UI Elements v24.0.0 released

  ### [24.0.0](https://github.com/box/box-ui-elements/compare/v23.4.0...v24.0.0) (2025-09-05)

  ### Bug Fixes

  * **blueprint-web:** Upgrade blueprint-web packages ([#4261](https://github.com/box/box-ui-elements/issues/4261)) ([`ac48f93`](https://github.com/box/box-ui-elements/commit/ac48f9313b4603cbae3ac7daf8be36cf84d0bdb1))
  * **blueprint:** Blueprint Modernization ([#4204](https://github.com/box/box-ui-elements/issues/4204)) ([`29030a9`](https://github.com/box/box-ui-elements/commit/29030a9a8c50eaa3b94c463993bc44dd2cc439ff))
  * **box-ai:** Fix suggested questions not appearing ([#4249](https://github.com/box/box-ui-elements/issues/4249)) ([`0c63595`](https://github.com/box/box-ui-elements/commit/0c63595299ea25408cabe6a4d846e7a34df74ee9))
  * **box-ai:** Update box-ai-content-answers peer dependency version ([#4238](https://github.com/box/box-ui-elements/issues/4238)) ([`8967acf`](https://github.com/box/box-ui-elements/commit/8967acf340eb96c4a50e11934c022cd10af1c42b))
  * **content-explorer:** Fix flaky SubheaderV2 folder title ([#4229](https://github.com/box/box-ui-elements/issues/4229)) ([`330ae33`](https://github.com/box/box-ui-elements/commit/330ae3398998c7e05778a52f15f2e5d0f815a0b3))
  * **content-explorer:** Fix grid selection ([#4267](https://github.com/box/box-ui-elements/issues/4267)) ([`4beb05d`](https://github.com/box/box-ui-elements/commit/4beb05d307a142331d55030fe35154c26dd4b1a5))
  * **content-explorer:** Validate selected item ids after item changes ([#4268](https://github.com/box/box-ui-elements/issues/4268)) ([`baaaa83`](https://github.com/box/box-ui-elements/commit/baaaa83462ef6b307992a9f6d800e62c8c668d16))
  * **i18n:** update translations ([#4241](https://github.com/box/box-ui-elements/issues/4241)) ([`5e7030a`](https://github.com/box/box-ui-elements/commit/5e7030adc2e0ad683c11329dc00ab8dbd911aea7))
  * **i18n:** update translations ([#4247](https://github.com/box/box-ui-elements/issues/4247)) ([`29f266c`](https://github.com/box/box-ui-elements/commit/29f266cbaa554d528766207ca22d9ab544686e36))
  * **i18n:** update translations ([#4253](https://github.com/box/box-ui-elements/issues/4253)) ([`f9e4e79`](https://github.com/box/box-ui-elements/commit/f9e4e7922d4efda3addbea621f71aaee38475385))
  * **i18n:** update translations ([#4254](https://github.com/box/box-ui-elements/issues/4254)) ([`59e30e3`](https://github.com/box/box-ui-elements/commit/59e30e3ac5eb1798456f228558f30f42d1b4ac2d))
  * **i18n:** update translations ([#4258](https://github.com/box/box-ui-elements/issues/4258)) ([`2522af9`](https://github.com/box/box-ui-elements/commit/2522af9d1ee562ec8f838263422c5ce30edc6be0))
  * **i18n:** update translations ([#4259](https://github.com/box/box-ui-elements/issues/4259)) ([`d3c5a78`](https://github.com/box/box-ui-elements/commit/d3c5a78fb8962acb92cdd91dccc497f05abdf164))
  * **i18n:** update translations ([#4264](https://github.com/box/box-ui-elements/issues/4264)) ([`8118ab6`](https://github.com/box/box-ui-elements/commit/8118ab6ae814daad43848e626b711fe3e92b00e8))
  * **metadata-view:** default iconcolumnvariant ([#4262](https://github.com/box/box-ui-elements/issues/4262)) ([`141cf6e`](https://github.com/box/box-ui-elements/commit/141cf6e1cc7c61a989c7bffbc5215d02c6d4f4c5))
  * **metadata-view:** Enable sorting dropdown ([#4265](https://github.com/box/box-ui-elements/issues/4265)) ([`fac795f`](https://github.com/box/box-ui-elements/commit/fac795f44248bb444c489d0512344a9f72b188d7))
  * **metadata-view:** fix filtering file extensions and filters visibility ([#4257](https://github.com/box/box-ui-elements/issues/4257)) ([`504aed7`](https://github.com/box/box-ui-elements/commit/504aed76ea4fab168ec9ad8b5190f1dfc15c781c))
  * **metadata-view:** fix filtering folders and files ([#4255](https://github.com/box/box-ui-elements/issues/4255)) ([`bdd6d1d`](https://github.com/box/box-ui-elements/commit/bdd6d1d6c521cf147a6fa89428560e1b9f65b9b7))
  * **metadata-view:** Hide keyword and location filters ([#4260](https://github.com/box/box-ui-elements/issues/4260)) ([`1ca5029`](https://github.com/box/box-ui-elements/commit/1ca5029a5287f7aad3aefe5d2e4cfed26c301e5e))
  * **metadata-view:** Use internal pagination ([#4263](https://github.com/box/box-ui-elements/issues/4263)) ([`b274e73`](https://github.com/box/box-ui-elements/commit/b274e73216a5f8195f1f15cd82414ae19d1273e8))
  * set version in release assets ([#4266](https://github.com/box/box-ui-elements/issues/4266)) ([`1ba15df`](https://github.com/box/box-ui-elements/commit/1ba15dfbb119b82515d263a5610a0725d6819949))

  ### Features

  * add client version to element api calls ([#4198](https://github.com/box/box-ui-elements/issues/4198)) ([`468d6c1`](https://github.com/box/box-ui-elements/commit/468d6c13d5e1b5c574f99442a22cdbb362d24485))
  * **box-ai:** Bump box-ai-content-answers version ([#4233](https://github.com/box/box-ui-elements/issues/4233)) ([`47cea9f`](https://github.com/box/box-ui-elements/commit/47cea9f604fafd686c03aeb42b9b14893d7dae0e))
  * **classification:** implement AppliedByAiClassificationReason ([#4250](https://github.com/box/box-ui-elements/issues/4250)) ([`e23fbf3`](https://github.com/box/box-ui-elements/commit/e23fbf303609bf6ee03ac35135dda57060346660))
  * **content-explorer:** Add initial filter values to Metadata View ([#4225](https://github.com/box/box-ui-elements/issues/4225)) ([`b68cd70`](https://github.com/box/box-ui-elements/commit/b68cd705b2720125c9b132a81ff6dd2f4abe3efc))
  * **metadata-instance-editor:** remove ai agent selector split and fi… ([#4226](https://github.com/box/box-ui-elements/issues/4226)) ([`1f953c0`](https://github.com/box/box-ui-elements/commit/1f953c08decd3113f855aceada1a8513e74582f9))
  * **metadata-view:** Add Filtering ([#4235](https://github.com/box/box-ui-elements/issues/4235)) ([`2f5e42b`](https://github.com/box/box-ui-elements/commit/2f5e42b9e36618dc6d9880812ee425eb5c799b29))
  * **metadata-view:** bulk custom actions ([#4227](https://github.com/box/box-ui-elements/issues/4227)) ([`371ad5e`](https://github.com/box/box-ui-elements/commit/371ad5eeb38cabe162d1b8bb0ab9eb6f8378deab))
  * **metadata-view:** default sortBy ([#4232](https://github.com/box/box-ui-elements/issues/4232)) ([`1a86aa5`](https://github.com/box/box-ui-elements/commit/1a86aa587b47e149d4e9430a3720492d4bffb2a4))
  * **metadata-view:** Implement metadata sidepanel ([#4230](https://github.com/box/box-ui-elements/issues/4230)) ([`4f89946`](https://github.com/box/box-ui-elements/commit/4f8994652f45b34abd22d5347ecfd7642ce47fa2))
  * **metadata-view:** Multi value display and onSave in metadata sidepanel ([#4245](https://github.com/box/box-ui-elements/issues/4245)) ([`7ddea1e`](https://github.com/box/box-ui-elements/commit/7ddea1e9ae6c0f5686fb8efa501619da61f41818))
  * **metadata-view:** pass-thru onSortChange ([#4248](https://github.com/box/box-ui-elements/issues/4248)) ([`1a8a59f`](https://github.com/box/box-ui-elements/commit/1a8a59f66740eeb0313e4a64d2793f1bd5ea22c8))
  * **router:** withRouterIfEnabled ([#4221](https://github.com/box/box-ui-elements/issues/4221)) ([`f969170`](https://github.com/box/box-ui-elements/commit/f96917063feedb5ee681935b1551d8fa7555e74e))
  * **timestamped-comments:** enabling time stamped video comments ([#4228](https://github.com/box/box-ui-elements/issues/4228)) ([`31b580d`](https://github.com/box/box-ui-elements/commit/31b580d3dd7411f25b0f6841ab56eb91fb425fc1)), closes [#4226](https://github.com/box/box-ui-elements/issues/4226) [#4230](https://github.com/box/box-ui-elements/issues/4230)

  ### BREAKING CHANGES

  * **box-ai:** isResetChatEnabled prop removed
</Update>

<Update label="2025-09-05">
  ## Box TypeScript SDK Generated v1.19.0 released

  ### Bug Fixes

  * Remove private access modifiers (box/box-codegen[#815](https://github.com/box/box-typescript-sdk-gen/issues/815)) ([#747](https://github.com/box/box-typescript-sdk-gen/issues/747)) ([`1693ddc`](https://github.com/box/box-typescript-sdk-gen/commit/1693ddc114b1c0452b2eddd6b4837a308155678a))

  ### New Features and Enhancements

  * Add missing webhook events (box/box-openapi[#554](https://github.com/box/box-typescript-sdk-gen/issues/554)) ([#753](https://github.com/box/box-typescript-sdk-gen/issues/753)) ([`2b77c98`](https://github.com/box/box-typescript-sdk-gen/commit/2b77c982d549ef8ad84d8c6b69f9afb37e53197e))
</Update>

<Update label="2025-09-05">
  ## Box Swift SDK Generated 0.6.3 released

  ### New Features and Enhancements

  * Add missing webhook events (box/box-openapi[#554](https://github.com/box/box-swift-sdk-gen/issues/554)) ([#581](https://github.com/box/box-swift-sdk-gen/issues/581)) ([`966d171`](https://github.com/box/box-swift-sdk-gen/commit/966d171baa3f6fa1139732b05081000e44b0e08a))
</Update>

<Update label="2025-09-05">
  ## Box Python SDK Generated v1.17.0 released

  ### New Features and Enhancements

  * Add missing webhook events (box/box-openapi[#554](https://github.com/box/box-python-sdk-gen/issues/554)) ([#708](https://github.com/box/box-python-sdk-gen/issues/708)) ([`3d25542`](https://github.com/box/box-python-sdk-gen/commit/3d2554239b0bede7a3158cf88913592643c3e22b))
  * Support event with long polling (box/box-codegen[#757](https://github.com/box/box-python-sdk-gen/issues/757)) ([#673](https://github.com/box/box-python-sdk-gen/issues/673)) ([`481fbeb`](https://github.com/box/box-python-sdk-gen/commit/481fbeb1412ecc137c0090dd4b37fe9ad75db6b0))
</Update>

<Update label="2025-09-05">
  ## Box Dotnet SDK Generated v1.12.0 released

  ### New Features and Enhancements

  * Add missing webhook events (box/box-openapi[#554](https://github.com/box/box-dotnet-sdk-gen/issues/554)) ([#600](https://github.com/box/box-dotnet-sdk-gen/issues/600)) ([`46c6d33`](https://github.com/box/box-dotnet-sdk-gen/commit/46c6d33238b7a97352a434333e18054d8adccd03))
</Update>

<Update label="2025-08-26">
  ## Box TypeScript SDK Generated v1.18.1 released

  ### Bug Fixes

  * correct import and export handling (box/box-codegen[#801](https://github.com/box/box-typescript-sdk-gen/issues/801)) ([#738](https://github.com/box/box-typescript-sdk-gen/issues/738)) ([`cea513f`](https://github.com/box/box-typescript-sdk-gen/commit/cea513fcf3ed79b930e7067f06282c5bb08d8bd6))
</Update>

<Update label="2025-08-26">
  ## Box TypeScript SDK Generated v1.18.0 released

  ### Bug Fixes

  * bump form-data to 4.0.4 and types/node-fetch to 2.6.13 (box/box-codegen[#808](https://github.com/box/box-typescript-sdk-gen/issues/808)) ([#735](https://github.com/box/box-typescript-sdk-gen/issues/735)) ([`7330b95`](https://github.com/box/box-typescript-sdk-gen/commit/7330b95dc18baa56a24a06657f2cb3cc3f4c7c46))
  * Fix serialization for `MetadataFilterValue` (box/box-codegen[#800](https://github.com/box/box-typescript-sdk-gen/issues/800)) ([#727](https://github.com/box/box-typescript-sdk-gen/issues/727)) ([`d046405`](https://github.com/box/box-typescript-sdk-gen/commit/d046405e644d5533e07ac42411c176527efdd1fb))

  ### New Features and Enhancements

  * Support event with long polling in Python and TS (box/box-codegen[#757](https://github.com/box/box-typescript-sdk-gen/issues/757)) ([#712](https://github.com/box/box-typescript-sdk-gen/issues/712)) ([`6f25fda`](https://github.com/box/box-typescript-sdk-gen/commit/6f25fdaf48b3538b3a7ba370d677454f6f0d2631))
</Update>

<Update label="2025-08-11">
  ## Bulk delete external users

  You can now [bulk delete](/guides/users/bulk-delete-external-users) up to 100 external user accounts through the public API.

  This job runs in the background, and sends a completion report when it's finished.

  The report contains details identifying which user deletions succeeded and which failed.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/) for any help needed.
</Update>

<Update label="2025-08-13">
  ## Box Swift SDK Generated 0.6.2 released

  ### Bug Fixes

  * Fix downscope token to use `retrieveToken` method for token retrieval (box/box-codegen[#731](https://github.com/box/box-swift-sdk-gen/issues/731)) ([#459](https://github.com/box/box-swift-sdk-gen/issues/459)) ([`8992b32`](https://github.com/box/box-swift-sdk-gen/commit/8992b32e9dd058fc77b4d68418da81b162aea315))
  * Fix parsing `Date` into query parameters (box/box-codegen[#729](https://github.com/box/box-swift-sdk-gen/issues/729)) ([#449](https://github.com/box/box-swift-sdk-gen/issues/449)) ([`1a95d0c`](https://github.com/box/box-swift-sdk-gen/commit/1a95d0c80e0bd29dc1b467e7e98e6f5e6196ddfb))
  * Specify events `next_stream_position` property type as `int64` (box/box-openapi[#535](https://github.com/box/box-swift-sdk-gen/issues/535)) ([#502](https://github.com/box/box-swift-sdk-gen/issues/502)) ([`795fe1c`](https://github.com/box/box-swift-sdk-gen/commit/795fe1c7f0aa6074145b675fce4dd8e1432b0a64))

  ### New Features and Enhancements

  * Add `downloadZip` method (box/box-codegen[#765](https://github.com/box/box-swift-sdk-gen/issues/765)) ([#505](https://github.com/box/box-swift-sdk-gen/issues/505)) ([`c03589d`](https://github.com/box/box-swift-sdk-gen/commit/c03589d6add3ee6d548f10b5380031cd38284e42))
  * Add `rawData` property (box/box-codegen[#724](https://github.com/box/box-swift-sdk-gen/issues/724)) ([#445](https://github.com/box/box-swift-sdk-gen/issues/445)) ([`77405ad`](https://github.com/box/box-swift-sdk-gen/commit/77405adc986adb8a1ce3bcff051ea8c481dbfd9d))
  * add AI agents warnings; allow for more types of metadata value (box/box-openapi[#520](https://github.com/box/box-swift-sdk-gen/issues/520)) ([#435](https://github.com/box/box-swift-sdk-gen/issues/435)) ([`af1dc12`](https://github.com/box/box-swift-sdk-gen/commit/af1dc12763f9a84691573fd3ba8307925fc017d6))
  * add AI spreadsheet processor (box/box-openapi[#533](https://github.com/box/box-swift-sdk-gen/issues/533)) ([#484](https://github.com/box/box-swift-sdk-gen/issues/484)) ([`14726d1`](https://github.com/box/box-swift-sdk-gen/commit/14726d1952f5ddb2414f723a0b18fa5226269a64))
  * Add Archive Public API (box/box-openapi[#540](https://github.com/box/box-swift-sdk-gen/issues/540)) ([#509](https://github.com/box/box-swift-sdk-gen/issues/509)) ([`8266386`](https://github.com/box/box-swift-sdk-gen/commit/82663868c61a31f43b229c6f24e29737913662a0))
  * Add CI for swift (box/box-codegen[#755](https://github.com/box/box-swift-sdk-gen/issues/755)) ([#494](https://github.com/box/box-swift-sdk-gen/issues/494)) ([`76a3337`](https://github.com/box/box-swift-sdk-gen/commit/76a3337bed9bfc4629ec7dcb9af86bec4aa710f3))
  * add hubs API beta endpoints (box/box-openapi[#531](https://github.com/box/box-swift-sdk-gen/issues/531)) ([#476](https://github.com/box/box-swift-sdk-gen/issues/476)) ([`a05aa5f`](https://github.com/box/box-swift-sdk-gen/commit/a05aa5fe2aaade1d7bdd7acb90c82fcb3a3bf262))
  * Add new Hubs APIs and Hubs items API (box/box-openapi[#538](https://github.com/box/box-swift-sdk-gen/issues/538)) ([#503](https://github.com/box/box-swift-sdk-gen/issues/503)) ([`9058c45`](https://github.com/box/box-swift-sdk-gen/commit/9058c45c0bcd3e7f294a1bedac151637001aec63))
  * Add new schema for `Metadata Error` (box/box-openapi[#539](https://github.com/box/box-swift-sdk-gen/issues/539)) ([#504](https://github.com/box/box-swift-sdk-gen/issues/504)) ([`2e9ecf9`](https://github.com/box/box-swift-sdk-gen/commit/2e9ecf9477854656958b715674b8aa0413508d31))
  * Add security settings properties on sign template schema (box/box-openapi[#518](https://github.com/box/box-swift-sdk-gen/issues/518)) ([#426](https://github.com/box/box-swift-sdk-gen/issues/426)) ([`a741a73`](https://github.com/box/box-swift-sdk-gen/commit/a741a7305e2b2d174bc325e35ea9b77548a38095))
  * add Shield Lists APIs (box/box-openapi[#528](https://github.com/box/box-swift-sdk-gen/issues/528)) ([#462](https://github.com/box/box-swift-sdk-gen/issues/462)) ([`b5993b0`](https://github.com/box/box-swift-sdk-gen/commit/b5993b096b4fceb77301f76eba1c17225b2844d6))
  * Add support for `additionalProperties` with Any value (box/box-codegen[#711](https://github.com/box/box-swift-sdk-gen/issues/711)) ([#427](https://github.com/box/box-swift-sdk-gen/issues/427)) ([`7fbf706`](https://github.com/box/box-swift-sdk-gen/commit/7fbf7069eff66afddc328066f8aeb7321b249eea))
  * Add support for `nullable` fields (box/box-codegen[#700](https://github.com/box/box-swift-sdk-gen/issues/700)) ([#420](https://github.com/box/box-swift-sdk-gen/issues/420)) ([`5d0ff41`](https://github.com/box/box-swift-sdk-gen/commit/5d0ff414b325db92db44c580cebb5636ab33553f))
  * add support of IBM models to AI API (box/box-openapi[#522](https://github.com/box/box-swift-sdk-gen/issues/522)) ([#436](https://github.com/box/box-swift-sdk-gen/issues/436)) ([`0717222`](https://github.com/box/box-swift-sdk-gen/commit/071722246402e0ec2439ae1e5e3d26bca45a049f))
  * Expose `makeRequest` method in `BoxClient` (box/box-codegen[#687](https://github.com/box/box-swift-sdk-gen/issues/687)) ([#408](https://github.com/box/box-swift-sdk-gen/issues/408)) ([`7ba7d09`](https://github.com/box/box-swift-sdk-gen/commit/7ba7d091b0c832276daa571fad2a7db75469676d))
  * Improve AI integration test (box/box-codegen[#758](https://github.com/box/box-swift-sdk-gen/issues/758)) ([#499](https://github.com/box/box-swift-sdk-gen/issues/499)) ([`3c7e717`](https://github.com/box/box-swift-sdk-gen/commit/3c7e717c6ca076caf1a963b3f60d3bd88f8c4bff))
  * Sanitize response body when throwing `BoxAPIError` (box/box-codegen[#760](https://github.com/box/box-swift-sdk-gen/issues/760)) ([#498](https://github.com/box/box-swift-sdk-gen/issues/498)) ([`2afc793`](https://github.com/box/box-swift-sdk-gen/commit/2afc7936dac87dee22adff3e22def92913f5854c))
  * Support `getDownloadUrl` in Swift (box/box-codegen[#751](https://github.com/box/box-swift-sdk-gen/issues/751)) ([#491](https://github.com/box/box-swift-sdk-gen/issues/491)) ([`5916ede`](https://github.com/box/box-swift-sdk-gen/commit/5916ede7454a1926de195e77b9a158c2af0fae2b))
  * Support new tools in AI Studio (box/box-openapi[#534](https://github.com/box/box-swift-sdk-gen/issues/534)) ([#485](https://github.com/box/box-swift-sdk-gen/issues/485)) ([`e793d7b`](https://github.com/box/box-swift-sdk-gen/commit/e793d7b3a03e8d58ce6adb63a894a0330ae154d1))
  * Support sensitive data sanitization in errors (box/box-codegen[#695](https://github.com/box/box-swift-sdk-gen/issues/695)) ([#415](https://github.com/box/box-swift-sdk-gen/issues/415)) ([`330ca9a`](https://github.com/box/box-swift-sdk-gen/commit/330ca9ad17cbc79c93ffb114fd56c09a41f92694))
  * Update legal holds and AI models (box/box-openapi[#526](https://github.com/box/box-swift-sdk-gen/issues/526)) ([#460](https://github.com/box/box-swift-sdk-gen/issues/460)) ([`caa848a`](https://github.com/box/box-swift-sdk-gen/commit/caa848ac977c7fedeacbe018339d27b9d948bb1e))
</Update>

<Update label="2025-08-12">
  ## Box UI Elements v23.4.0 released

  ### [23.4.0](https://github.com/box/box-ui-elements/compare/v23.3.0...v23.4.0) (2025-08-12)

  ### Bug Fixes

  * **`ai-sidebar`:** Add callback for selected agent ([#4115](https://github.com/box/box-ui-elements/issues/4115)) ([`8bdbf3e`](https://github.com/box/box-ui-elements/commit/8bdbf3eee149e3a6dbc3431792509f3005371561))
  * **`blueprint`:** Bump blueprint ([#4205](https://github.com/box/box-ui-elements/issues/4205)) ([`5e7f4b2`](https://github.com/box/box-ui-elements/commit/5e7f4b21f47d6be7416e06a1554bc58c0b150395))
  * **`breadcrumb`:** Add missing key property ([#4170](https://github.com/box/box-ui-elements/issues/4170)) ([`c10b059`](https://github.com/box/box-ui-elements/commit/c10b05951c6efa185b0a04517d4cf91349f8a545))
  * **`content-preview`:** prevent item icon shrinking on small screens ([#4111](https://github.com/box/box-ui-elements/issues/4111)) ([`e5004f7`](https://github.com/box/box-ui-elements/commit/e5004f785d38fe6681dcd70b11842e413fef55bb))
  * **`gh-pages`:** deploy storybook from docs folder ([#4100](https://github.com/box/box-ui-elements/issues/4100)) ([`dd34522`](https://github.com/box/box-ui-elements/commit/dd345227b8cb864cb42eabdbefd4208cfdd690c2))
  * **`header-flyout`:** remove animation on \< medium screen size ([#4163](https://github.com/box/box-ui-elements/issues/4163)) ([`cf3123e`](https://github.com/box/box-ui-elements/commit/cf3123e802fdd64d794087d7dd7551a3b5b28c32))
  * **`i18n`:** update translations ([#4105](https://github.com/box/box-ui-elements/issues/4105)) ([`df61d95`](https://github.com/box/box-ui-elements/commit/df61d95591f74c44351e083fd139aed0bcf5e92a))
  * **`i18n`:** update translations ([#4108](https://github.com/box/box-ui-elements/issues/4108)) ([`e702f97`](https://github.com/box/box-ui-elements/commit/e702f9773ae876c9355ebb9a02221e7f935f729e))
  * **`i18n`:** update translations ([#4113](https://github.com/box/box-ui-elements/issues/4113)) ([`196beee`](https://github.com/box/box-ui-elements/commit/196beee85ebdcea2cfbc92ef70c1332d9b8ea25c))
  * **`i18n`:** update translations ([#4119](https://github.com/box/box-ui-elements/issues/4119)) ([`113915b`](https://github.com/box/box-ui-elements/commit/113915b34d9f4895bae0b3085544bcd34dd7794c))
  * **`i18n`:** update translations ([#4121](https://github.com/box/box-ui-elements/issues/4121)) ([`02cb22e`](https://github.com/box/box-ui-elements/commit/02cb22e1727821da51e366bdd8e70ab56e6c8a45))
  * **`i18n`:** update translations ([#4130](https://github.com/box/box-ui-elements/issues/4130)) ([`ff8f322`](https://github.com/box/box-ui-elements/commit/ff8f3223c72e7f6aaea5d571fd5cf3bcd71b5857))
  * **`i18n`:** update translations ([#4139](https://github.com/box/box-ui-elements/issues/4139)) ([`47b7690`](https://github.com/box/box-ui-elements/commit/47b76902799c69d1d5cd54965fb37d5781451423))
  * **`i18n`:** update translations ([#4185](https://github.com/box/box-ui-elements/issues/4185)) ([`fef4134`](https://github.com/box/box-ui-elements/commit/fef4134a26b59ee7bbb3e9da13ae488a98e6fa52))
  * **`i18n`:** update translations ([#4196](https://github.com/box/box-ui-elements/issues/4196)) ([`dd19958`](https://github.com/box/box-ui-elements/commit/dd19958289d113f4272559edbd1307e4d81e3137))
  * **`i18n`:** update translations ([#4203](https://github.com/box/box-ui-elements/issues/4203)) ([`bd31196`](https://github.com/box/box-ui-elements/commit/bd31196e11bcae1b2efa732255697751c25644a4))
  * **`i18n`:** update translations ([#4208](https://github.com/box/box-ui-elements/issues/4208)) ([`95b3cc6`](https://github.com/box/box-ui-elements/commit/95b3cc6b48ea7850e348936d040e4fda4f64e4df))
  * **`i18n`:** update translations ([#4211](https://github.com/box/box-ui-elements/issues/4211)) ([`bee412f`](https://github.com/box/box-ui-elements/commit/bee412f1bad7e647b814d7601ddd04fe2d2421d1))
  * **`i18n`:** update translations ([#4216](https://github.com/box/box-ui-elements/issues/4216)) ([`da932f1`](https://github.com/box/box-ui-elements/commit/da932f18801e936cffe7951a95639af2e52e05d8))
  * **`i18n`:** update translations ([#4219](https://github.com/box/box-ui-elements/issues/4219)) ([`d8a8fcb`](https://github.com/box/box-ui-elements/commit/d8a8fcbc6ad3cbf11fec25949374bb73dce01d56))
  * **`metadata-editor`:** package bump for bug fixes ([#4171](https://github.com/box/box-ui-elements/issues/4171)) ([`51dd7ca`](https://github.com/box/box-ui-elements/commit/51dd7caf8b273e0c0adba948f58e4b69be3a708e))
  * **`metadata-instance-fields`:** add minimal taxonomy support in `metada-instance-field`s ([#4133](https://github.com/box/box-ui-elements/issues/4133)) ([`0dff276`](https://github.com/box/box-ui-elements/commit/0dff276da6b497220f762fd917c421db4d5cf343))
  * resolve CVE-2025-7783 `form-data` vulnerability ([#4213](https://github.com/box/box-ui-elements/issues/4213)) ([`96252db`](https://github.com/box/box-ui-elements/commit/96252db2ca2cad6b9b07787621e027e0a8ac7c84))
  * resolve incorrect type import ([#4132](https://github.com/box/box-ui-elements/issues/4132)) ([`8b5eec6`](https://github.com/box/box-ui-elements/commit/8b5eec6b4eda2a8291a8fda142b33ba6ba4498c0))
  * Throttle create folder to avoid rapid clicks ([#4193](https://github.com/box/box-ui-elements/issues/4193)) ([`67ec941`](https://github.com/box/box-ui-elements/commit/67ec94170a855e6ec62064f51e0b2e5d6d5aa729))
  * **`uploads`:** handle rate limit errors with retries ([#4134](https://github.com/box/box-ui-elements/issues/4134)) ([`eb3e3da`](https://github.com/box/box-ui-elements/commit/eb3e3da1c5b145f07994c5bb1eec38567de78187))

  ### Features

  * **`boxai-sidebar`:** Add logic to render remote sidebar from prop  ([#4106](https://github.com/box/box-ui-elements/issues/4106)) ([`7f8802a`](https://github.com/box/box-ui-elements/commit/7f8802a4997322503e5f31bb86aaeb252b99ef70))
  * **`cascadepolicy`:** disable inputs if cascade policy exists ([#4175](https://github.com/box/box-ui-elements/issues/4175)) ([`b6d778c`](https://github.com/box/box-ui-elements/commit/b6d778c6d3b0778a3e2f786b4b53d6d7ce045076))
  * **`header-flyout`:** add opening animation ([#4159](https://github.com/box/box-ui-elements/issues/4159)) ([`3b417ba`](https://github.com/box/box-ui-elements/commit/3b417ba0a71d10026ba1c1857a974487eaf27f86))
  * **`header-flyout`:** optionally allow header actions ([#4164](https://github.com/box/box-ui-elements/issues/4164)) ([`8f3ad6e`](https://github.com/box/box-ui-elements/commit/8f3ad6e9f39d5fd8a5dcc54691bca6360af74dc6))
  * **`mergify`:** update rule to require conversation resolution ([#4142](https://github.com/box/box-ui-elements/issues/4142)) ([`ef3291e`](https://github.com/box/box-ui-elements/commit/ef3291ed0f65122bfdaf9dd0fb51cfb6fc8acd64))
  * `metadata-edito`r and `blueprint-web-assets` package bump ([#4137](https://github.com/box/box-ui-elements/issues/4137)) ([`070ff74`](https://github.com/box/box-ui-elements/commit/070ff749e085283ad97487a8a7daf6b44807fa94))
  * **`metadata-editor`:** expose advanced metadata extract agent props ([#4128](https://github.com/box/box-ui-elements/issues/4128)) ([`f59b0aa`](https://github.com/box/box-ui-elements/commit/f59b0aa998fea1d54e2bc14a841dbfd3adc8be65))
  * **`metadata-editor`:** expose custom agent in `extractStructured` payload ([#4135](https://github.com/box/box-ui-elements/issues/4135)) ([`076e719`](https://github.com/box/box-ui-elements/commit/076e719857d17bd52de52f904bf5ee2763bc0ef7)), closes [#4102](https://github.com/box/box-ui-elements/issues/4102)
  * **`metadata-editor`:** Metadata API adjustments ([#4192](https://github.com/box/box-ui-elements/issues/4192)) ([`6112967`](https://github.com/box/box-ui-elements/commit/6112967007196e2c91ca54ed7a7ce3afc5ab994b))
  * **`metadata-editor`:** package bump for new icons ([#4195](https://github.com/box/box-ui-elements/issues/4195)) ([`1506020`](https://github.com/box/box-ui-elements/commit/150602092e957693b7fbd227e92adac8110ac327))
  * **`metadata-instance-editor`:** add enhanced ai extract support ([#4197](https://github.com/box/box-ui-elements/issues/4197)) ([`540026a`](https://github.com/box/box-ui-elements/commit/540026a28bb805dd06d4b3f22c868ed0edd3f56e))
  * **`metadata-instance-editor`:** allow hydration of enhanced ai extract ([#4217](https://github.com/box/box-ui-elements/issues/4217)) ([`5a93a16`](https://github.com/box/box-ui-elements/commit/5a93a16c29187618429b8f0e4a53b8140a11b5f1))
  * **`metadata-view`:** Add `MetadataView` V2 ([#4191](https://github.com/box/box-ui-elements/issues/4191)) ([`c0ab1e7`](https://github.com/box/box-ui-elements/commit/c0ab1e7670e5f7c7ae8ff7572709ac19c9788a46))
  * **`metadata-view`:** Add Subheader for Metadata View v2 ([#4202](https://github.com/box/box-ui-elements/issues/4202)) ([`ab12626`](https://github.com/box/box-ui-elements/commit/ab1262690196a3ebb220250b1ad0243cd18932ce))
  * **`metadata-view`:** Added Metadata V2 button ([#4174](https://github.com/box/box-ui-elements/issues/4174)) ([`d8ec9c7`](https://github.com/box/box-ui-elements/commit/d8ec9c75d6c7d2fa502d7d44aad2e7cd0ad1721e))
  * **`metadata-view`:** custom actions ([#4215](https://github.com/box/box-ui-elements/issues/4215)) ([`88a5187`](https://github.com/box/box-ui-elements/commit/88a518723c44bcf6a6d0762c1ff8e16ebcdb5fd6))
  * **`metadataeditor`:** enable ai folder extraction through API ([#4102](https://github.com/box/box-ui-elements/issues/4102)) ([`6ebec78`](https://github.com/box/box-ui-elements/commit/6ebec78fff6ece2f1ea3c4bc20ef7409e33f27fd))
  * **`metadataeditor`:** remove ai pricing notice ([#4107](https://github.com/box/box-ui-elements/issues/4107)) ([`4bd24bc`](https://github.com/box/box-ui-elements/commit/4bd24bcf59489f7aaac381d9c66b7e1b9d2a64df))
  * **`notification-redesign`:** Add logic for use of BP icons ([#4103](https://github.com/box/box-ui-elements/issues/4103)) ([`7907136`](https://github.com/box/box-ui-elements/commit/79071362aea99c02993ed89cd9bee34bbe196b25))
  * **`router`:** added router-less logic to `VersionsSidebarContainer` ([#4209](https://github.com/box/box-ui-elements/issues/4209)) ([`0f46866`](https://github.com/box/box-ui-elements/commit/0f46866a9490bd8c9872f9e76147ed72d9d7a287))
  * **`router`:** Merging `NavButton` functionality into `SidebarNavButton` ([#4150](https://github.com/box/box-ui-elements/issues/4150)) ([`814035d`](https://github.com/box/box-ui-elements/commit/814035d73280b7d1e0e9a068876ca3c0cf471b94))
  * **`router`:** optional router in `ActivitySidebar` ([#4199](https://github.com/box/box-ui-elements/issues/4199)) ([`435c75a`](https://github.com/box/box-ui-elements/commit/435c75a9bce168c8206597da804b7ce55c97467d))
  * **`router`:** optional router in `AddTaskButton` ([#4176](https://github.com/box/box-ui-elements/issues/4176)) ([`90537b4`](https://github.com/box/box-ui-elements/commit/90537b471fce6643dd5eaecf1e5b0a1e3f196012))
  * **`router`:** optional router in `NavRouter` and `withNavRouter` ([#4161](https://github.com/box/box-ui-elements/issues/4161)) ([`7f9cad4`](https://github.com/box/box-ui-elements/commit/7f9cad4b85f96d8d65f11c30ae3a45f2a3c96e40))
  * **`router`:** optional router in `SidebarNav`, `SidebarNavTablist` ([#4177](https://github.com/box/box-ui-elements/issues/4177)) ([`d14e06e`](https://github.com/box/box-ui-elements/commit/d14e06eb47083160dcf04055d3f418c4457d1255))
  * **`router`:** optional router in `SidebarNavButton` ([#4156](https://github.com/box/box-ui-elements/issues/4156)) ([`dc8af3b`](https://github.com/box/box-ui-elements/commit/dc8af3b1dda45b1617aeac5a2d04af07af7e1e21))
  * **`router`:** optional router in `SidebarNavigation` ([#4194](https://github.com/box/box-ui-elements/issues/4194)) ([`e25e0e1`](https://github.com/box/box-ui-elements/commit/e25e0e1174efd262f93e70619ff5f9a79d168fd8))
  * **`router`:** optional router in `SidebarToggle` ([#4160](https://github.com/box/box-ui-elements/issues/4160)) ([`12c9a3a`](https://github.com/box/box-ui-elements/commit/12c9a3a840545048f53ebae7b278208981ed1a55))
  * **`router`:** optional router in `StaticVersionSidebar` and `VersionsSid…` ([#4152](https://github.com/box/box-ui-elements/issues/4152)) ([`a456f3d`](https://github.com/box/box-ui-elements/commit/a456f3d677c3ad15e5ec2e052dcedf93d0d612f3))
  * **`router`:** optional router in `VersionsList` ([#4144](https://github.com/box/box-ui-elements/issues/4144)) ([`15c5d8d`](https://github.com/box/box-ui-elements/commit/15c5d8dfed2b2cc777344d0e0ef10da8c3525434))
  * **`router`:** optional router in `withAnnotatorContext` and `withAnnotations` ([#4136](https://github.com/box/box-ui-elements/issues/4136)) ([`d08545e`](https://github.com/box/box-ui-elements/commit/d08545ef0650ad7082040d74acddb365bc8122f4))
  * **`router`:** optional router in `withRouterAndRef` hoc ([#4162](https://github.com/box/box-ui-elements/issues/4162)) ([`32b08b9`](https://github.com/box/box-ui-elements/commit/32b08b929acbd906b2a348b8939234c980f1b642))
  * **`router`:** optional router in `withSidebarAnnotations` ([#4206](https://github.com/box/box-ui-elements/issues/4206)) ([`782877d`](https://github.com/box/box-ui-elements/commit/782877d2dcfa6d928da884055f1cc4bb17745d18))
  * **`router`:** Removed router functionality from `BackButton` component ([#4141](https://github.com/box/box-ui-elements/issues/4141)) ([`f01364c`](https://github.com/box/box-ui-elements/commit/f01364c73117a4d0638b28d4e3c6e832b1c27a62))
  * upgrade blueprint packages ([#4123](https://github.com/box/box-ui-elements/issues/4123)) ([`c166d7d`](https://github.com/box/box-ui-elements/commit/c166d7d49373168daed0eab315f2e90d4b0532a9))
  * upgrade react-virtualized for react 19 support ([#4157](https://github.com/box/box-ui-elements/issues/4157)) ([`269f585`](https://github.com/box/box-ui-elements/commit/269f5854c5c15a48c971207cf00bc2f1a98ccb97))
  * **`uploads`:** add option to error on name conflicts ([#4117](https://github.com/box/box-ui-elements/issues/4117)) ([`463839e`](https://github.com/box/box-ui-elements/commit/463839ee00c901cd9752106ca1a44e7a3906dc0b))
</Update>

<Update label="2025-08-07">
  ## Box TypeScript SDK Generated v1.17.1 released

  ### Bug Fixes

  * Fix exports syntax when importing from `lib` ([#700](https://github.com/box/box-typescript-sdk-gen/issues/700)) ([`782a287`](https://github.com/box/box-typescript-sdk-gen/commit/782a287efd3481fc056effcf83886f05bc9adbf9))
</Update>

<Update label="2025-08-07">
  ## Box CLI v4.3.0 released

  ### New Features and Enhancements

  * add agent support to `ai:ask` command ([#589](https://github.com/box/boxcli/issues/589)) ([`095f411`](https://github.com/box/boxcli/commit/095f4110274f67c5b1024de49a256b5bbe35cf18))

  ### Bug Fixes

  * Fix support metadata query array ([#583](https://github.com/box/boxcli/issues/583)) ([`112db16`](https://github.com/box/boxcli/commit/112db160230e5bb75f84e44cb86a8372341dd8ad))
  * Remove `description` flag from folders:create command ([#587](https://github.com/box/boxcli/issues/587)) ([`adca76b`](https://github.com/box/boxcli/commit/adca76b5fb03f62daf2104500b87f8a962382a35))
</Update>

<Update label="2025-08-05">
  ## Box TypeScript SDK Generated v1.17.0 released

  ### Bug Fixes

  * Bump `cypress` to resolve `CVE-2025-7783` in `form-data` (box/box-codegen[#769](https://github.com/box/box-typescript-sdk-gen/issues/769)) ([#677](https://github.com/box/box-typescript-sdk-gen/issues/677)) ([`077413e`](https://github.com/box/box-typescript-sdk-gen/commit/077413ec525fad4d8ebc4c7209fce20046731295))

  ### New Features and Enhancements

  * Add AI spreadsheet processor (box/box-openapi[#533](https://github.com/box/box-typescript-sdk-gen/issues/533)) ([#649](https://github.com/box/box-typescript-sdk-gen/issues/649)) ([`254fb54`](https://github.com/box/box-typescript-sdk-gen/commit/254fb54d928ec3a76304674f341be1c67d78a143))
  * Add Archive Public API (box/box-openapi[#540](https://github.com/box/box-typescript-sdk-gen/issues/540)) ([#674](https://github.com/box/box-typescript-sdk-gen/issues/674)) ([`1cbb124`](https://github.com/box/box-typescript-sdk-gen/commit/1cbb12485a417b813df8b6918cf3721ae781a286))
  * Add new Hubs APIs and Hubs items API (box/box-openapi[#538](https://github.com/box/box-typescript-sdk-gen/issues/538)) ([#666](https://github.com/box/box-typescript-sdk-gen/issues/666)) ([`25c9596`](https://github.com/box/box-typescript-sdk-gen/commit/25c9596bc71fe88e0a2b6d5e01c65fa682c2fd38))
  * Add new schema for `Metadata Error` (box/box-openapi[#539](https://github.com/box/box-typescript-sdk-gen/issues/539)) ([#667](https://github.com/box/box-typescript-sdk-gen/issues/667)) ([`9af46ab`](https://github.com/box/box-typescript-sdk-gen/commit/9af46abe837ee0d812bcc15f1edf0d5a6530bfe0))
  * Allow injecting private key decryption mechanism for JWT (box/box-codegen[#754](https://github.com/box/box-typescript-sdk-gen/issues/754)) ([#656](https://github.com/box/box-typescript-sdk-gen/issues/656)) ([`cb0c35d`](https://github.com/box/box-typescript-sdk-gen/commit/cb0c35df4a5b3f9b8c611006dd33d480949a0d36))
  * Improve webhook validation checks (box/box-codegen[#745](https://github.com/box/box-typescript-sdk-gen/issues/745)) ([#647](https://github.com/box/box-typescript-sdk-gen/issues/647)) ([`98b3b92`](https://github.com/box/box-typescript-sdk-gen/commit/98b3b9293ff3f0e5922d0772d87504770bb9303c))
  * Retry request on network exception (box/box-codegen[#776](https://github.com/box/box-typescript-sdk-gen/issues/776)) ([#684](https://github.com/box/box-typescript-sdk-gen/issues/684)) ([`c0c4dba`](https://github.com/box/box-typescript-sdk-gen/commit/c0c4dbac40970d34da4c9e52fc43f029ae2f91a6))
  * Support ESM build and tree-shaking (box/box-codegen[#762](https://github.com/box/box-typescript-sdk-gen/issues/762)) ([#663](https://github.com/box/box-typescript-sdk-gen/issues/663)) ([`8ca3302`](https://github.com/box/box-typescript-sdk-gen/commit/8ca33023d904edd596819c7c6df42022006274ed))
  * Support Hubs beta endpoints (box/box-openapi[#531](https://github.com/box/box-typescript-sdk-gen/issues/531)) ([#641](https://github.com/box/box-typescript-sdk-gen/issues/641)) ([`d8c7bb6`](https://github.com/box/box-typescript-sdk-gen/commit/d8c7bb66736a3c4679b116916c61e2ead824a305))
  * Support new tools in AI Studio (box/box-openapi[#534](https://github.com/box/box-typescript-sdk-gen/issues/534))  ([#652](https://github.com/box/box-typescript-sdk-gen/issues/652)) ([`db2501b`](https://github.com/box/box-typescript-sdk-gen/commit/db2501bb13fc6ecebbb4c535b4a19c9be2cf64c2))
</Update>

<Update label="2025-08-05">
  ## Box Python SDK Generated v1.16.0 released

  ### Bug Fixes

  * Specify events `next_stream_position` property type as `int` (box/box-openapi[#535](https://github.com/box/box-python-sdk-gen/issues/535)) ([#644](https://github.com/box/box-python-sdk-gen/issues/644)) ([`64069db`](https://github.com/box/box-python-sdk-gen/commit/64069db8da33988c173380defd6be065daa02496))

  ### New Features and Enhancements

  * Add AI spreadsheet processor (box/box-openapi[#533](https://github.com/box/box-python-sdk-gen/issues/533)) ([#630](https://github.com/box/box-python-sdk-gen/issues/630)) ([`6635757`](https://github.com/box/box-python-sdk-gen/commit/66357578218913240bc923cb0dc771157ec95f54))
  * Add Archive Public API (box/box-openapi[#540](https://github.com/box/box-python-sdk-gen/issues/540)) ([#651](https://github.com/box/box-python-sdk-gen/issues/651)) ([`c36d1db`](https://github.com/box/box-python-sdk-gen/commit/c36d1dbff42c89876c037983c792c5c7282459cc))
  * Add new Hubs APIs and Hubs items API (box/box-openapi[#538](https://github.com/box/box-python-sdk-gen/issues/538)) ([#645](https://github.com/box/box-python-sdk-gen/issues/645)) ([`1daa3e8`](https://github.com/box/box-python-sdk-gen/commit/1daa3e8814403c78ed2a1d64187b8e4c379028fe))
  * Add new property for network exception retry strategy (box/box-codegen[#763](https://github.com/box/box-python-sdk-gen/issues/763)) ([#650](https://github.com/box/box-python-sdk-gen/issues/650)) ([`13f9593`](https://github.com/box/box-python-sdk-gen/commit/13f9593dbc4a45d094ee5709d602188ef341a1a5))
  * Add new schema for `Metadata Error` (box/box-openapi[#539](https://github.com/box/box-python-sdk-gen/issues/539)) ([#646](https://github.com/box/box-python-sdk-gen/issues/646)) ([`49d7f34`](https://github.com/box/box-python-sdk-gen/commit/49d7f349e1be4e23939ef10db1edfc6042b98175))
  * Allow injecting private key decryption mechanism for JWT (box/box-codegen[#754](https://github.com/box/box-python-sdk-gen/issues/754)) ([#636](https://github.com/box/box-python-sdk-gen/issues/636)) ([`4ea0af5`](https://github.com/box/box-python-sdk-gen/commit/4ea0af5f8f5b5516a7c23d7912c34690c017db29))
  * Improve webhook validation checks (box/box-codegen[#745](https://github.com/box/box-python-sdk-gen/issues/745)) ([#628](https://github.com/box/box-python-sdk-gen/issues/628)) ([`f0ece63`](https://github.com/box/box-python-sdk-gen/commit/f0ece639d761c765b3bc59fbe3ba8582af755178))
  * Support Hubs beta endpoints (box/box-openapi[#531](https://github.com/box/box-python-sdk-gen/issues/531)) ([#622](https://github.com/box/box-python-sdk-gen/issues/622)) ([`b5e95fe`](https://github.com/box/box-python-sdk-gen/commit/b5e95fe5b219d067028aa395170718eca0d62189))
  * Support new tools in AI Studio (box/box-openapi[#534](https://github.com/box/box-python-sdk-gen/issues/534))  ([#633](https://github.com/box/box-python-sdk-gen/issues/633)) ([`ac76eb2`](https://github.com/box/box-python-sdk-gen/commit/ac76eb2d7c5560b30c4cec171dd90b0a0ece4ab5))
</Update>

<Update label="2025-08-05">
  ## Box Dotnet SDK Generated v1.11.0 released

  ### Bug Fixes

  * Fix downscope token to use `retrieveToken` method for token retrieval (box/box-codegen[#731](https://github.com/box/box-windows-sdk-v2/issues/731)) ([#492](https://github.com/box/box-dotnet-sdk-gen/issues/492)) ([`292360e`](https://github.com/box/box-dotnet-sdk-gen/commit/292360efe86797e42dbfb388a5bd2f5b41efa0c1))
  * Specify events `next_stream_position` property type as `long` (box/box-openapi[#535](https://github.com/box/box-dotnet-sdk-gen/issues/535)) ([#536](https://github.com/box/box-dotnet-sdk-gen/issues/536)) ([`da265bd`](https://github.com/box/box-dotnet-sdk-gen/commit/da265bd5c40defc4b2036811aefad59447faca09))

  ### New Features and Enhancements

  * Add `ReadOnlyCollection` implicit operator for Unions (box/box-codegen[#633](https://github.com/box/box-windows-sdk-v2/issues/633)) ([#483](https://github.com/box/box-dotnet-sdk-gen/issues/483)) ([`a1fc2c5`](https://github.com/box/box-dotnet-sdk-gen/commit/a1fc2c584021c151fc9d1815877ffe73c972f711))
  * Add AI spreadsheet processor (box/box-openapi[#533](https://github.com/box/box-dotnet-sdk-gen/issues/533)) ([#519](https://github.com/box/box-dotnet-sdk-gen/issues/519)) ([`c344023`](https://github.com/box/box-dotnet-sdk-gen/commit/c34402355243145a1cab7da78c6c2facde39fb36))
  * Add Archive Public API (box/box-openapi[#540](https://github.com/box/box-dotnet-sdk-gen/issues/540)) ([#543](https://github.com/box/box-dotnet-sdk-gen/issues/543)) ([`be0bb9d`](https://github.com/box/box-dotnet-sdk-gen/commit/be0bb9d3e58f97bc87f749d08d828c990c71789b))
  * Add new Hubs APIs and Hubs items API (box/box-openapi[#538](https://github.com/box/box-dotnet-sdk-gen/issues/538)) ([#537](https://github.com/box/box-dotnet-sdk-gen/issues/537)) ([`f2584cd`](https://github.com/box/box-dotnet-sdk-gen/commit/f2584cd9be40b67eaa3a500411b367543a26f830))
  * Add new schema for `Metadata Error` (box/box-openapi[#539](https://github.com/box/box-dotnet-sdk-gen/issues/539)) ([#538](https://github.com/box/box-dotnet-sdk-gen/issues/538)) ([`425b4ad`](https://github.com/box/box-dotnet-sdk-gen/commit/425b4add7975d49584c8ed18a791caf72559203c))
  * add Shield Lists APIs (box/box-openapi[#528](https://github.com/box/box-dotnet-sdk-gen/issues/528)) ([#496](https://github.com/box/box-dotnet-sdk-gen/issues/496)) ([`8b81c87`](https://github.com/box/box-dotnet-sdk-gen/commit/8b81c879c8b8bb5c020ecb573e527e2a5d9f1701))
  * Allow injecting private key decryption mechanism for JWT (box/box-codegen[#754](https://github.com/box/box-windows-sdk-v2/issues/754)) ([#528](https://github.com/box/box-dotnet-sdk-gen/issues/528)) ([`865c729`](https://github.com/box/box-dotnet-sdk-gen/commit/865c729395556a3c4a8bb1f1418c3932d268bdc4))
  * Make `OneOf` classes public (box/box-codegen[#773](https://github.com/box/box-windows-sdk-v2/issues/773)) ([#551](https://github.com/box/box-dotnet-sdk-gen/issues/551)) ([`f7dcc32`](https://github.com/box/box-dotnet-sdk-gen/commit/f7dcc3262b289da55ebc6210c5656cc98e3b14b4))
  * Support Hubs beta endpoints (box/box-openapi[#531](https://github.com/box/box-dotnet-sdk-gen/issues/531)) ([#511](https://github.com/box/box-dotnet-sdk-gen/issues/511)) ([`59c43b8`](https://github.com/box/box-dotnet-sdk-gen/commit/59c43b868e46edd26be0be13a5e1772a4d731128))
  * Support new tools in AI Studio (box/box-openapi[#534](https://github.com/box/box-dotnet-sdk-gen/issues/534)) ([#520](https://github.com/box/box-dotnet-sdk-gen/issues/520)) ([`0b47597`](https://github.com/box/box-dotnet-sdk-gen/commit/0b47597f259884a2a5f567608e9e07997e3c6dc9))
  * Update legal holds and AI models (box/box-openapi[#526](https://github.com/box/box-dotnet-sdk-gen/issues/526)) ([#494](https://github.com/box/box-dotnet-sdk-gen/issues/494)) ([`6310e56`](https://github.com/box/box-dotnet-sdk-gen/commit/6310e560df6d9520598295139f55ec8a0a4d69d9))
</Update>

<Update label="2025-08-01">
  ## Box Hubs APIs

  Box Hubs APIs enable you to programmatically create, manage, and collaborate on content hubs within your applications. Hubs provide a centralized space for organizing and sharing content across teams and projects.

  ## What you can do with the Hubs APIs

  The Hubs APIs consist of three main resource types that allow you to build comprehensive hub management functionality:

  1. [Hubs](https://developer.box.com/reference/v2025.0/hubs-resources)
     * Create hub
     * Copy hub
     * Update hub information by ID
     * Delete hub
     * List all hubs
     * List all hubs for requesting enterprise
     * Get hub information by ID

  2. [Hub Collaborations](https://developer.box.com/reference/v2025.0/hub-collaborations-resources)
     * Create hub collaboration
     * Update hub collaboration
     * Remove hub collaboration
     * Get hub collaborations
     * Get hub collaboration by collaboration ID

  3. [Hub Items](https://developer.box.com/reference/v2025.0/hub-items-resources)
     * Get hub items
     * Manage hub items

  To learn more about using Box Hubs, visit the [Box Hubs support documentation](https://support.box.com/hc/en-us/sections/26102544955027-Box-Hubs).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/) for any help needed.
</Update>

<Update label="2025-07-29">
  ## Box Node SDK v3.8.2 released

  ### Bug Fixes

  * Bump `cypress/request` to resolve `CVE-2025-7783` in `form-data` ([#904](https://github.com/box/box-node-sdk/issues/904)) ([`8e8d2da`](https://github.com/box/box-node-sdk/commit/8e8d2da58ab42bdfb9e5a49ca25e9b9fc50e0d61))
</Update>

<Update label="2025-07-27">
  ## Box AI API - Google Gemini 2.5 Pro now available, Gemini 2.5 Flash Preview and Pro Preview deprecated

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with Google Gemini 2.5 Pro.

  The following models have been deprecated:

  * Google Gemini 2.5 Flash Preview
  * Google Gemini 2.5 Pro Preview

  For more information, see [retired models](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions#expandable-1).

  Models offered in **Preview** mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-tutorials/default-agent-overrides) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-07-23">
  ## Box Java SDK v4.16.3 released

  ### Bug Fixes

  * Fix compare message webhook message signature ([#1315](https://github.com/box/box-java-sdk/issues/1315)) ([`e2d407d`](https://github.com/box/box-java-sdk/commit/e2d407ded3370ffee6eb074044fd562629a904be))
  * Fix File Request Copy method to return valid data ([#1320](https://github.com/box/box-java-sdk/issues/1320)) ([`8392a43`](https://github.com/box/box-java-sdk/commit/8392a437c1a738bebb4e7d0f84d6bf833c76bdf3))
</Update>

<Update label="2025-06-24">
  ## Enhanced extract agent

  Today we introduced the new enhanced extract agent powered by Gemini 2.5 Pro. It employs chain-of-thought
  processing to provide the best answer, but also to tell the developer the reason it believes this answer is the correct one.

  The enhanced extract agent:

  * Offers an improved key-value pair extraction from complex documents with higher accuracy.
  * Effortless access with Box UI: activate the feature with a single click.
  * Transforms unstructured data into meaningful metadata attached to files.
  * Enables faster insights and discovery using the Box Metadata search tool.

  Go to the Autofilling Metadata in Templates section in our [product documentation](https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata) to learn more about its capabilities.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-06-24">
  ## AI Studio v2

  With the release of the newest version of the AI Studio functionality, we introduced the [enhancements](/reference/get-ai-agents/) listed below.

  * **Users** receive a notification in case of any issues with an agent directly in the AI Studio UI.
  * Agents are validated in real time. The ones that don't pass validation are not visible for the users.

  **Admins** can:

  * Control the suggested questions displayed when the user starts interacting with a custom AI agent.
  * See the details of a request and response of a LLM, for example the system prompt, model, custom instructions.
  * Control the parameters of a Box AI image processor in a custom agent. The parameters are necessary to ask a LLM about a specific image.

  You can find more information in our [API](/reference/get-ai-agents/) and [product documentation](https://support.box.com/hc/en-us/articles/37228357884179-Creating-and-Configuring-Agents).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-06-20">
  ## Box CLI v4.2.0 released

  ### New Features and Enhancements

  * Setup proxy for Box CLI with TS SDK ([#577](https://github.com/box/boxcli/issues/577)) ([`ec42077`](https://github.com/box/boxcli/commit/ec4207715360cc284574e1cbb573586218379517))
  * Support `owned-by` flag when moving folder ([#580](https://github.com/box/boxcli/issues/580)) ([`2ec8e7f`](https://github.com/box/boxcli/commit/2ec8e7fcf241dcd2c5841b8912e178e2384db426))
  * Support integration mappings for Teams ([#579](https://github.com/box/boxcli/issues/579)) ([`163a367`](https://github.com/box/boxcli/commit/163a36727c5f76b0e3b1c36049b3abae50148eb6))
  * Support metadata query with array ([#581](https://github.com/box/boxcli/issues/581)) ([`6750708`](https://github.com/box/boxcli/commit/675070856eac6d06f2091203f4f19e41055dd97d))
</Update>

<Update label="2025-06-12">
  ## Box TypeScript SDK Generated v1.16.0 released

  ### Bug Fixes

  * Compute webhook signature with and without escaping the body (box/box-codegen[#737](https://github.com/box/box-typescript-sdk-gen/issues/737)) ([#627](https://github.com/box/box-typescript-sdk-gen/issues/627)) ([`6a21b8e`](https://github.com/box/box-typescript-sdk-gen/commit/6a21b8ed54ef26041feccaa5481951355965e514))
  * Fix circular dependency in `boxNetworkClient` (box/box-codegen[#708](https://github.com/box/box-typescript-sdk-gen/issues/708)) ([#591](https://github.com/box/box-typescript-sdk-gen/issues/591)) ([`b383889`](https://github.com/box/box-typescript-sdk-gen/commit/b383889b9fdc91c6cfed7169e4d36a22a8c8a0fa))
  * Fix downscope token to use `retrieveToken` method for token retrieval (box/box-codegen[#731](https://github.com/box/box-typescript-sdk-gen/issues/731)) ([#618](https://github.com/box/box-typescript-sdk-gen/issues/618)) ([`90edb0c`](https://github.com/box/box-typescript-sdk-gen/commit/90edb0cc9bddc474c20b8b83770a4d314843edab))
  * Fix slash escaping when calculating webhook signature (box/box-codegen[#736](https://github.com/box/box-typescript-sdk-gen/issues/736)) ([#624](https://github.com/box/box-typescript-sdk-gen/issues/624)) ([`a0307d0`](https://github.com/box/box-typescript-sdk-gen/commit/a0307d0c4c5dfed1a66e395a1dfb4c8ff387561d))
  * Handle list of strings in metadata filter (box/box-codegen[#716](https://github.com/box/box-typescript-sdk-gen/issues/716)) ([#597](https://github.com/box/box-typescript-sdk-gen/issues/597)) ([`979ff2c`](https://github.com/box/box-typescript-sdk-gen/commit/979ff2c82edce9a969444febf1896d866ca154bf))
  * Improve file download to avoid storing content in memory (box/box-codegen[#701](https://github.com/box/box-typescript-sdk-gen/issues/701)) ([#589](https://github.com/box/box-typescript-sdk-gen/issues/589)) ([`513a15e`](https://github.com/box/box-typescript-sdk-gen/commit/513a15eb28736d28d665324949d145dd3387d27d))
  * Modify utility functions for browser (box/box-codegen[#686](https://github.com/box/box-typescript-sdk-gen/issues/686)) ([#585](https://github.com/box/box-typescript-sdk-gen/issues/585)) ([`7232170`](https://github.com/box/box-typescript-sdk-gen/commit/7232170fe7901cb7ba9ebf79ffc6a7c0b376a1c8))
  * Use constant-time comparison for HMAC signatures (box/box-codegen[#739](https://github.com/box/box-typescript-sdk-gen/issues/739)) ([#630](https://github.com/box/box-typescript-sdk-gen/issues/630)) ([`efdcaaf`](https://github.com/box/box-typescript-sdk-gen/commit/efdcaaf605fc6f14bbbf171e2797d73e97302bfe))

  ### New Features and Enhancements

  * Add AI agents warnings; allow for more types of metadata value (box/box-openapi[#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([#600](https://github.com/box/box-typescript-sdk-gen/issues/600)) ([`a5a555f`](https://github.com/box/box-typescript-sdk-gen/commit/a5a555f835df5b550b9839e3e1fcff5d9f2b9f96))
  * Add security settings properties on sign template schema (box/box-openapi[#518](https://github.com/box/box-typescript-sdk-gen/issues/518)) ([#588](https://github.com/box/box-typescript-sdk-gen/issues/588)) ([`dfd3e5f`](https://github.com/box/box-typescript-sdk-gen/commit/dfd3e5f7ecf8a8e49d79ed7df4d7e1f88f3e8537))
  * Add Shield Lists APIs (box/box-openapi[#528](https://github.com/box/box-typescript-sdk-gen/issues/528)) ([#622](https://github.com/box/box-typescript-sdk-gen/issues/622)) ([`be3af44`](https://github.com/box/box-typescript-sdk-gen/commit/be3af441a66da02254d38576bb9ec258142f6d2d))
  * Add support of IBM models to AI API (box/box-openapi[#522](https://github.com/box/box-typescript-sdk-gen/issues/522)) ([#601](https://github.com/box/box-typescript-sdk-gen/issues/601)) ([`b060b8c`](https://github.com/box/box-typescript-sdk-gen/commit/b060b8c21a13abdfb12988f9c6e6beb014fa104f))
  * Increase max items for ai extract endpoints (box/box-openapi[#525](https://github.com/box/box-typescript-sdk-gen/issues/525)) ([#602](https://github.com/box/box-typescript-sdk-gen/issues/602)) ([`86c5d14`](https://github.com/box/box-typescript-sdk-gen/commit/86c5d14bafe8789c306a1688bcf010207c302ca9))
  * Update legal holds and AI models (box/box-openapi[#526](https://github.com/box/box-typescript-sdk-gen/issues/526)) ([#620](https://github.com/box/box-typescript-sdk-gen/issues/620)) ([`de3df57`](https://github.com/box/box-typescript-sdk-gen/commit/de3df57cc90577a49ea40de278bde423d17c4f06))
</Update>

<Update label="2025-06-12">
  ## Box Python SDK Generated v1.15.0 released

  ### Bug Fixes

  * Compute webhook signature with and without escaping the body (box/box-codegen[#737](https://github.com/box/box-python-sdk-gen/issues/737)) ([#607](https://github.com/box/box-python-sdk-gen/issues/607)) ([`e5118b8`](https://github.com/box/box-python-sdk-gen/commit/e5118b8a257a042510374d91bd62a1f98c662fef))
  * Fix downscope token to use `retrieveToken` method for token retrieval (box/box-codegen[#731](https://github.com/box/box-python-sdk-gen/issues/731)) ([#598](https://github.com/box/box-python-sdk-gen/issues/598)) ([`e492685`](https://github.com/box/box-python-sdk-gen/commit/e4926851edccd4ee7e66157050cedd0d01cec5ea))
  * Fix slash escaping when calculating webhook signature (box/box-codegen[#736](https://github.com/box/box-python-sdk-gen/issues/736)) ([#603](https://github.com/box/box-python-sdk-gen/issues/603)) ([`430b175`](https://github.com/box/box-python-sdk-gen/commit/430b1754ec840582e28a277c6c8d369cbe7ebdf5))
  * Use constant-time comparison for HMAC signatures (box/box-codegen[#739](https://github.com/box/box-python-sdk-gen/issues/739)) ([#610](https://github.com/box/box-python-sdk-gen/issues/610)) ([`6f6660c`](https://github.com/box/box-python-sdk-gen/commit/6f6660c8f3aa2b7b75b0fcd4ed015d8d761cd77f))

  ### New Features and Enhancements

  * Add AI agents warnings; allow for more types of metadata value (box/box-openapi[#520](https://github.com/box/box-python-sdk-gen/issues/520)) ([#567](https://github.com/box/box-python-sdk-gen/issues/567)) ([`86aa1cc`](https://github.com/box/box-python-sdk-gen/commit/86aa1ccadac9acead7bceeafb50e45f38eb2d9cc))
  * Add Shield Lists APIs (box/box-openapi[#528](https://github.com/box/box-python-sdk-gen/issues/528)) ([#601](https://github.com/box/box-python-sdk-gen/issues/601)) ([`f980f65`](https://github.com/box/box-python-sdk-gen/commit/f980f6544a58a5c64ab0b3ec13b2771b81ea25ed))
  * Add support of IBM models to AI API (box/box-openapi[#522](https://github.com/box/box-python-sdk-gen/issues/522)) ([#568](https://github.com/box/box-python-sdk-gen/issues/568)) ([`767547a`](https://github.com/box/box-python-sdk-gen/commit/767547ae070909852800c447e65cbcc95b97c5a3))
  * Update legal holds and AI models (box/box-openapi[#526](https://github.com/box/box-python-sdk-gen/issues/526)) ([#599](https://github.com/box/box-python-sdk-gen/issues/599)) ([`d56228d`](https://github.com/box/box-python-sdk-gen/commit/d56228d81bd9777af5431ccc9d05233e13a0c2ed))
</Update>

<Update label="2025-06-11">
  ## Box Node SDK v3.8.1 released

  ### Bug Fixes

  * Use constant-time comparison for HMAC signatures ([#893](https://github.com/box/box-node-sdk/issues/893)) ([`d819efe`](https://github.com/box/box-node-sdk/commit/d819efe663a59fce53412fbe153a76dd346d4536))
</Update>

<Update label="2025-06-02">
  ## Box Java SDK v4.16.2 released

  ### Bug Fixes

  * Fix parsing `downloadFileCount` property for `BoxZipDownloadStatus` ([`50c2249`](https://github.com/box/box-java-sdk/commit/50c2249ff5e0f0d1fdc99c9ff8786e9c134e58eb))
</Update>

<Update label="2025-05-24">
  ## Box AI API - new AI models now available, Gemini 1.5 models deprecated

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with the following models:

  * AWS Claude 4 Sonnet
  * AWS Claude 4 Opus

  The following models have been deprecated:

  * Google Gemini 1.5 Flash 001
  * Google Gemini 1.5 Pro 001

  For more information, see [retired models](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/model-versions#expandable-1).

  Azure OpenAI GPT o4 Mini model was removed.

  Models offered in **Preview** mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-tutorials/default-agent-overrides) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-05-15">
  ## Box CLI v4.1.0 released

  ### New Features and Enhancements

  * Support AI Extract endpoints ([#574](https://github.com/box/boxcli/issues/574)) ([`0b4ff6b`](https://github.com/box/boxcli/commit/0b4ff6b63c8707c6842f3812d2a69071d195b799))

  ### Bug Fixes

  * Remove incorrect `process.stderr.setEncoding` call ([`486779e`](https://github.com/box/boxcli/commit/486779ee3b8403805286b7ae6d3ab5c802c6f948)), closes [#571](https://github.com/box/boxcli/issues/571)
</Update>

<Update label="2025-05-13">
  ## Box Dotnet SDK Generated v1.10.0 released

  ### New Features and Enhancements

  * Add `UploadWithPreflightCheck` convenient method (box/box-codegen[#705](https://github.com/box/box-windows-sdk-v2/issues/705)) ([#469](https://github.com/box/box-dotnet-sdk-gen/issues/469)) ([`8dff7bb`](https://github.com/box/box-dotnet-sdk-gen/commit/8dff7bb859cd034d4e43b81c7c11b9a3fdb396e8))
  * Add AI agents warnings; allow for more types of metadata value (box/box-openapi[#520](https://github.com/box/box-dotnet-sdk-gen/issues/520)) ([#474](https://github.com/box/box-dotnet-sdk-gen/issues/474)) ([`a53cff5`](https://github.com/box/box-dotnet-sdk-gen/commit/a53cff54395db91bad179d3c5bbae9800c1b79dd))
  * Add security settings properties on sign template schema (box/box-openapi[#518](https://github.com/box/box-dotnet-sdk-gen/issues/518)) ([#462](https://github.com/box/box-dotnet-sdk-gen/issues/462)) ([`7fddaea`](https://github.com/box/box-dotnet-sdk-gen/commit/7fddaeab425a859dc1aa5dc3420891047d27efdf))
  * Add support of IBM models to AI API (box/box-openapi[#522](https://github.com/box/box-dotnet-sdk-gen/issues/522)) ([#475](https://github.com/box/box-dotnet-sdk-gen/issues/475)) ([`a187301`](https://github.com/box/box-dotnet-sdk-gen/commit/a187301543d6741c77799b66fde0f12d4fca710d))
  * Support sensitive data sanitization in errors (box/box-codegen[#695](https://github.com/box/box-windows-sdk-v2/issues/695)) ([#453](https://github.com/box/box-dotnet-sdk-gen/issues/453)) ([`5ee0c93`](https://github.com/box/box-dotnet-sdk-gen/commit/5ee0c932254a0cd1cc7bc814c29fe5f9e2151462))
</Update>

<Update label="2025-05-12">
  ## Box UI Elements v23.3.0 released

  ### [23.3.0](https://github.com/box/box-ui-elements/compare/v23.2.0...v23.3.0) (2025-05-12)

  ### Bug Fixes

  * **`commitlint`:** Bump to 19.8.0 ([#4083](https://github.com/box/box-ui-elements/issues/4083)) ([`7e9e6e5`](https://github.com/box/box-ui-elements/commit/7e9e6e5ef30eb080313276f8549337710ecd875f))
  * **flow-typed:** Bumped to 4.1.0 ([#4081](https://github.com/box/box-ui-elements/issues/4081)) ([`15b8108`](https://github.com/box/box-ui-elements/commit/15b81086caf692986717f34e259d745fb6c34b04))
  * **flyout:** change logic for `onKeyPress` in `Flyout.js` ([#4096](https://github.com/box/box-ui-elements/issues/4096)) ([`f48c2a9`](https://github.com/box/box-ui-elements/commit/f48c2a92d8df6d731965dfa0d60d93c05f0c8e80))
  * **i18n:** update translations ([#4077](https://github.com/box/box-ui-elements/issues/4077)) ([`fe7752d`](https://github.com/box/box-ui-elements/commit/fe7752d809f4946040bf18dec4a8a980b22c908e))
  * **i18n:** update translations ([#4079](https://github.com/box/box-ui-elements/issues/4079)) ([`0f587f5`](https://github.com/box/box-ui-elements/commit/0f587f522e1904b37fccf25bdfff98d1c3252aea))
  * **i18n:** update translations ([#4089](https://github.com/box/box-ui-elements/issues/4089)) ([`f48076d`](https://github.com/box/box-ui-elements/commit/f48076d2cf967283dd5c9af95540ac1743a6ab71))
  * **i18n:** update translations ([#4091](https://github.com/box/box-ui-elements/issues/4091)) ([`9869175`](https://github.com/box/box-ui-elements/commit/986917536c15345378b64bfc9e66d47ade83b930))
  * **i18n:** update translations ([#4097](https://github.com/box/box-ui-elements/issues/4097)) ([`e265cfe`](https://github.com/box/box-ui-elements/commit/e265cfef405c9644863c612a72158dac0bc2c439))
  * **metadata-sidebar:** Show all metadata fields fix ([#4090](https://github.com/box/box-ui-elements/issues/4090)) ([`e4dcdcb`](https://github.com/box/box-ui-elements/commit/e4dcdcb1ef5b9247b69b4b0666ac68c9ad82f6b2))
  * **`opensource`:** copy storybook files to root ([#4099](https://github.com/box/box-ui-elements/issues/4099)) ([`37c9cf0`](https://github.com/box/box-ui-elements/commit/37c9cf06da4d17006f053cedbef6d4fedec09ed5))
  * **sass-lint:** Remove sass-lint ([#4082](https://github.com/box/box-ui-elements/issues/4082)) ([`05d1e8b`](https://github.com/box/box-ui-elements/commit/05d1e8b9f094b35dc0494c09f30777be6cd4ce2c))

  ### Features

  * **`bp-assets`:** Bump BP assets to 4.39.0 ([#4095](https://github.com/box/box-ui-elements/issues/4095)) ([`15c403c`](https://github.com/box/box-ui-elements/commit/15c403c402e135ff9f5f73da011633d6ac923e3d))
  * **content-sidebar:** additional prop for feedback tooltip in Box AI ([#4075](https://github.com/box/box-ui-elements/issues/4075)) ([`bcd2b86`](https://github.com/box/box-ui-elements/commit/bcd2b8698106ab5c03dcd44be7a948ab4a5cf203))
  * **content-sidebar:** update content-answers for box ai sidebar ([#4094](https://github.com/box/box-ui-elements/issues/4094)) ([`8d4c456`](https://github.com/box/box-ui-elements/commit/8d4c456dae84978341c3af572c81299ead047b9b))
  * **metadata-sidebar:** Is delete confirmation modal checkbox enabled ([#4076](https://github.com/box/box-ui-elements/issues/4076)) ([`7e8c8ac`](https://github.com/box/box-ui-elements/commit/7e8c8ac824f53c9264e939ba396369412150e5d0))
  * **`metadataeditor`:** add agent selector ([#4098](https://github.com/box/box-ui-elements/issues/4098)) ([`f3af868`](https://github.com/box/box-ui-elements/commit/f3af86837955e4ff7ebb0d3a938538139d9eeabf))
  * **`metadataeditor`:** add ai extraction for folders ([#4080](https://github.com/box/box-ui-elements/issues/4080)) ([`82d6b29`](https://github.com/box/box-ui-elements/commit/82d6b29c40b1c70eae027d084396600aae36fdeb))
  * **notification-redesign:** Add Notification classname prop ([#4092](https://github.com/box/box-ui-elements/issues/4092)) ([`2dc371f`](https://github.com/box/box-ui-elements/commit/2dc371fa6ea1a6a70dfd4f0fec05925fd581b7b3))
  * **`opensource`:** update default route to use storybook ([#4087](https://github.com/box/box-ui-elements/issues/4087)) ([`174f335`](https://github.com/box/box-ui-elements/commit/174f335b7bd80f1b75a03441a3e14afb50f3e82d))
  * **unified-share-modal:** add custom permission descriptions ([#4071](https://github.com/box/box-ui-elements/issues/4071)) ([`19a7978`](https://github.com/box/box-ui-elements/commit/19a7978121ac005cecd8643584076d4f2f1864ee))
  * upgrade blueprint packages ([#4101](https://github.com/box/box-ui-elements/issues/4101)) ([`f8606cf`](https://github.com/box/box-ui-elements/commit/f8606cf689b1468ebec5948e018bfa86b237705f))

  ### Reverts

  * "chore(storybook): Bump to v8.6.12 ([#4069](https://github.com/box/box-ui-elements/issues/4069))" ([#4078](https://github.com/box/box-ui-elements/issues/4078)) ([`cbe4c0a`](https://github.com/box/box-ui-elements/commit/cbe4c0a22d3526f6090d8c67bce38dcb9d5a4772))
</Update>

<Update label="2025-05-02">
  ## Box Python SDK Generated v1.14.0 released

  ### Bug Fixes

  * set default timeouts for requests (box/box-codegen[#707](https://github.com/box/box-python-sdk-gen/issues/707)) ([#552](https://github.com/box/box-python-sdk-gen/issues/552)) ([`66b87c8`](https://github.com/box/box-python-sdk-gen/commit/66b87c8986ce2f5fdb3a9eac995ef8a9643bcd76))

  ### New Features and Enhancements

  * Add security settings properties on sign template schema (box/box-openapi[#518](https://github.com/box/box-python-sdk-gen/issues/518)) ([#543](https://github.com/box/box-python-sdk-gen/issues/543)) ([`0a45d21`](https://github.com/box/box-python-sdk-gen/commit/0a45d218d1aa3fa62da7b5c8c01506fb657c0b36))
  * Support sensitive data sanitization in errors (box/box-codegen[#695](https://github.com/box/box-python-sdk-gen/issues/695)) ([#533](https://github.com/box/box-python-sdk-gen/issues/533)) ([`abb7b1d`](https://github.com/box/box-python-sdk-gen/commit/abb7b1d16a192edd99ff1fc4fb7c4caf79ee5f10))
</Update>

<Update label="2025-04-30">
  ## Box AI API - new AI models now available

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with the following models:

  * Azure OpenAI o3 (beta)
  * Azure OpenAI o4 mini (beta)
  * xAI Grok 3 (beta)
  * xAI Grok 3 mini (beta)

  Models offered in **Preview** mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-tutorials/default-agent-overrides) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-04-29">
  ## Box AI API - new AI models now available

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with the following models:

  * Azure OpenAI GPT-4.1
  * Azure OpenAI GPT-4.1 Mini
  * Gemini 2.5 Pro Preview
  * Gemini 2.5 Flash Preview
  * IBM Llama 4 Scout
  * IBM Llama 3.2 Instruct

  Models offered in **Preview** mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-tutorials/default-agent-overrides) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-04-29">
  ## Box Java SDK v4.16.1 released

  ### Bug Fixes

  * use `Locale.ROOT` to prevent issues with non-US locales ([#1306](https://github.com/box/box-java-sdk/issues/1306)) ([`f083092`](https://github.com/box/box-java-sdk/commit/f083092d5fdac37c93493945ab0c05ecdcdbc838))
</Update>

<Update label="2025-04-25">
  ## Box UI Elements v23.2.0 released

  ### [23.2.0](https://github.com/box/box-ui-elements/compare/v23.1.0...v23.2.0) (2025-04-25)

  ### Bug Fixes

  * **content-answers:** fix CSS variable ([#4074](https://github.com/box/box-ui-elements/issues/4074)) ([`393d83b`](https://github.com/box/box-ui-elements/commit/393d83ba8c8882f6b136b38f933bfc17f5be0720))
  * **i18n:** update translations ([#4072](https://github.com/box/box-ui-elements/issues/4072)) ([`dc1cf01`](https://github.com/box/box-ui-elements/commit/dc1cf014f1bb84384244cf68d684d07bd6420d11))

  ### Features

  * **message-center:** Pass `badgeCount` to `ButtonComponent` ([#4068](https://github.com/box/box-ui-elements/issues/4068)) ([`e316267`](https://github.com/box/box-ui-elements/commit/e3162676d06dc330c42204b0871cc61140665c57))
  * **unified-share-modal:** add remove collaborators ([#4070](https://github.com/box/box-ui-elements/issues/4070)) ([`4645733`](https://github.com/box/box-ui-elements/commit/4645733c1d5aad0a42cbabd130741bdd6923243e))
</Update>

<Update label="2025-04-17">
  ## Box UI Elements v23.1.0 released

  ### [23.1.0](https://github.com/box/box-ui-elements/compare/v23.0.0...v23.1.0) (2025-04-17)

  ### Bug Fixes

  * **axios:** Bump Axios to 0.30.0 ([#4039](https://github.com/box/box-ui-elements/issues/4039)) ([`e212834`](https://github.com/box/box-ui-elements/commit/e212834b2c5ec6e64d6c5378e7b114c3526d21f4))
  * **content-explorer:** Add default dimension to `ItemListIcon` ([#4052](https://github.com/box/box-ui-elements/issues/4052)) ([`900757c`](https://github.com/box/box-ui-elements/commit/900757c6bdd760b31ad0ba7c717f3fe71a799ed3))
  * **content-explorer:** improve theming feature ([#4045](https://github.com/box/box-ui-elements/issues/4045)) ([`5ad4a94`](https://github.com/box/box-ui-elements/commit/5ad4a94d9e3a8792ad32518272bb1aecf8cf47fc))
  * **content-explorer:** remove base styles ([#4063](https://github.com/box/box-ui-elements/issues/4063)) ([`071f5b9`](https://github.com/box/box-ui-elements/commit/071f5b9cdcadd0cfa15589dc47b1c3361299c0a7))
  * **i18n:** update translations ([#4038](https://github.com/box/box-ui-elements/issues/4038)) ([`2977e50`](https://github.com/box/box-ui-elements/commit/2977e5014e079a776f4316cc348512d182780f3a))
  * **i18n:** update translations ([#4040](https://github.com/box/box-ui-elements/issues/4040)) ([`6c89353`](https://github.com/box/box-ui-elements/commit/6c89353911c1be3fa10ae411242e8fcd51aaa8d0))
  * **i18n:** update translations ([#4050](https://github.com/box/box-ui-elements/issues/4050)) ([`a6b5074`](https://github.com/box/box-ui-elements/commit/a6b50746500ef6d6d8316c78a1703b5f943ddf89))
  * **i18n:** update translations ([#4051](https://github.com/box/box-ui-elements/issues/4051)) ([`4f74362`](https://github.com/box/box-ui-elements/commit/4f7436230d6450a60ea6444bcbb6faf5c17612b9))
  * **i18n:** update translations ([#4056](https://github.com/box/box-ui-elements/issues/4056)) ([`5d2e63b`](https://github.com/box/box-ui-elements/commit/5d2e63bff00cd5fe3cafb58ba9c5e2807d849fbc))
  * **ip:** remove resolution ([#4057](https://github.com/box/box-ui-elements/issues/4057)) ([`8ad6f71`](https://github.com/box/box-ui-elements/commit/8ad6f718ae32cba1104ceab2de08cabcc8da5ce2))
  * **item-options:** render correctly when item actions are filtered ([#4042](https://github.com/box/box-ui-elements/issues/4042)) ([`ab56916`](https://github.com/box/box-ui-elements/commit/ab56916d4048acfecc03b0d1036791504a52caed))
  * **metadata-editor:** Handle new taxonomy API ([#4049](https://github.com/box/box-ui-elements/issues/4049)) ([`ed622af`](https://github.com/box/box-ui-elements/commit/ed622af35a2a016a2e6df14b25b79f5488bb9e1d))
  * **stylelint:** Bump to v16 ([#4058](https://github.com/box/box-ui-elements/issues/4058)) ([`db6c93e`](https://github.com/box/box-ui-elements/commit/db6c93ef9f7b6ff13fe9198b697ec45c3f303335))
  * **uaa-parity:** Display error message for UAA errors ([#4035](https://github.com/box/box-ui-elements/issues/4035)) ([`f9e9f35`](https://github.com/box/box-ui-elements/commit/f9e9f35ec07fd720d6148d4b324d5a342ac3e558))
  * **uaa-parity:** Not showing fallback `promoted_by user` for empty `promoted_by user` ([#4043](https://github.com/box/box-ui-elements/issues/4043)) ([`a586a0a`](https://github.com/box/box-ui-elements/commit/a586a0a3da711ce1803a4e8999af839a668598fb))

  ### Features

  * **content-explorer:** Add feature flag for `MetadataViewList` redesign ([#4061](https://github.com/box/box-ui-elements/issues/4061)) ([`5d0c716`](https://github.com/box/box-ui-elements/commit/5d0c716f449bed05f3c638a00f292e6fe00a4b40))
  * **content-explorer:** enable independent theming ([#4062](https://github.com/box/box-ui-elements/issues/4062)) ([`a67be72`](https://github.com/box/box-ui-elements/commit/a67be72dc9886094444627d97619d79195d67427))
  * **content-picker:** Add `MoreOptions` button to rows ([#4036](https://github.com/box/box-ui-elements/issues/4036)) ([`f3667dc`](https://github.com/box/box-ui-elements/commit/f3667dc104c283287049e2c8ca43a46aa9bb1068))
  * **content-sidebar:** added support for feedback tooltip in Box AI ([#4059](https://github.com/box/box-ui-elements/issues/4059)) ([`b09cbf3`](https://github.com/box/box-ui-elements/commit/b09cbf3cf18a36274410df5f0859675445e23cb1))
  * **doc-first-pages:** Add webp xrep header ([#4054](https://github.com/box/box-ui-elements/issues/4054)) ([`ca41b1a`](https://github.com/box/box-ui-elements/commit/ca41b1ad22f89667b30e552040224abab3182c27))
  * **metadata-sidebar:** Control Multilevel Taxonomy ([#4037](https://github.com/box/box-ui-elements/issues/4037)) ([`f705927`](https://github.com/box/box-ui-elements/commit/f705927f9071950a59d4f3d5da1e141dad21d4b0))
  * **metadata-sidebar:** Multilevel taxonomy integration ([#4044](https://github.com/box/box-ui-elements/issues/4044)) ([`8a794ad`](https://github.com/box/box-ui-elements/commit/8a794adb431d3dd7efd0518d0de4c3b361975c7d))
</Update>

<Update label="2025-04-15">
  ## Box Java SDK v4.16.0 released

  ### New Features and Enhancements

  * Bump version of `zstd-jni` ([#1302](https://github.com/box/box-java-sdk/issues/1302)) ([`9ebf8b5`](https://github.com/box/box-java-sdk/commit/9ebf8b5d16c0ab8f4aa19849fdaa86935d38b294))
</Update>

<Update label="2025-04-11">
  ## Box TypeScript SDK Generated v1.15.1 released

  ### Bug Fixes

  * Fix data sanitizer for TypeScript (box/box-codegen[#702](https://github.com/box/box-typescript-sdk-gen/issues/702)) ([#582](https://github.com/box/box-typescript-sdk-gen/issues/582)) ([`eb79c0f`](https://github.com/box/box-typescript-sdk-gen/commit/eb79c0faa11f40667289155e71b8893a96eb558a))
</Update>

<Update label="2025-04-10">
  ## Box TypeScript SDK Generated v1.15.0 released

  ### New Features and Enhancements

  * Support sensitive data sanitization in errors (box/box-codegen[#695](https://github.com/box/box-typescript-sdk-gen/issues/695)) ([#573](https://github.com/box/box-typescript-sdk-gen/issues/573)) ([`488e76a`](https://github.com/box/box-typescript-sdk-gen/commit/488e76a1e1f66d5d4ac56b16e6a7dae9e7f497a1))
</Update>

<Update label="2025-04-09">
  ## Box Python SDK v3.14.0 released

  ### New Features and Enhancements

  * Add `stream_file_content` parameter to upload methods ([#890](https://github.com/box/box-python-sdk/issues/890)) ([`0e63c00`](https://github.com/box/box-python-sdk/commit/0e63c002ee17618c08200c12caae4bb3890b1e90))
</Update>

<Update label="2025-04-09">
  ## Box Node SDK v3.8.0 released

  ### New Features and Enhancements

  * Support AI agent ([#887](https://github.com/box/box-node-sdk/issues/887)) ([`5b109ad`](https://github.com/box/box-node-sdk/commit/5b109adbd506510fc83b1c90af13b063ddefab37))
</Update>

<Update label="2025-03-26">
  ## Box UI Elements v23.0.0 released

  ### [23.0.0](https://github.com/box/box-ui-elements/compare/v22.1.0...v23.0.0) (2025-03-26)

  ### Features

  * BREAKING CHANGE noop to trigger major version release ([#4034](https://github.com/box/box-ui-elements/issues/4034)) ([`4e1751f`](https://github.com/box/box-ui-elements/commit/4e1751f4054f53bc62880dd3371893a853f93aa2))

  ### BREAKING CHANGES

  * update peer dependencies for `@box/` packages
</Update>

<Update label="2025-03-18">
  ## Box TypeScript SDK Generated v1.14.0 released

  ### Bug Fixes

  * Add `verification_phone_number` property to create sign request (box/box-openapi[#515](https://github.com/box/box-typescript-sdk-gen/issues/515)) ([#546](https://github.com/box/box-typescript-sdk-gen/issues/546)) ([`916502c`](https://github.com/box/box-typescript-sdk-gen/commit/916502c47cb4936ab93a40b3f1552c1860173a8e))

  ### New Features and Enhancements

  * Add find app item for shared link endpoint (box/box-openapi[#514](https://github.com/box/box-typescript-sdk-gen/issues/514)) ([#545](https://github.com/box/box-typescript-sdk-gen/issues/545)) ([`7c32eaf`](https://github.com/box/box-typescript-sdk-gen/commit/7c32eaf2af3ef08299d9dd69e744304b20f4309f))
  * Add Integration Mappings Teams API (box/box-openapi[#517](https://github.com/box/box-typescript-sdk-gen/issues/517)) ([#548](https://github.com/box/box-typescript-sdk-gen/issues/548)) ([`6ce1c7c`](https://github.com/box/box-typescript-sdk-gen/commit/6ce1c7c78c9bc5d70383065e95f01bc8133fdd52))
  * Support upload with preflight check (box/box-codegen[#676](https://github.com/box/box-typescript-sdk-gen/issues/676)) ([#554](https://github.com/box/box-typescript-sdk-gen/issues/554)) ([`e3aa784`](https://github.com/box/box-typescript-sdk-gen/commit/e3aa784b73c7b473fdf06c05c7f657a54fc08e4c))
</Update>

<Update label="2025-03-18">
  ## Box Swift SDK Generated 0.6.1 released

  ### Bug Fixes

  * Add `verification_phone_number` property to create sign request (box/box-openapi[#515](https://github.com/box/box-swift-sdk-gen/issues/515)) ([#391](https://github.com/box/box-swift-sdk-gen/issues/391)) ([`717b3a8`](https://github.com/box/box-swift-sdk-gen/commit/717b3a8b285dfab92a9446cbd84443caa8dde148))

  ### New Features and Enhancements

  * Add find app item for shared link endpoint (box/box-openapi[#514](https://github.com/box/box-swift-sdk-gen/issues/514)) ([#390](https://github.com/box/box-swift-sdk-gen/issues/390)) ([`07b9be5`](https://github.com/box/box-swift-sdk-gen/commit/07b9be5d523f3d3fb89bdbb240e4ca9628a3736d))
  * Add hubs support to `/ai/ask` (box/box-codegen[#656](https://github.com/box/box-swift-sdk-gen/issues/656)) ([#364](https://github.com/box/box-swift-sdk-gen/issues/364)) ([`9a49864`](https://github.com/box/box-swift-sdk-gen/commit/9a4986499eaefffdb4f2593968d59eaf030f516f))
  * Add Integration Mappings Teams API (box/box-openapi[#517](https://github.com/box/box-swift-sdk-gen/issues/517)) ([#393](https://github.com/box/box-swift-sdk-gen/issues/393)) ([`b9ed4e3`](https://github.com/box/box-swift-sdk-gen/commit/b9ed4e35d17f85c1d2bc2a4e9e148ae009551348))
  * Expose token storage for authentication classes (box/box-codegen[#682](https://github.com/box/box-swift-sdk-gen/issues/682)) ([#400](https://github.com/box/box-swift-sdk-gen/issues/400)) ([`08221e5`](https://github.com/box/box-swift-sdk-gen/commit/08221e59cabc4042ea1d43bf578c2069ad66b444))
  * Support AI Studio API (box/box-codegen[#626](https://github.com/box/box-swift-sdk-gen/issues/626)) ([#375](https://github.com/box/box-swift-sdk-gen/issues/375)) ([`802571d`](https://github.com/box/box-swift-sdk-gen/commit/802571dd34977ae2ebf674dbdddd3e140829b819))
  * Support unknown enum values (box/box-codegen[#670](https://github.com/box/box-swift-sdk-gen/issues/670)) ([#382](https://github.com/box/box-swift-sdk-gen/issues/382)) ([`8fe7ff4`](https://github.com/box/box-swift-sdk-gen/commit/8fe7ff45fa4e45f743acd4450270d945b0afd393))
  * Support upload with preflight check (box/box-codegen[#676](https://github.com/box/box-swift-sdk-gen/issues/676)) ([#399](https://github.com/box/box-swift-sdk-gen/issues/399)) ([`1befb4c`](https://github.com/box/box-swift-sdk-gen/commit/1befb4c1b4898375ea3ab353c7149fd10adc1f17))
  * Update `/ai/extract_structured` response schema (box/box-codegen[#641](https://github.com/box/box-swift-sdk-gen/issues/641)) ([#358](https://github.com/box/box-swift-sdk-gen/issues/358)) ([`430611a`](https://github.com/box/box-swift-sdk-gen/commit/430611a0036258d5f3ff8e1c6de0b833255ce0ed))
</Update>

<Update label="2025-03-18">
  ## Box Python SDK Generated v1.13.0 released

  ### Bug Fixes

  * Add `verification_phone_number` property to create sign request (box/box-openapi[#515](https://github.com/box/box-python-sdk-gen/issues/515)) ([#503](https://github.com/box/box-python-sdk-gen/issues/503)) ([`6d19d19`](https://github.com/box/box-python-sdk-gen/commit/6d19d197481a578d7d5ad8d632ac6f5c06bd3dce))

  ### New Features and Enhancements

  * Add find app item for shared link endpoint (box/box-openapi[#514](https://github.com/box/box-python-sdk-gen/issues/514)) ([#502](https://github.com/box/box-python-sdk-gen/issues/502)) ([`fd6c693`](https://github.com/box/box-python-sdk-gen/commit/fd6c6933f0fb518830e9ac810fd511a0cf60b429))
  * Add Integration Mappings Teams API (box/box-openapi[#517](https://github.com/box/box-python-sdk-gen/issues/517)) ([#505](https://github.com/box/box-python-sdk-gen/issues/505)) ([`d1aa250`](https://github.com/box/box-python-sdk-gen/commit/d1aa250fb01fbf742daf266d4458ba2eab2c5669))
  * Support upload with preflight check (box/box-codegen[#676](https://github.com/box/box-python-sdk-gen/issues/676)) ([#515](https://github.com/box/box-python-sdk-gen/issues/515)) ([`bb4597e`](https://github.com/box/box-python-sdk-gen/commit/bb4597e40d49e20eca44c4414e406b1352af1a2b))
</Update>

<Update label="2025-03-18">
  ## Box Dotnet SDK Generated v1.9.0 released

  ### Bug Fixes

  * Add `verification_phone_number` property to create sign request (box/box-openapi[#515](https://github.com/box/box-dotnet-sdk-gen/issues/515)) ([#427](https://github.com/box/box-dotnet-sdk-gen/issues/427)) ([`d90faea`](https://github.com/box/box-dotnet-sdk-gen/commit/d90faea77650a37ce794a93c51bd9a8eb91f619c))
  * Use `targetFramework` when single .Net version is supported (box/box-codegen[#684](https://github.com/box/box-windows-sdk-v2/issues/684)) ([#438](https://github.com/box/box-dotnet-sdk-gen/issues/438)) ([`4e64174`](https://github.com/box/box-dotnet-sdk-gen/commit/4e64174c21c6f1dd2cef75f1f29ebe2ace92d852))

  ### New Features and Enhancements

  * Add find app item for shared link endpoint (box/box-openapi[#514](https://github.com/box/box-dotnet-sdk-gen/issues/514)) ([#426](https://github.com/box/box-dotnet-sdk-gen/issues/426)) ([`4dc5dc1`](https://github.com/box/box-dotnet-sdk-gen/commit/4dc5dc14e3c204c537180df166d07735ae1c4e40))
  * Add Integration Mappings Teams API (box/box-openapi[#517](https://github.com/box/box-dotnet-sdk-gen/issues/517)) ([#429](https://github.com/box/box-dotnet-sdk-gen/issues/429)) ([`92063c4`](https://github.com/box/box-dotnet-sdk-gen/commit/92063c435d7cb38a7eeca2e71f42e32b995a659a))
  * Expose token storage for authentication classes (box/box-codegen[#682](https://github.com/box/box-windows-sdk-v2/issues/682)) ([#435](https://github.com/box/box-dotnet-sdk-gen/issues/435)) ([`413058e`](https://github.com/box/box-dotnet-sdk-gen/commit/413058e78cb69c89be6a819c0e63f9457bd7f2f5))
</Update>

<Update label="2025-03-12">
  ## Integration mappings for Teams

  Use the [integration mappings](/reference/resources/integration-mapping-teams) feature for MS Teams to manage [where the content
  from Teams](https://support.box.com/hc/en-us/articles/360050737154-Assigning-a-Default-Box-Folder-to-a-Teams-Channel-or-Chat) channels and chats is stored in Box.

  * [List](/reference/get-integration-mappings-teams) all Teams integration mappings
  * [Create](/reference/post-integration-mappings-teams) a new Teams integration mapping
  * [Update](/reference/put-integration-mappings-teams-id) existing Teams integration mapping
  * [Delete](/reference/delete-integration-mappings-teams-id) Teams integration mapping

  Check the integration mappings for Teams API developer [guide](/guides/integration-mappings/teams-mappings/index) to learn more about this feature.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2025-03-12">
  ## Box Java SDK v4.15.3 released

  ### Bug Fixes

  * trim `content-length` header value ([#1297](https://github.com/box/box-java-sdk/issues/1297)) ([`fa11d14`](https://github.com/box/box-java-sdk/commit/fa11d141edf511eabc5f2398e55dc411d0cdcd31))
</Update>

<Update label="2025-03-11">
  ## Box TypeScript SDK Generated v1.13.2 released

  ### Bug Fixes

  * Fix `rollup` plugin output directory in Typescript (box/box-codegen[#678](https://github.com/box/box-typescript-sdk-gen/issues/678)) ([#543](https://github.com/box/box-typescript-sdk-gen/issues/543)) ([`f828d5e`](https://github.com/box/box-typescript-sdk-gen/commit/f828d5e7e3079c48590e9766f0dccd25ee1af9ca))
</Update>

<Update label="2025-03-07">
  ## Box TypeScript SDK Generated v1.13.1 released

  ### Bug Fixes

  * Split browser configuration in `package.json` for TypeScript (box/box-codegen[#672](https://github.com/box/box-typescript-sdk-gen/issues/672)) ([#538](https://github.com/box/box-typescript-sdk-gen/issues/538)) ([`ca7e291`](https://github.com/box/box-typescript-sdk-gen/commit/ca7e29180e450cbb346a76aadfdade1062559b1e))
</Update>

<Update label="2025-03-07">
  ## Box CLI v4.0.1 released

  ### Bug Fixes

  * Fix `configure:environments:set-current` command ([#568](https://github.com/box/boxcli/issues/568)) ([`dc0905f`](https://github.com/box/boxcli/commit/dc0905f7b85a32373e93ec7726afb261223e9fac))
</Update>

<Update label="2025-02-26">
  ## Box Java SDK v4.15.2 released

  ### Bug Fixes

  * Improve logging for API Request and API Response ([#1295](https://github.com/box/box-java-sdk/issues/1295)) ([`6eb1f57`](https://github.com/box/box-java-sdk/commit/6eb1f57a584571b46daa14d045a36bca382493fa))
</Update>

<Update label="2025-02-26">
  ## Box AI API - AWS Claude 3.7 Sonnet now available

  The list of [available AI models](https://developer.box.com/guides/box-ai/ai-models) has been recently updated with AWS Claude 3.7 Sonnet.

  Models offered in **Preview** mode have not been fully performance-tested at scale and are made available on an as-is basis. You may experience variability in model/output quality, availability, and accuracy.

  You can use the provided models to [override the default model](https://developer.box.com/guides/box-ai/ai-models) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-02-24">
  ## Box Java SDK v4.15.1 released

  ### Bug Fixes

  * Fix parsing content length header ([#1292](https://github.com/box/box-java-sdk/issues/1292)) ([`3bcf788`](https://github.com/box/box-java-sdk/commit/3bcf788dd9849305aa2cc85b8e5f88b35803ecb2))
</Update>

<Update label="2025-02-20">
  ## Box TypeScript SDK Generated v1.13.0 released

  ### New Features and Enhancements

  * Support AI Studio API (box/box-codegen[#626](https://github.com/box/box-typescript-sdk-gen/issues/626)) ([#520](https://github.com/box/box-typescript-sdk-gen/issues/520)) ([`949b856`](https://github.com/box/box-typescript-sdk-gen/commit/949b856ce1d77b1aa425b91b46440b46b383438a))
</Update>

<Update label="2025-02-20">
  ## Box Dotnet SDK Generated v1.8.0 released

  ### Bug Fixes

  * Do not retry HTTP request when `TaskCanceledException` is thrown (box/box-codegen[#665](https://github.com/box/box-windows-sdk-v2/issues/665)) ([#406](https://github.com/box/box-dotnet-sdk-gen/issues/406)) ([`1af0a6a`](https://github.com/box/box-dotnet-sdk-gen/commit/1af0a6aaf5f1e80f092ce506abe1cc01bf110bb8))

  ### New Features and Enhancements

  * Support AI Studio API (box/box-codegen[#626](https://github.com/box/box-windows-sdk-v2/issues/626)) ([#409](https://github.com/box/box-dotnet-sdk-gen/issues/409)) ([`9661450`](https://github.com/box/box-dotnet-sdk-gen/commit/966145021d4a1dd450cd199cc9ed3e9457f5a141))
</Update>

<Update label="2025-02-19">
  ## Box Java SDK v4.15.0 released

  ### New Features and Enhancements

  * Add `canNonOwnersViewCollaborators` flag to `BoxFolder` ([#1288](https://github.com/box/box-java-sdk/issues/1288)) ([`9119adc`](https://github.com/box/box-java-sdk/commit/9119adceae35e892e73ed61ed30cf82ad912960d))
  * Support `zstd` encoding for downloads ([#1287](https://github.com/box/box-java-sdk/issues/1287)) ([`0e3c4c0`](https://github.com/box/box-java-sdk/commit/0e3c4c07e65ef1887cd5c393e3daf98aeb50ee47))

  ### Bug Fixes

  * Fix AI dialogue history ([#1289](https://github.com/box/box-java-sdk/issues/1289)) ([`29b6519`](https://github.com/box/box-java-sdk/commit/29b651987a5cbeead4b129cab20970f983cb6889))
</Update>

<Update label="2025-02-18">
  ## Box AI Studio API

  We are excited to announce that Box AI Studio API is now available to all Enterprise Advanced customers.
  [Box AI Studio](https://support.box.com/hc/en-us/articles/37228079461267-Enabling-Box-AI-Studio-and-Managing-Agents) allows you to build and manage custom AI agents to
  best suit your business needs. For example, you can create an AI agent
  that acts as a compliance consultant, answering questions regarding customer
  documentation with specific compliance rules in mind.

  Box AI Studio API allows you to:

  * List all AI agents
  * Get AI agent details
  * Create a new AI agent
  * Update existing AI agent
  * Delete an AI agent

  Check the Box AI Studio API developer [guide](https://developer.box.com/guides/ai-studio/getting-started-ai-studio) to learn more about this feature and check the [API Reference](https://developer.box.com/reference/get-ai-agents/) for details.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://community.box.com/) for any help needed.
</Update>

<Update label="2025-02-12">
  ## Box Python SDK Generated v1.11.1 released

  ### Bug Fixes

  * Fix proxy usage (box/box-codegen[#662](https://github.com/box/box-python-sdk-gen/issues/662)) ([#476](https://github.com/box/box-python-sdk-gen/issues/476)) ([`e1d62ac`](https://github.com/box/box-python-sdk-gen/commit/e1d62ac5a8063bf37244329329100752c3a069af))
</Update>

<Update label="2025-02-06">
  ## Box TypeScript SDK Generated v1.12.0 released

  ### New Features and Enhancements

  * Add Box Sign shared requests (box/box-openapi[#504](https://github.com/box/box-typescript-sdk-gen/issues/504)) ([#491](https://github.com/box/box-typescript-sdk-gen/issues/491)) ([`e90255c`](https://github.com/box/box-typescript-sdk-gen/commit/e90255c5d97a7a1a10dd529b58426142c5c6f0d4))
  * feat: Add hubs support to `/ai/ask`. Replace type of `items` property from `AiItemBase[]` to `AiItemAsk[]` in the `AiAsk` interface (box/box-codegen[#656](https://github.com/box/box-typescript-sdk-gen/issues/656)) ([#507](https://github.com/box/box-typescript-sdk-gen/issues/507)) ([`9f29d8c`](https://github.com/box/box-typescript-sdk-gen/commit/9f29d8cb1f1d3b8c7625da1ddb9f2abd62d133f0))
  * Update `/ai/extract_structured` response schema (box/box-codegen[#641](https://github.com/box/box-typescript-sdk-gen/issues/641)) ([#498](https://github.com/box/box-typescript-sdk-gen/issues/498)) ([`502ac11`](https://github.com/box/box-typescript-sdk-gen/commit/502ac11a2ad4e56fceece0deb6a15dbfc8b429ff))
</Update>

<Update label="2025-02-06">
  ## Box Python SDK Generated v1.11.0 released

  ### Bug Fixes

  * Correct types of `paged` and `thumb` properties in File representation (box/box-openapi[#503](https://github.com/box/box-python-sdk-gen/issues/503)) ([#451](https://github.com/box/box-python-sdk-gen/issues/451)) ([`e818fa6`](https://github.com/box/box-python-sdk-gen/commit/e818fa6c9c80e61a293fc24ed6f1a15978681662))

  ### New Features and Enhancements

  * Add Box Sign shared requests (box/box-openapi[#504](https://github.com/box/box-python-sdk-gen/issues/504)) ([#453](https://github.com/box/box-python-sdk-gen/issues/453)) ([`3590918`](https://github.com/box/box-python-sdk-gen/commit/359091873d26111b82f000e7837553cc799f2433))
  * feat: Add hubs support to `/ai/ask`. Replace type of `items` parameter from `List[AiItemBase]` to `List[AiItemAsk]` in `create_ai_ask` method (box/box-openapi[#506](https://github.com/box/box-python-sdk-gen/issues/506)) ([#466](https://github.com/box/box-python-sdk-gen/issues/466)) ([`29f0364`](https://github.com/box/box-python-sdk-gen/commit/29f03649f3ec1471e859609d2b8bd77ad5d09106))
  * Update `/ai/extract_structured` response schema (box/box-codegen[#641](https://github.com/box/box-python-sdk-gen/issues/641)) ([#459](https://github.com/box/box-python-sdk-gen/issues/459)) ([`7c73cea`](https://github.com/box/box-python-sdk-gen/commit/7c73ceaa8888332b23bca4d6b64ef4999f942940))
</Update>

<Update label="2025-02-06">
  ## Box Dotnet SDK Generated v1.7.0 released

  ### Bug Fixes

  * Correct types of `paged` and `thumb` properties in File representation (box/box-openapi[#503](https://github.com/box/box-dotnet-sdk-gen/issues/503)) ([#383](https://github.com/box/box-dotnet-sdk-gen/issues/383)) ([`d6995ad`](https://github.com/box/box-dotnet-sdk-gen/commit/d6995ad8ffa4f2cceb8195ffbfb6606f934a671f))
  * Prevent `Authentication` header from being passed during cross-origin redirects (box/box-codegen[#648](https://github.com/box/box-windows-sdk-v2/issues/648)) ([#382](https://github.com/box/box-dotnet-sdk-gen/issues/382)) ([`a64d373`](https://github.com/box/box-dotnet-sdk-gen/commit/a64d373a935cd2a8e6f72184b8dc129a973e9d45))

  ### New Features and Enhancements

  * Add Box Sign shared requests (box/box-openapi[#504](https://github.com/box/box-dotnet-sdk-gen/issues/504)) ([#384](https://github.com/box/box-dotnet-sdk-gen/issues/384)) ([`d563886`](https://github.com/box/box-dotnet-sdk-gen/commit/d563886f2a2f48a20df13600f9c25ff95198a56f))
  * feat: Add hubs support to /ai/ask. Replace type of `Items` property from `IReadOnlyList<AiItemBase>` to `IReadOnlyList<AiItemAsk>` in the `AiAsk` class (box/box-codegen[#656](https://github.com/box/box-windows-sdk-v2/issues/656)) ([#397](https://github.com/box/box-dotnet-sdk-gen/issues/397)) ([`32b6d03`](https://github.com/box/box-dotnet-sdk-gen/commit/32b6d03aba97c18a8901efe98fc60c74e10197ce))
  * Update `/ai/extract_structured` response schema (box/box-codegen[#641](https://github.com/box/box-windows-sdk-v2/issues/641)) ([#391](https://github.com/box/box-dotnet-sdk-gen/issues/391)) ([`5f79a03`](https://github.com/box/box-dotnet-sdk-gen/commit/5f79a03453b9339a26eb130113d8f55748f0d912))
</Update>

<Update label="2025-01-28">
  ## Box CLI v4.0.0 released

  ### ⚠ BREAKING CHANGES

  * Drop support old Node version and integrate typescript SDK ([#548](https://github.com/box/boxcli/issues/548))

  ### New Features and Enhancements

  * Drop support old Node version and integrate typescript SDK ([#548](https://github.com/box/boxcli/issues/548)) ([`22179ec`](https://github.com/box/boxcli/commit/22179ecfc68b8dd315339ac204a7274d712d5a8e))
  * Incognito browser option for box login ([#561](https://github.com/box/boxcli/issues/561)) ([`a666766`](https://github.com/box/boxcli/commit/a6667664d6b43fd80de9e57482b0f4138efcd6cf))
  * Replace `@oclif/command` to `@oclif/core` library ([#553](https://github.com/box/boxcli/issues/553)) ([`aed470b`](https://github.com/box/boxcli/commit/aed470b22d28ed19040b4417e3143f3323b9a916))

  ### Bug Fixes

  * Respect using environment `defaultAsUserId` for CCG Auth and OAuth ([#554](https://github.com/box/boxcli/issues/554)) ([`b3a691e`](https://github.com/box/boxcli/commit/b3a691e8c886f7bb3a25ae8f7986f284a695f046))
</Update>

<Update label="2025-01-22">
  ## Box Java SDK v4.14.0 released

  ### New Features and Enhancements

  * Support downloading file from shared link ([#1282](https://github.com/box/box-java-sdk/issues/1282)) ([`9b7f28b`](https://github.com/box/box-java-sdk/commit/9b7f28b0288977513b0db3ed4f800647545e1f2c))

  ### Bug Fixes

  * Remove sensitive data when `BoxAPIException` logs request ([#1284](https://github.com/box/box-java-sdk/issues/1284)) ([`f1e226f`](https://github.com/box/box-java-sdk/commit/f1e226f710c301202acff067ef34687ddbb57b7b))
  * Support creating ongoing Legal Hold policy with start date ([#1281](https://github.com/box/box-java-sdk/issues/1281)) ([`d9564e2`](https://github.com/box/box-java-sdk/commit/d9564e2e86ea110af933ca3dd0f728111d7140ae))
</Update>

<Update label="2024-01-13">
  ## Box Doc Gen

  We are excited to announce that [Box Doc Gen](/guides/docgen/docgen-getting-started/) is now available to all **Enterprise Advanced** customers.

  [Box Doc Gen](https://developer.box.com/guides/docgen) allows you to generate various business documents based on Box Doc Gen templates uploaded to Box, with data fields that can be dynamically filled using Box Doc Gen API.

  Box Doc Gen functionality allows you to:

  * [Mark files as Doc Gen templates](/guides/docgen/mark-template/).
  * [Generate documents](/guides/docgen/generate-document/).
  * Check status of the [Box Doc Gen jobs](/guides/docgen/docgen-jobs/)

  Check the [Box Doc Gen developer guides](https://developer.box.com/guides/docgen) to learn more about Box Doc Gen and check the [API Reference](/reference/v2025.0/post-docgen-templates) for Box Doc Gen API details.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2025-01-17">
  ## Google PaLM deprecation and removal

  `Google Pathways Language Models (PaLM)` are being deprecated by `Google`.

  As a result, the following models will be removed from Box AI on 2025-01-17

  * `text_bison`
  * `text_bison_32k`
  * `text_unicorn`
  * `google_text_embedding_gecko*`

  If you are using one of these models via agent override, check our [list of
  supported models](https://developer.box.com/guides/box-ai/ai-agents/) here.
</Update>


# 2026
Source: https://developer.box.com/changelog/2026

Box Platform changelog: API, SDK, and product updates from 2026.

[Subscribe to the changelog with RSS](/changelog/2026/rss.xml) to get new APIs, SDK releases, and platform updates delivered to your feed reader.

<Update label="2026-10-07">
  ## Box Python SDK `v10.17.1` released

  ### Bug Fixes

  * encode text streams as UTF-8 in `MultipartStream` uploads ([box/box-codegen#995](https://github.com/box/box-codegen/issues/995)) ([box-python-sdk#1607](https://github.com/box/box-python-sdk/issues/1607)) ([`2788783`](https://github.com/box/box-python-sdk/commit/2788783dd536cfc5e1abda540fbdd92991c5f11a))

  ## Box Python SDK `v4.18.0` released

  ### Bug Fixes

  * **boxsdkgen:** encode text streams as UTF-8 in `MultipartStream` uploads ([box/box-codegen#995](https://github.com/box/box-codegen/issues/995)) ([box-python-sdk#1608](https://github.com/box/box-python-sdk/issues/1608)) ([`1e34853`](https://github.com/box/box-python-sdk/commit/1e34853fdb48a1133e615e94ca975e263ab9ded7))

  ### New Features and Enhancements

  * **boxsdk:** Replace `requests-toolbelt` with streaming `MultipartStream` encoder ([box-python-sdk#1606](https://github.com/box/box-python-sdk/issues/1606)) ([`685e9fc`](https://github.com/box/box-python-sdk/commit/685e9fc63ebf4b06ce99bed179af758d2160dda0))
</Update>

<Update label="2026-10-05">
  ## Experience Cloud Toolkit for Salesforce

  The [Salesforce Developer Toolkit](/guides/tooling/salesforce-toolkit) now includes the [Experience Cloud Toolkit](/guides/tooling/salesforce-toolkit/experience-cloud-toolkit/experience-cloud-toolkit-global-methods). Its global methods let you manage Box App Users for Salesforce Experience Cloud users:

  * Create or reactivate a Box App User for the current or a specific Salesforce user.
  * Deactivate a Box App User.
  * Look up an existing Box App User linked to a Salesforce user.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-10-01">
  ## Box iOS SDK `6.17.0` released

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`47724eb`](https://github.com/box/box-ios-sdk/commit/47724ebb1c065e90f5bb298e3f10d8292b866eac))

  ### Bug Fixes

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`47724eb`](https://github.com/box/box-ios-sdk/commit/47724ebb1c065e90f5bb298e3f10d8292b866eac))
</Update>

<Update label="2026-10-01">
  ## Box Java SDK `v10.19.0` released

  ### ⚠ BREAKING CHANGES

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`c6b93be`](https://github.com/box/box-java-sdk/commit/c6b93bee255b7358421cbf786891cff551aef807))

  ### Bug Fixes

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`c6b93be`](https://github.com/box/box-java-sdk/commit/c6b93bee255b7358421cbf786891cff551aef807))
</Update>

<Update label="2026-10-01">
  ## Box Java SDK `v5.18.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`28640c7`](https://github.com/box/box-java-sdk/commit/28640c7d6e3efe2314bc21a6b816c6c4e3bdacae))

  ### Bug Fixes

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`28640c7`](https://github.com/box/box-java-sdk/commit/28640c7d6e3efe2314bc21a6b816c6c4e3bdacae))
</Update>

<Update label="2026-10-01">
  ## Box Windows SDK `v10.19.0` released

  ### BREAKING CHANGES

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`0403b76`](https://github.com/box/box-windows-sdk-v2/commit/0403b76e32e979e4f5a0d5328134b60797f45a57))

  ### Bug Fixes

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`0403b76`](https://github.com/box/box-windows-sdk-v2/commit/0403b76e32e979e4f5a0d5328134b60797f45a57))
</Update>

<Update label="2026-10-01">
  ## Box Node SDK `v10.17.0` released

  ### ⚠ BREAKING CHANGES

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`3f31be2`](https://github.com/box/box-node-sdk/commit/3f31be2c9ae3e9379df08e2f5de5259442ad7a49))

  ### Bug Fixes

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`3f31be2`](https://github.com/box/box-node-sdk/commit/3f31be2c9ae3e9379df08e2f5de5259442ad7a49))
</Update>

<Update label="2026-10-01">
  ## Box Node SDK `v4.17.0` released

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`10521f5`](https://github.com/box/box-node-sdk/commit/10521f509b61d4b616d7af50735b31bf4ce33fc8))

  ### Bug Fixes

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`10521f5`](https://github.com/box/box-node-sdk/commit/10521f509b61d4b616d7af50735b31bf4ce33fc8))
</Update>

<Update label="2026-10-01">
  ## Box Windows SDK `v6.19.0` released

  ### BREAKING CHANGES

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`e4f7d0a`](https://github.com/box/box-windows-sdk-v2/commit/e4f7d0a76414a0315ec840263c935277273b2c9b))

  ### Bug Fixes

  * **boxsdkgen:** use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`e4f7d0a`](https://github.com/box/box-windows-sdk-v2/commit/e4f7d0a76414a0315ec840263c935277273b2c9b))
</Update>

<Update label="2026-10-01">
  ## Box AI API — new AI models available

  The list of [available AI models](/guides/box-ai/ai-models) has been updated with the following core models:

  * [OpenAI GPT-6.1 Sol](/guides/box-ai/ai-models/openai-gpt-6-1-sol-model-card)
  * [AWS Claude Sonnet 5.5](/guides/box-ai/ai-models/aws-claude-sonnet-5-5-model-card)

  You can use the provided models to [override the default model](/guides/box-ai/ai-agents/ai-agent-overrides) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](/guides/box-ai) and [API reference](/reference/post-ai-ask).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-10-01">
  ## Box Python SDK `v10.17.0` released

  ### ⚠ BREAKING CHANGES

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`89e7d0b`](https://github.com/box/box-python-sdk/commit/89e7d0bff99da4c54b6cd59cbedd3897caf91327))

  ### New Features and Enhancements

  * replace `MultipartEncoder` with streaming `MultipartStream` for uploads ([box/box-codegen#994](https://github.com/box/box-codegen/issues/994)) ([`8a5d896`](https://github.com/box/box-python-sdk/commit/8a5d8963888aeb500a9f03826c85c1681950e4dd))

  ### Bug Fixes

  * use `FileMini`/`FolderMini`/`WebLinkMini` in `CollaborationItem` ([box/box-openapi#619](https://github.com/box/box-openapi/issues/619)) ([`89e7d0b`](https://github.com/box/box-python-sdk/commit/89e7d0bff99da4c54b6cd59cbedd3897caf91327))
</Update>

<Update label="2026-09-25">
  ## Box AI API — new AI models available

  The list of [available AI models](/guides/box-ai/ai-models) has been updated with the following core models:

  * [OpenAI GPT-6 Sol](/guides/box-ai/ai-models/openai-gpt-6-sol-model-card)
  * [OpenAI GPT-6 Luna](/guides/box-ai/ai-models/openai-gpt-6-luna-model-card)

  The following customer-enabled models have also been added:

  * [Meta Muse Spark 1.3](/guides/box-ai/ai-models/meta-muse-spark-1-3-model-card) (Beta)
  * [Meta Muse Spark 1.2](/guides/box-ai/ai-models/meta-muse-spark-1-2-model-card) (Beta)

  <Note>
    Models offered in **Beta** mode have not been fully performance-tested at scale and are provided on an as-is basis.
  </Note>

  You can use the provided models to [override the default model](/guides/box-ai/ai-agents/ai-agent-overrides) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](/guides/box-ai) and [API reference](/reference/post-ai-ask).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-09-24">
  ## Box Embed updates

  [Box Embed](/guides/embed/box-embed#parameters) has the following updates:

  * The new `hidePreviewCloseButton` parameter lets you hide or show navigation controls in Box Preview.
  * The `uxLite` parameter now shows the simplified content preview (Preview Light) for all files and Box Notes, not only shared files.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-09-24">
  ## Introducing Box Doc Split

  [Box Doc Split](/guides/docgen/doc-split) breaks a multi-page PDF into smaller sub-documents and saves them to a Box folder of your choice.

  Box Doc Split supports two split types:

  * [Manual split](/guides/docgen/manual-split) divides the PDF using page ranges you define. Results are fixed, so use it when you already know the page numbers.
  * [Smart split](/guides/docgen/smart-split) uses a natural language prompt to decide how to group pages, for example at QR code separator pages or around signature pages. A smart split consumes 1 AI unit for every 4 pages processed.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-09-23">
  ## Box AI API — new AI model available

  The list of [available AI models](/guides/box-ai/ai-models) has been updated with a new core model, [AWS Claude Opus 5.5](/guides/box-ai/ai-models/aws-claude-opus-5-5-model-card).

  You can use the provided models to [override the default model](/guides/box-ai/ai-agents/ai-agent-overrides) used in the AI agent configuration.
  For further details on Box AI API, see the [guides](/guides/box-ai) and [API reference](/reference/post-ai-ask).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-09-11">
  ## Box AI API — new AI models available

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been updated with the following core model:

  * <Link href="/guides/box-ai/ai-models/openai-gpt-6-astra-model-card">OpenAI GPT-6 Astra</Link>

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-09-09">
  ## Box Windows SDK `v10.17.0` released

  ### New Features and Enhancements

  * Add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-windows-sdk-v2#1627](https://github.com/box/box-windows-sdk-v2/issues/1627)) ([`ba8a130`](https://github.com/box/box-windows-sdk-v2/commit/ba8a130f3900d75fa44f1d3bd594b4f9fc0e0b7e))
  * Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-windows-sdk-v2#1630](https://github.com/box/box-windows-sdk-v2/issues/1630)) ([`339b2c6`](https://github.com/box/box-windows-sdk-v2/commit/339b2c6a57fcc2d04d957aed5bb6cd5217fe1fb8))
</Update>

<Update label="2026-09-09">
  ## Box Windows SDK `v6.17.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-windows-sdk-v2#1626](https://github.com/box/box-windows-sdk-v2/issues/1626)) ([`0615145`](https://github.com/box/box-windows-sdk-v2/commit/0615145a335e3c9667a145495f929e3ced8ff1dc))
  * **boxsdkgen:** Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-windows-sdk-v2#1628](https://github.com/box/box-windows-sdk-v2/issues/1628)) ([`b4aea5e`](https://github.com/box/box-windows-sdk-v2/commit/b4aea5e8d579718d066b85210282b946e19e202d))
</Update>

<Update label="2026-09-09">
  ## Box Python SDK `v10.15.0` released

  ### New Features and Enhancements

  * Add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-python-sdk#1559](https://github.com/box/box-python-sdk/issues/1559)) ([`9b570c0`](https://github.com/box/box-python-sdk/commit/9b570c04998d6a01391a9cd4a042dea427ebb780))
  * Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-python-sdk#1562](https://github.com/box/box-python-sdk/issues/1562)) ([`2cfdc80`](https://github.com/box/box-python-sdk/commit/2cfdc806a5f66d1ed6f96804551fdae3b9610053))
</Update>

<Update label="2026-09-09">
  ## Box Python SDK `v4.15.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-python-sdk#1558](https://github.com/box/box-python-sdk/issues/1558)) ([`6aa5cda`](https://github.com/box/box-python-sdk/commit/6aa5cda955b9bbf6dc1cb1223a11d49575940ab8))
  * **boxsdkgen:** Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-python-sdk#1560](https://github.com/box/box-python-sdk/issues/1560)) ([`d660d35`](https://github.com/box/box-python-sdk/commit/d660d3589cc46707b81615adde55d99d2fcb5375))
</Update>

<Update label="2026-09-09">
  ## Box Node SDK `v10.15.0` released

  ### Bug Fixes

  * Fix type declarations that break `tsc` under `Node-only` `tsconfig` ([box/box-codegen#983](https://github.com/box/box-codegen/issues/983)) ([box-node-sdk#1602](https://github.com/box/box-node-sdk/issues/1602)) ([`874246d`](https://github.com/box/box-node-sdk/commit/874246d84713b1aa48b65305bf8c1fdc14496e04))
  * Stop double-JSON-encoding error fields in Box API errors ([box/box-codegen#985](https://github.com/box/box-codegen/issues/985)) ([box-node-sdk#1608](https://github.com/box/box-node-sdk/issues/1608)) ([`a517b3d`](https://github.com/box/box-node-sdk/commit/a517b3d019085695ad73042ed34983a969fdd779))

  ### New Features and Enhancements

  * Add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-node-sdk#1598](https://github.com/box/box-node-sdk/issues/1598)) ([`be0d1ff`](https://github.com/box/box-node-sdk/commit/be0d1ff043075f7edd7b54f0c6cfaafce6b8cf4f))
  * Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-node-sdk#1601](https://github.com/box/box-node-sdk/issues/1601)) ([`f28a496`](https://github.com/box/box-node-sdk/commit/f28a496f0843d666c2d5430029df5cfb4472addf))
</Update>

<Update label="2026-09-09">
  ## Box Node SDK `v4.15.0` released

  ### Bug Fixes

  * **boxsdkgen:** Fix type declarations that break `tsc` under `Node-only` `tsconfig` ([box/box-codegen#983](https://github.com/box/box-codegen/issues/983)) ([box-node-sdk#1600](https://github.com/box/box-node-sdk/issues/1600)) ([`73b5b87`](https://github.com/box/box-node-sdk/commit/73b5b874a9dd3c7c4dac8ee741b65d3219e41d87))
  * **boxsdkgen:** Stop double-JSON-encoding error fields in Box API errors ([box/box-codegen#985](https://github.com/box/box-codegen/issues/985)) ([box-node-sdk#1609](https://github.com/box/box-node-sdk/issues/1609)) ([`61970fc`](https://github.com/box/box-node-sdk/commit/61970fc7e6a0e7867255640492f5747a04ace306))

  ### New Features and Enhancements

  * **boxsdkgen:** Add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-node-sdk#1597](https://github.com/box/box-node-sdk/issues/1597)) ([`195b856`](https://github.com/box/box-node-sdk/commit/195b856568e6018a928db84e970ebe6629ac3d67))
  * **boxsdkgen:** Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-node-sdk#1599](https://github.com/box/box-node-sdk/issues/1599)) ([`80f8130`](https://github.com/box/box-node-sdk/commit/80f81309de05668518cc804ff799ac257266cf02))
</Update>

<Update label="2026-09-09">
  ## Box Java SDK `v10.17.0` released

  ### New Features and Enhancements

  * Add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-java-sdk#1976](https://github.com/box/box-java-sdk/issues/1976)) ([`7312c51`](https://github.com/box/box-java-sdk/commit/7312c51263f4c62efb1f6072a4f165b5919419ba))
  * Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-java-sdk#1979](https://github.com/box/box-java-sdk/issues/1979)) ([`6eb78be`](https://github.com/box/box-java-sdk/commit/6eb78beffbee2c2d400a04f12215cfd8d4d1727e))
</Update>

<Update label="2026-09-09">
  ## Box iOS SDK `10.15.0` released

  ### New Features and Enhancements

  * Add Japanese ZIP code validation to sign request ([box/box-openapi#615](https://github.com/box/box-openapi/issues/615)) ([box-ios-sdk#1631](https://github.com/box/box-ios-sdk/issues/1631)) ([`81df573`](https://github.com/box/box-ios-sdk/commit/81df573ce1fc4716a5705bc665ba6f7ccc2071cd))
  * Support chunk upload session plan API ([box/box-openapi#616](https://github.com/box/box-openapi/issues/616)) ([box-ios-sdk#1634](https://github.com/box/box-ios-sdk/issues/1634)) ([`02101c3`](https://github.com/box/box-ios-sdk/commit/02101c361ad13cfc69f0017aa535c99f8c0d161f))
</Update>

<Update label="2026-09-09">
  ## Box iOS SDK `10.13.0` released

  ### Bug Fixes

  * Strip Authorization header on cross-host redirects in Swift ([box/box-codegen#964](https://github.com/box/box-codegen/issues/964)) ([box-ios-sdk#1560](https://github.com/box/box-ios-sdk/issues/1560)) ([`b87cc65`](https://github.com/box/box-ios-sdk/commit/b87cc65f4de1ba978c23b0ae6922fe6662a5c9dc))

  ### New Features and Enhancements

  * Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-ios-sdk#1569](https://github.com/box/box-ios-sdk/issues/1569)) ([`11c5a71`](https://github.com/box/box-ios-sdk/commit/11c5a71ca135ea8bffb9e9ad952a6cb9e33138f9))
  * Set up common default timeout ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-ios-sdk#1577](https://github.com/box/box-ios-sdk/issues/1577)) ([`c20322d`](https://github.com/box/box-ios-sdk/commit/c20322dcb4ec791f99e6d1d4b5f1905425e117db))
</Update>

<Update label="2026-09-07">
  ## Box AI API — new AI models available

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been updated with the following core models:

  * <Link href="/guides/box-ai/ai-models/google-gemini-3-8-flash-model-card">Google Gemini 3.8 Flash</Link>
  * <Link href="/guides/box-ai/ai-models/google-gemini-3-7-flash-model-card">Google Gemini 3.7 Flash</Link>

  The following customer-enabled model has also been added:

  * <Link href="/guides/box-ai/ai-models/aws-claude-fable-5-1-model-card">AWS Claude Fable 5.1</Link> (Beta)

  <Note>
    Models offered in **Beta** mode have not been fully performance-tested at scale and are provided on an as-is basis.
  </Note>

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-09-02">
  ## Box Java SDK `v10.16.2` released

  ### Bug Fixes

  * bump `bouncyCastle` version ([box/box-codegen#982](https://github.com/box/box-codegen/issues/982)) ([box-java-sdk#1972](https://github.com/box/box-java-sdk/issues/1972)) ([`6c9877b`](https://github.com/box/box-java-sdk/commit/6c9877b15a1ad0449c117bdbe3e5e141bd33635b))
</Update>

<Update label="2026-08-26">
  ## Box Java SDK `v5.15.1` released

  ### Bug Fixes

  * **boxsdkgen:** avoid null chunk when file size is a multiple of part size ([box/box-codegen#980](https://github.com/box/box-codegen/issues/980)) ([box-java-sdk#1966](https://github.com/box/box-java-sdk/issues/1966)) ([`d737c81`](https://github.com/box/box-java-sdk/commit/d737c810ef04781738537c77060a720452ce53ba))
</Update>

<Update label="2026-08-26">
  ## Box Java SDK `v10.16.1` released

  ### Bug Fixes

  * Avoid null chunk when file size is a multiple of part size ([box/box-codegen#980](https://github.com/box/box-codegen/issues/980)) ([box-java-sdk#1967](https://github.com/box/box-java-sdk/issues/1967)) ([`f71a2c1`](https://github.com/box/box-java-sdk/commit/f71a2c1e836b99d3a7d9f96b320290378f7b99c6)).
</Update>

<Update label="2026-08-05">
  ## Box Windows SDK `v6.16.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** add `is_collaborated_content_available_when_owner_inactive` property ([box/box-openapi#613](https://github.com/box/box-openapi/issues/613)) ([box-windows-sdk-v2#1604](https://github.com/box/box-windows-sdk-v2/issues/1604)) ([`1415ec9`](https://github.com/box/box-windows-sdk-v2/commit/1415ec941a73b04ac822982f1533dfe0f1003860))
  * **boxsdkgen:** Added two missing event types ([box/box-openapi#611](https://github.com/box/box-openapi/issues/611)) ([box-windows-sdk-v2#1598](https://github.com/box/box-windows-sdk-v2/issues/1598)) ([`5d177f0`](https://github.com/box/box-windows-sdk-v2/commit/5d177f09d57ddbe22cf56e6a7ed2bb3b2750d307))
  * **boxsdkgen:** Support query APIs ([box/box-openapi#610](https://github.com/box/box-openapi/issues/610))  ([box-windows-sdk-v2#1596](https://github.com/box/box-windows-sdk-v2/issues/1596)) ([`5232dfd`](https://github.com/box/box-windows-sdk-v2/commit/5232dfd0436045034595f1205e27e36fc21b5908))
</Update>

<Update label="2026-08-05">
  ## Box Python SDK `v10.14.0` released

  ### New Features and Enhancements

  * add `is_collaborated_content_available_when_owner_inactive` property ([box/box-openapi#613](https://github.com/box/box-openapi/issues/613)) ([box-python-sdk#1537](https://github.com/box/box-python-sdk/issues/1537)) ([`9d4542f`](https://github.com/box/box-python-sdk/commit/9d4542f1ca9ef8da5b273705e670c19e89d5ea8b))
  * Added two missing event types ([box/box-openapi#611](https://github.com/box/box-openapi/issues/611)) ([box-python-sdk#1531](https://github.com/box/box-python-sdk/issues/1531)) ([`94120f3`](https://github.com/box/box-python-sdk/commit/94120f3fa866c2521db42d62dc7471030c023871))
  * Support query APIs ([box/box-openapi#610](https://github.com/box/box-openapi/issues/610)) ([box-python-sdk#1529](https://github.com/box/box-python-sdk/issues/1529)) ([`1f18e93`](https://github.com/box/box-python-sdk/commit/1f18e931e8fcc5b13429acb9a2669e7bd9610c10))
</Update>

<Update label="2026-08-05">
  ## Box Node SDK `v4.14.0` released

  ### Bug Fixes

  * **boxsdkgen:** Added two missing event types ([box/box-openapi#611](https://github.com/box/box-openapi/issues/611)) ([box-node-sdk#1565](https://github.com/box/box-node-sdk/issues/1565)) ([`24650c0`](https://github.com/box/box-node-sdk/commit/24650c02bad20615fe6dc98ac57b1ac96c0fa337))

  ### New Features and Enhancements

  * **boxsdkgen:** add `is_collaborated_content_available_when_owner_inactive` property ([box/box-openapi#613](https://github.com/box/box-openapi/issues/613)) ([box-node-sdk#1571](https://github.com/box/box-node-sdk/issues/1571)) ([`b8dd5fa`](https://github.com/box/box-node-sdk/commit/b8dd5fae2a6f5e04716a3d38acbc599dc70d2a9d))
  * **boxsdkgen:** export error types from the package root ([box/box-codegen#976](https://github.com/box/box-codegen/issues/976)) ([box-node-sdk#1569](https://github.com/box/box-node-sdk/issues/1569)) ([`4d9d485`](https://github.com/box/box-node-sdk/commit/4d9d4850817c7d8bc75ade54314dfeb4b476f135))
  * **boxsdkgen:** Support query APIs ([box/box-openapi#610](https://github.com/box/box-openapi/issues/610)) ([box-node-sdk#1562](https://github.com/box/box-node-sdk/issues/1562)) ([`493563f`](https://github.com/box/box-node-sdk/commit/493563ff1fbab11f0cae5460434f5933343def20))
</Update>

<Update label="2026-08-05">
  ## Box Java SDK `v5.15.0` released

  ### Bug Fixes

  * **boxsdkgen:** Fix broken link in Readme ([box-java-sdk#1931](https://github.com/box/box-java-sdk/issues/1931)) ([`6a88eaf`](https://github.com/box/box-java-sdk/commit/6a88eaf6dce2b6e8ca343f42557a927c5744b75d))

  ### New Features and Enhancements

  * **boxsdkgen:** add `is_collaborated_content_available_when_owner_inactive` property ([box/box-openapi#613](https://github.com/box/box-openapi/issues/613)) ([box-java-sdk#1945](https://github.com/box/box-java-sdk/issues/1945)) ([`e02e6f6`](https://github.com/box/box-java-sdk/commit/e02e6f6f3ed112a19a90048aa87354539cecd2b9))
  * **boxsdkgen:** Added two missing event types ([box/box-openapi#611](https://github.com/box/box-openapi/issues/611)) ([box-java-sdk#1939](https://github.com/box/box-java-sdk/issues/1939)) ([`dfc3e67`](https://github.com/box/box-java-sdk/commit/dfc3e67f9df97dcc065a27ca5bb9adfb7a434044))
  * **boxsdkgen:** Support query APIs ([box/box-openapi#610](https://github.com/box/box-openapi/issues/610))  ([box-java-sdk#1937](https://github.com/box/box-java-sdk/issues/1937)) ([`102e966`](https://github.com/box/box-java-sdk/commit/102e966fdedaf95ea1abeb0060918676d84ffee3))
</Update>

<Update label="2026-08-05">
  ## Box iOS SDK `10.14.0` released

  ### New Features and Enhancements

  * add `is_collaborated_content_available_when_owner_inactive` property ([box/box-openapi#613](https://github.com/box/box-openapi/issues/613)) ([box-ios-sdk#1606](https://github.com/box/box-ios-sdk/issues/1606)) ([`fd1a20c`](https://github.com/box/box-ios-sdk/commit/fd1a20c0c80f1b56318b76a77483965cdea8a1bf))
  * Added two missing event types ([box/box-openapi#611](https://github.com/box/box-openapi/issues/611)) ([box-ios-sdk#1600](https://github.com/box/box-ios-sdk/issues/1600)) ([`73f7b98`](https://github.com/box/box-ios-sdk/commit/73f7b985e3481552ba49ffbb83a5d1b9d2d4d43e))
  * Support query APIs ([box/box-openapi#610](https://github.com/box/box-openapi/issues/610)) ([box-ios-sdk#1597](https://github.com/box/box-ios-sdk/issues/1597)) ([`0bb4da5`](https://github.com/box/box-ios-sdk/commit/0bb4da52ab6758309c563a8289bb029db8ffb28b))
</Update>

<Update label="2026-08-05">
  ## Box iOS SDK `6.14.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** add `is_collaborated_content_available_when_owner_inactive` property ([box/box-openapi#613](https://github.com/box/box-openapi/issues/613)) ([box-ios-sdk#1605](https://github.com/box/box-ios-sdk/issues/1605)) ([`5227664`](https://github.com/box/box-ios-sdk/commit/522766457f6fe721ff230e6bbd1ce20ced7a6f80))
  * **boxsdkgen:** Added two missing event types ([box/box-openapi#611](https://github.com/box/box-openapi/issues/611)) ([box-ios-sdk#1599](https://github.com/box/box-ios-sdk/issues/1599)) ([`8571fc9`](https://github.com/box/box-ios-sdk/commit/8571fc998637f7e42470407194c4e43ee5ded5a5))
  * **boxsdkgen:** Support query APIs ([box/box-openapi#610](https://github.com/box/box-openapi/issues/610)) ([box-ios-sdk#1596](https://github.com/box/box-ios-sdk/issues/1596)) ([`ddcbefd`](https://github.com/box/box-ios-sdk/commit/ddcbefd059594ef6eaa5b3c6794e419bd21d15d1))
</Update>

<Update label="2026-07-29">
  ## Box AI API — new AI models available

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been updated with the following core models:

  * <Link href="/guides/box-ai/ai-models/aws-claude-opus-5-model-card">AWS Claude Opus 5</Link>
  * <Link href="/guides/box-ai/ai-models/google-gemini-3-5-flash-lite-model-card">Google Gemini 3.5 Flash Lite</Link>

  The following customer-enabled model has also been added:

  * <Link href="/guides/box-ai/ai-models/google-gemini-3-6-flash-model-card">Google Gemini 3.6 Flash</Link>

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-07-23">
  ## Box Query and Query Insights released

  We introduced two new APIs, [Box query](/guides/metadata/box-query) and [query insights](/guides/metadata/insights).

  With [Box query API](/reference/v2026.0/query-resources#query-results), you can filter and sort results using metadata templates and item fields, building more detailed queries.

  With [query insights API](/reference/v2026.0/query-resources#query-insights), you can get insights into the usage of a query.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-07-14">
  ## New automated response action for Shield Ransomware Activity alert

  Along with the release of Ransomware Activity: Automated Remediation in Box Shield Pro, the `rule_response_action` parameter is now returned for the [Ransomware Activity alert event](/guides/events/event-triggers/shield-alert-events#ransomware-activity-alert).

  Previously, `rule_response_action` was always `null` for Ransomware Activity alerts. It now returns a `terminate_sessions` field that reflects whether Box Shield automatically terminated the target user's sessions when the alert was created.

  The value depends on the **Terminate Target User Sessions** rule setting in the Admin Console, which is off by default.

  * If enabled, `terminate_sessions` is `true` when the alert is triggered.
  * If disabled, `terminate_sessions` is `false` when the alert is triggered.

  For all other Shield alerts (**Anomalous Download**, **Malicious Content**, **Suspicious Session**), the `rule_response_action` parameter remains `null`.

  For additional information, see the [Shield Alert Events guide](/guides/events/event-triggers/shield-alert-events#ransomware-activity-alert).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-07-17">
  ## Box Node SDK `v10.13.0` released

  ### Bug Fixes

  * Define TypeScript SDK `tsconfig` roots ([box/box-codegen#970](https://github.com/box/box-codegen/issues/970)) ([box-node-sdk#1538](https://github.com/box/box-node-sdk/issues/1538)) ([`2848a20`](https://github.com/box/box-node-sdk/commit/2848a2042be615c782cc8c79ea2cde432a488b77))

  ### New Features and Enhancements

  * Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-node-sdk#1528](https://github.com/box/box-node-sdk/issues/1528)) ([`41fc72e`](https://github.com/box/box-node-sdk/commit/41fc72eebc0dcd3de31ed54dbf9ba2ea4d6ec7c2))
  * Rename `connectionTimeout` in typescript to `responseHeadersTimeout` and raise default to 60 seconds ([box/box-codegen#973](https://github.com/box/box-codegen/issues/973)) ([box-node-sdk#1555](https://github.com/box/box-node-sdk/issues/1555)) ([`189073b`](https://github.com/box/box-node-sdk/commit/189073b8632b9d494274c28b6e805338651bea85))
  * Setup common default timeout ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-node-sdk#1534](https://github.com/box/box-node-sdk/issues/1534)) ([`5eb3c68`](https://github.com/box/box-node-sdk/commit/5eb3c68eae4b156c85fb6402ec669836ba8fe438))
</Update>

<Update label="2026-07-16">
  ## Box AI API — two Google Gemini 2.0 models retired

  The following AI models are retired and no longer available in Box AI.

  * `google__gemini_2_0_flash_001` (Gemini 2.0 Flash)
  * `google__gemini_2_0_flash_lite_preview` (Gemini 2.0 Flash Lite)

  If you are using one of these models through agent override, switch to a [supported model](https://developer.box.com/guides/box-ai/ai-models/). See the [retired models](https://developer.box.com/guides/box-ai/ai-models/#retired-models) section for the full list.

  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-07-15">
  ## Box Java SDK `v10.15.2` released

  ### Bug Fixes

  * Fix broken readme link ([box/box-codegen#974](https://github.com/box/box-codegen/issues/974)) ([box-java-sdk#1929](https://github.com/box/box-java-sdk/issues/1929)) ([`f216711`](https://github.com/box/box-java-sdk/commit/f2167116cc3a84782b89984abbbd9d75fc7cfc91))
</Update>

<Update label="2026-07-10">
  ## Box Java SDK `v10.15.1` released

  ### Bug Fixes

  * Bump `Bouncy Castle` to 1.84 fix CVE ([box/box-codegen#972](https://github.com/box/box-codegen/issues/972)) ([box-java-sdk#1918](https://github.com/box/box-java-sdk/issues/1918)) ([`4441f03`](https://github.com/box/box-java-sdk/commit/4441f037afaf148b300466a23818108a364457ab))
</Update>

<Update label="2026-07-10">
  ## Box Java SDK `v5.14.1` released

  ### Bug Fixes

  * Bump `Bouncy Castle` to 1.84 ([box-java-sdk#1917](https://github.com/box/box-java-sdk/issues/1917)) ([`a88c283`](https://github.com/box/box-java-sdk/commit/a88c283c39fc36805962a5981eb2c4e10d34b87e))
</Update>

<Update label="2026-07-10">
  ## Box AI API — two new OpenAI GPT-5.6 models and Security Classification Agent default update

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been updated with the following core models:

  * <Link href="/guides/box-ai/ai-models/openai-gpt-5-6-sol-model-card">OpenAI GPT-5.6 Sol</Link>
  * <Link href="/guides/box-ai/ai-models/openai-gpt-5-6-terra-model-card">OpenAI GPT-5.6 Terra</Link>

  Additionally, the default model for the Security Classification Agent has been updated:

  * <Link href="/guides/box-ai/ai-models/google-gemini-3-1-flash-lite-model-card">Google Gemini 3.1 Flash Lite</Link> replaces <Link href="/guides/box-ai/ai-models/google-gemini-2-5-flash-model-card">Google Gemini 2.5 Flash</Link> as the default model.

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-07-10">
  ## Box Python SDK `v10.13.0` released

  ### Bug Fixes

  * Fix dictionary values deserialization ([box/box-codegen#966](https://github.com/box/box-codegen/issues/966)) ([box-python-sdk#1511](https://github.com/box/box-python-sdk/issues/1511)) ([`7352ce9`](https://github.com/box/box-python-sdk/commit/7352ce921211dc9c68f7af4344067361ecb0ebf0))

  ### New Features and Enhancements

  * Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-python-sdk#1499](https://github.com/box/box-python-sdk/issues/1499)) ([`c083ad0`](https://github.com/box/box-python-sdk/commit/c083ad0af00b962a7224795bbf56ab04d3deffc5))
  * Setup default timeouts ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-python-sdk#1507](https://github.com/box/box-python-sdk/issues/1507)) ([`b502193`](https://github.com/box/box-python-sdk/commit/b502193e66b56796ba9ea9967ad13c2f6f9edfca))
</Update>

<Update label="2026-07-10">
  ## Box Windows SDK `v10.15.0` released

  ### New Features and Enhancements

  * Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-windows-sdk-v2#1571](https://github.com/box/box-windows-sdk-v2/issues/1571)) ([`b54adb6`](https://github.com/box/box-windows-sdk-v2/commit/b54adb62dcecee641fa3000b69ce0b546949157c))
  * Setup default timeout ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-windows-sdk-v2#1577](https://github.com/box/box-windows-sdk-v2/issues/1577)) ([`b48284e`](https://github.com/box/box-windows-sdk-v2/commit/b48284e95cbf6581891503125b45b8d6e2feb1e6))
</Update>

<Update label="2026-07-09">
  ## Box iOS SDK `6.13.0` released

  ### Bug Fixes

  * **boxsdkgen:** Strip Authorization header on cross-host redirects in Swift ([box/box-codegen#964](https://github.com/box/box-codegen/issues/964)) ([box-ios-sdk#1559](https://github.com/box/box-ios-sdk/issues/1559)) ([`545a32a`](https://github.com/box/box-ios-sdk/commit/545a32ae6e1782ee102dd9457d98b0480dac8d25))

  ### New Features and Enhancements

  * **boxsdkgen:** Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-ios-sdk#1568](https://github.com/box/box-ios-sdk/issues/1568)) ([`49f3b09`](https://github.com/box/box-ios-sdk/commit/49f3b099fe2c949e6f252fc1896af58c51752267))
  * **boxsdkgen:** Setup default timeouts ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-ios-sdk#1575](https://github.com/box/box-ios-sdk/issues/1575)) ([`f434389`](https://github.com/box/box-ios-sdk/commit/f4343890486f75e72c6fc5e11f901dfebe9a9961))
</Update>

<Update label="2026-07-09">
  ## Box Windows SDK `v6.15.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-windows-sdk-v2#1570](https://github.com/box/box-windows-sdk-v2/issues/1570)) ([`6d22a92`](https://github.com/box/box-windows-sdk-v2/commit/6d22a921fd6245c27b97c8f614732ed9f5e5cda8))
  * **boxsdkgen:** Setup default timeout ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-windows-sdk-v2#1576](https://github.com/box/box-windows-sdk-v2/issues/1576)) ([`fe5cfd9`](https://github.com/box/box-windows-sdk-v2/commit/fe5cfd95ae155ddffbffdc72433a030f60c581f9))
</Update>

<Update label="2026-07-09">
  ## Box Python SDK `v4.13.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-python-sdk#1498](https://github.com/box/box-python-sdk/issues/1498)) ([`b02f154`](https://github.com/box/box-python-sdk/commit/b02f154eb7644f2746dc49e3e43bdc12e8b77209))
  * **boxsdkgen:** Setup default timeouts ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-python-sdk#1505](https://github.com/box/box-python-sdk/issues/1505)) ([`ec8d510`](https://github.com/box/box-python-sdk/commit/ec8d5107a8b3c91d24d73d6bd3a77084184c3dcf))

  ### Bug Fixes

  * **boxsdkgen:** Fix dictionary values deserialization ([box/box-codegen#966](https://github.com/box/box-codegen/issues/966)) ([box-python-sdk#1510](https://github.com/box/box-python-sdk/issues/1510)) ([`b18be5a`](https://github.com/box/box-python-sdk/commit/b18be5a916180c6861eef76f39dd4e53ce11f217))
</Update>

<Update label="2026-07-09">
  ## Box Java SDK `v5.14.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add new fields to Hubs ([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-java-sdk#1900](https://github.com/box/box-java-sdk/issues/1900)) ([`ce54ef6`](https://github.com/box/box-java-sdk/commit/ce54ef6fa9e7c20dbea41d3d2d5cb74a27ce7e32))
  * **boxsdkgen:** Setup default timeouts ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-java-sdk#1904](https://github.com/box/box-java-sdk/issues/1904)) ([`2a2e44e`](https://github.com/box/box-java-sdk/commit/2a2e44ee33a3134f1a1de5b34d11b48bb4201e7d))
</Update>

<Update label="2026-07-09">
  ## Box Java SDK `v10.15.0` released

  ### New Features and Enhancements

  * Add new fields to Hubs([box/box-openapi#606](https://github.com/box/box-openapi/issues/606)) ([box-java-sdk#1901](https://github.com/box/box-java-sdk/issues/1901)) ([`f590481`](https://github.com/box/box-java-sdk/commit/f590481020c9d8670dd1f3a96583b1b7c909c303))
  * Setup default timeouts ([box/box-codegen#965](https://github.com/box/box-codegen/issues/965)) ([box-java-sdk#1905](https://github.com/box/box-java-sdk/issues/1905)) ([`a87b8d1`](https://github.com/box/box-java-sdk/commit/a87b8d1e10e0f03f61e56b1a3328714bb78efd17))
</Update>

<Update label="2026-07-08">
  ## Box AI API — new AI models available and default model update

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been updated with the following models:

  * <Link href="/guides/box-ai/ai-models/aws-claude-fable-5-model-card">AWS Claude Fable 5</Link> (Beta)
  * <Link href="/guides/box-ai/ai-models/aws-claude-sonnet-5-model-card">AWS Claude Sonnet 5</Link>

  Additionally, the default model for the Box Agent (Standard version) has been updated:

  * <Link href="/guides/box-ai/ai-models/google-gemini-3-5-flash-model-card">Google Gemini 3.5 Flash</Link> replaces <Link href="/guides/box-ai/ai-models/openai-gpt-5-4-model-card">OpenAI GPT-5.4</Link> as the default model.

  <Note>
    Models offered in **Beta** mode have not been fully performance-tested at scale and are provided on an as-is basis.
  </Note>

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-06-25">
  ## 21 CFR Part 11 support in the Box Sign API

  You can now create and manage 21 CFR Part 11 (GxP) signature requests through the
  Box Sign API, in addition to standard requests. Previously, 21 CFR Part 11 requests
  were available only in the Box web app. You can now require 21 CFR Part 11 signatures in your own applications, as well as in Box Automate workflows and the Box for Salesforce integration.

  ## What's new

  * A new `request_flow` field lets you create requests using the `cfr11` or
    `standard` flow. When you don't set it, Box uses your enterprise's default.
  * New response fields, `reason` and `is_validated`, on signer inputs surface
    21 CFR Part 11 signing details.
  * The API enforces 21 CFR Part 11 requirements, such as required signer login,
    restricted signature colors, and signature or initials field validation.

  ## API updates

  The following endpoints now support the 21 CFR Part 11 flow:

  * [`POST /sign_requests`](/reference/post-sign-requests) — Create a 21 CFR Part 11 or standard sign request.
  * [`GET /:sign_request_id`](/reference/get-sign-requests-id) — Get a sign request, including its `request_flow`.
  * [`GET /sign_requests`](/reference/get-sign-requests) — List sign requests with their `request_flow`.
  * [`POST /:sign_request_id/cancel`](/reference/post-sign-requests-id-cancel) — Cancel a sign request.
  * [`POST /:sign_request_id/resend`](/reference/post-sign-requests-id-resend) — Resend a sign request.
  * [`GET /:template_id`](/reference/get-sign-templates-id) — Get a template, including its `request_flow`.
  * [`GET /sign_templates`](/reference/get-sign-templates) — List templates with their `request_flow`.

  ## Getting started

  To start using 21 CFR Part 11 requests, see the [21 CFR Part 11 requests](/guides/box-sign/cfr-part-11) guide.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to
  our [developer forum](https://support.box.com/hc/en-us/community/topics/360001932973-Platform-and-Developer-Forum) for any help needed.
</Update>

<Update label="2026-06-15">
  ## Box Node SDK `v1.1.0` released

  ### New Features and Enhancements

  * bump box-node-sdk to version 10.12.0 ([npm-box#22](https://github.com/box/npm-box/issues/22)) ([`f792690`](https://github.com/box/npm-box/commit/f792690fb27fb9819e12de0960d2294f265ae8e1))
</Update>

<Update label="2026-06-11">
  ## Box iOS SDK `10.12.0` released

  ### New Features and Enhancements

  * Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-ios-sdk#1553](https://github.com/box/box-ios-sdk/issues/1553)) ([`0007eda`](https://github.com/box/box-ios-sdk/commit/0007eda8466273748d898eb919c6441cc60f306a))
  * Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-ios-sdk#1552](https://github.com/box/box-ios-sdk/issues/1552)) ([`6d11e6b`](https://github.com/box/box-ios-sdk/commit/6d11e6ba91b463ea0a9189ddc4c985f6586cbbf2))
  * Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-ios-sdk#1551](https://github.com/box/box-ios-sdk/issues/1551)) ([`0ab4f19`](https://github.com/box/box-ios-sdk/commit/0ab4f19de05a8789e3182df3e69cc440763a951e))
</Update>

<Update label="2026-06-11">
  ## Box Node SDK `v10.12.0` released

  ### New Features and Enhancements

  * Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-node-sdk#1513](https://github.com/box/box-node-sdk/issues/1513)) ([`01cfe5a`](https://github.com/box/box-node-sdk/commit/01cfe5a26e0f91b4d4913d83462c36af0d1ac979))
  * Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-node-sdk#1512](https://github.com/box/box-node-sdk/issues/1512)) ([`f0d0196`](https://github.com/box/box-node-sdk/commit/f0d019654867bf90d65e250206ddce99bc0a69f0))
  * Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-node-sdk#1511](https://github.com/box/box-node-sdk/issues/1511)) ([`968c5cb`](https://github.com/box/box-node-sdk/commit/968c5cb57e8565028472f3e43bafdb4240d3a156))
</Update>

<Update label="2026-06-11">
  ## Box Windows SDK `v10.14.0` released

  ### New Features and Enhancements

  * Add Convert Note API ([box/box-codegen#955](https://github.com/box/box-codegen/issues/955)) ([box-windows-sdk-v2#1536](https://github.com/box/box-windows-sdk-v2/issues/1536)) ([`a7ca8d6`](https://github.com/box/box-windows-sdk-v2/commit/a7ca8d6378abdd19935824badd734a88d7d7fced))
  * Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-windows-sdk-v2#1559](https://github.com/box/box-windows-sdk-v2/issues/1559)) ([`7db6c4b`](https://github.com/box/box-windows-sdk-v2/commit/7db6c4b3bb79a5ceb3bc53088f3edbf349f06079))
  * Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-windows-sdk-v2#1558](https://github.com/box/box-windows-sdk-v2/issues/1558)) ([`8c27b1d`](https://github.com/box/box-windows-sdk-v2/commit/8c27b1db593e7fbf3af5041d8fb47cc912a0a76e))
  * Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-windows-sdk-v2#1555](https://github.com/box/box-windows-sdk-v2/issues/1555)) ([`beb3dc2`](https://github.com/box/box-windows-sdk-v2/commit/beb3dc290a0f3f75748ba111b1790ecca5adef4c))
</Update>

<Update label="2026-06-11">
  ## Box Java SDK `v10.14.0` released

  ### New Features and Enhancements

  * Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-java-sdk#1889](https://github.com/box/box-java-sdk/issues/1889)) ([`1747b14`](https://github.com/box/box-java-sdk/commit/1747b14eac8ae1b4a96e1da2602d9e6894d6b4ee))
  * Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-java-sdk#1888](https://github.com/box/box-java-sdk/issues/1888)) ([`09c342f`](https://github.com/box/box-java-sdk/commit/09c342f5979f0bdb1a93c822273638aa0e60dbdf))
  * Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-java-sdk#1887](https://github.com/box/box-java-sdk/issues/1887)) ([`70dc787`](https://github.com/box/box-java-sdk/commit/70dc787c16f096070428af8e2caa02be3ba6fcc0))
</Update>

<Update label="2026-06-11">
  ## Box Python SDK `v10.12.0` released

  ### New Features and Enhancements

  * Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-python-sdk#1486](https://github.com/box/box-python-sdk/issues/1486)) ([`fa0bef9`](https://github.com/box/box-python-sdk/commit/fa0bef9ba2ecd43a6490f9f176c45888e1ee03a5))
  * Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-python-sdk#1485](https://github.com/box/box-python-sdk/issues/1485)) ([`ba4f5ab`](https://github.com/box/box-python-sdk/commit/ba4f5ab5f0b9ad9d5a72fdd9f069fe4c35807986))
  * Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-python-sdk#1484](https://github.com/box/box-python-sdk/issues/1484)) ([`d2ff760`](https://github.com/box/box-python-sdk/commit/d2ff760a62fd1e4df31312d12af891e9e4862728))
</Update>

<Update label="2026-06-11">
  ## Box iOS SDK `6.12.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-ios-sdk#1548](https://github.com/box/box-ios-sdk/issues/1548)) ([`fccb1d7`](https://github.com/box/box-ios-sdk/commit/fccb1d7b690c18a3f11e928b22dc2dff5d2d4e5d))
  * **boxsdkgen:** Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-ios-sdk#1547](https://github.com/box/box-ios-sdk/issues/1547)) ([`a350beb`](https://github.com/box/box-ios-sdk/commit/a350bebb5ef24e9682ec1cacc32c14eb3d3c65f6))
  * **boxsdkgen:** Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-ios-sdk#1546](https://github.com/box/box-ios-sdk/issues/1546)) ([`e053935`](https://github.com/box/box-ios-sdk/commit/e053935d5d9b617a61602b17a6622bc936ebbfa9))
</Update>

<Update label="2026-06-11">
  ## Box Node SDK `v4.12.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-node-sdk#1514](https://github.com/box/box-node-sdk/issues/1514)) ([`f2d1618`](https://github.com/box/box-node-sdk/commit/f2d1618af79ca3292ac2cc12f5d85132ca335b3e))
  * **boxsdkgen:** Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-node-sdk#1507](https://github.com/box/box-node-sdk/issues/1507)) ([`13fcaca`](https://github.com/box/box-node-sdk/commit/13fcacaad4828c35b12af5203f1f827c50525b0f))
  * **boxsdkgen:** Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-node-sdk#1506](https://github.com/box/box-node-sdk/issues/1506)) ([`6e15f67`](https://github.com/box/box-node-sdk/commit/6e15f6736a3f61c0741cb55f618096055c6f18a1))
</Update>

<Update label="2026-06-11">
  ## Box Java SDK `v5.13.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-java-sdk#1884](https://github.com/box/box-java-sdk/issues/1884)) ([`d71a8f5`](https://github.com/box/box-java-sdk/commit/d71a8f5f76a432b7e02ac842afc2a6334d72278d))
  * **boxsdkgen:** Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-java-sdk#1882](https://github.com/box/box-java-sdk/issues/1882)) ([`16b0d70`](https://github.com/box/box-java-sdk/commit/16b0d70f18ce14e15fb94314d98c02a533b512e0))
  * **boxsdkgen:** Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-java-sdk#1881](https://github.com/box/box-java-sdk/issues/1881)) ([`de6bd88`](https://github.com/box/box-java-sdk/commit/de6bd88fa797213ba43cd2abd92ce5af65078dc5))
</Update>

<Update label="2026-06-11">
  ## Box Windows SDK `v6.14.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-windows-sdk-v2#1552](https://github.com/box/box-windows-sdk-v2/issues/1552)) ([`ffcf62b`](https://github.com/box/box-windows-sdk-v2/commit/ffcf62b42302d014d1b5f0e799cfcb75cda44a76))
  * **boxsdkgen:** Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-windows-sdk-v2#1551](https://github.com/box/box-windows-sdk-v2/issues/1551)) ([`02d0970`](https://github.com/box/box-windows-sdk-v2/commit/02d0970f8ff9b3531b2a314f1d3076ef0c5be52f))
  * **boxsdkgen:** Expose  `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-windows-sdk-v2#1550](https://github.com/box/box-windows-sdk-v2/issues/1550)) ([`e986f27`](https://github.com/box/box-windows-sdk-v2/commit/e986f27122f5d8544dac48f2e0247d4994d1d772))
</Update>

<Update label="2026-06-11">
  ## Box Python SDK `v4.12.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add new event types ([box/box-openapi#1703](https://github.com/box/box-openapi/issues/1703)) ([box/box-openapi#605](https://github.com/box/box-openapi/issues/605)) ([box-python-sdk#1481](https://github.com/box/box-python-sdk/issues/1481)) ([`b452cd9`](https://github.com/box/box-python-sdk/commit/b452cd9c4f1f3816a4558632e5a494d2b7fd2786))
  * **boxsdkgen:** Add new parameters to ai extract structured method ([box/box-openapi#604](https://github.com/box/box-openapi/issues/604)) ([box-python-sdk#1479](https://github.com/box/box-python-sdk/issues/1479)) ([`3943af2`](https://github.com/box/box-python-sdk/commit/3943af272b225b0a804113494c9cbd98e2da5e6e))
  * **boxsdkgen:** Expose `errorCode` in sign request schemas ([box/box-openapi#601](https://github.com/box/box-openapi/issues/601)) ([box-python-sdk#1478](https://github.com/box/box-python-sdk/issues/1478)) ([`edf938e`](https://github.com/box/box-python-sdk/commit/edf938e5323c3f8167c93ff2b7e247f74ca6aeb6))
</Update>

<Update label="2026-06-03">
  ## Box Node SDK `v10.11.1` released

  ### Bug Fixes

  * bump `node-fetch` and `proxy-agent` ([box/box-codegen#961](https://github.com/box/box-codegen/issues/961)) ([box-node-sdk#1502](https://github.com/box/box-node-sdk/issues/1502)) ([`e8d61f9`](https://github.com/box/box-node-sdk/commit/e8d61f92fc9c80e7f4063019638f65328c1a40f3))
  * Replace `node-fetch` with native fetch in browser ([box/box-codegen#959](https://github.com/box/box-codegen/issues/959)) ([box-node-sdk#1498](https://github.com/box/box-node-sdk/issues/1498)) ([`c128fbb`](https://github.com/box/box-node-sdk/commit/c128fbb1bf7ad8885159400a9acd94eb734076fb))
</Update>

<Update label="2026-06-03">
  ## Box iOS SDK `10.11.0` released

  ### New Features and Enhancements

  * Add Convert Note API ([box/box-codegen#955](https://github.com/box/box-codegen/issues/955)) ([box-ios-sdk#1527](https://github.com/box/box-ios-sdk/issues/1527)) ([`3efe279`](https://github.com/box/box-ios-sdk/commit/3efe2796343198a50daf9f81916facd214162140))
</Update>

<Update label="2026-06-03">
  ## Box Java SDK `v10.13.0` released

  ### New Features and Enhancements

  * Convert Note Public API ([box/box-openapi#599](https://github.com/box/box-openapi/issues/599)) ([box-java-sdk#1855](https://github.com/box/box-java-sdk/issues/1855)) ([`e396190`](https://github.com/box/box-java-sdk/commit/e396190406633a2071dacbbe0b67c4a92b03c7e0))
</Update>

<Update label="2026-06-03">
  ## Box Python SDK `v10.11.0` released

  ### New Features and Enhancements

  * Add Convert Note API ([box/box-codegen#955](https://github.com/box/box-codegen/issues/955)) ([box-python-sdk#1458](https://github.com/box/box-python-sdk/issues/1458)) ([`1215d52`](https://github.com/box/box-python-sdk/commit/1215d52b80e4ab833c6d51615cfa2e60114f9326))
</Update>

<Update label="2026-06-03">
  ## Box Node SDK `v4.11.2` released

  ### Bug Fixes

  * **boxsdkgen:** Fix global not defined in browser ([box/box-codegen#959](https://github.com/box/box-codegen/issues/959)) ([box-node-sdk#1494](https://github.com/box/box-node-sdk/issues/1494)) ([`fef58ba`](https://github.com/box/box-node-sdk/commit/fef58bac32de0c13d17b58170664fec52f5b91be))
</Update>

<Update label="2026-06-01">
  ## Box Node SDK `v4.11.1` released

  ### Bug Fixes

  * bump `@cypress/request` to resolve deprecated packages ([box-node-sdk#1487](https://github.com/box/box-node-sdk/issues/1487)) ([`9e07cd5`](https://github.com/box/box-node-sdk/commit/9e07cd50692ef5f5014065c8639dc1296e06000e))
</Update>

<Update label="2026-06-01">
  ## Box AI API — new AI models available

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been updated with the following models:

  * <Link href="/guides/box-ai/ai-models/aws-claude-4-8-opus-model-card">AWS Claude Opus 4.8</Link>
  * <Link href="/guides/box-ai/ai-models/openai-gpt-5-4-mini-model-card">OpenAI GPT-5.4 mini</Link>
  * <Link href="/guides/box-ai/ai-models/google-gemini-3-5-flash-model-card">Google Gemini 3.5 Flash</Link>

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-06-01">
  ## Box AI API — 12 AI models retired

  The following AI models are retired and no longer available in Box AI.

  * `azure__openai__gpt_4_1` (Azure OpenAI GPT-4.1)
  * `azure__openai__gpt_4_1_mini` (Azure OpenAI GPT-4.1 mini)
  * `azure__openai__gpt_4o` (Azure OpenAI GPT-4o)
  * `azure__openai__gpt_4o_mini` (Azure OpenAI GPT-4o mini)
  * `aws__claude_4_opus` (Claude 4 Opus)
  * `aws__claude_4_sonnet` (Claude 4 Sonnet)
  * `aws__titan_text_lite` (Titan Text Lite)
  * `google__gemini_3_pro` (Gemini 3 Pro)
  * `ibm__llama_4_scout` (Llama 4 Scout)
  * `ibm__llama_3_2_90b_vision_instruct` (Llama 3.2 90B Vision)
  * `xai__grok_3_beta` (Grok 3 Beta)
  * `xai__grok_3_mini_beta` (Grok 3 mini Beta)

  If you are using one of these models through agent override, switch to a [supported model](https://developer.box.com/guides/box-ai/ai-models/). See the [retired models](https://developer.box.com/guides/box-ai/ai-models/#retired-models) section for the full list.

  For further details on Box AI API, see the [guides](https://developer.box.com/guides/box-ai) and [API reference](https://developer.box.com/reference/post-ai-ask/).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-05-27">
  ## Box Java SDK `v5.12.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Convert Note Public API ([box/box-openapi#599](https://github.com/box/box-openapi/issues/599)) ([box-java-sdk#1853](https://github.com/box/box-java-sdk/issues/1853)) ([`e07dff3`](https://github.com/box/box-java-sdk/commit/e07dff3cc7d73ca7ea68644e16c5d82ef05689e3))
</Update>

<Update label="2026-05-27">
  ## Box Windows SDK `v6.13.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Add Convert Note API ([box/box-codegen#955](https://github.com/box/box-codegen/issues/955)) ([box-windows-sdk-v2#1535](https://github.com/box/box-windows-sdk-v2/issues/1535)) ([`0b4c196`](https://github.com/box/box-windows-sdk-v2/commit/0b4c19655b2371affd17e65d7837aa3427460524))
</Update>

<Update label="2026-05-27">
  ## Box Python SDK `v4.11.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add Convert Note API ([box/box-codegen#955](https://github.com/box/box-codegen/issues/955)) ([box-python-sdk#1457](https://github.com/box/box-python-sdk/issues/1457)) ([`555f8f1`](https://github.com/box/box-python-sdk/commit/555f8f175fdf12275d4a1b170ae48e44bed92436))
</Update>

<Update label="2026-05-26">
  ## New tutorials: Automate invoice processing and build an AI-powered RFP answer bank

  Two new end-to-end tutorials show you how to use Box AI to better automate your business workflows.

  ### [Invoice intake automation](/tutorials/invoice-intake)

  Stop entering invoice data by hand. This tutorial walks you through building a Python service that watches a Box folder for new PDFs, extracts vendor names, totals, dates, and line items with Box AI Extract, then writes the results back as structured metadata. Ready for your ERP or AP system, all with minimal effort.

  ### [Sales RFP answer bank](/tutorials/sales-rfp-answer-bank)

  Give your sales team instant, accurate answers grounded in approved content. Provision a Box Hub, populate it with curated proposals, embed the AI chat interface in your CRM, and let reps query past responses with natural language. Quicker, easier, and no more hunting through shared drives.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-05-15">
  ## Box Node SDK `v10.10.0` released

  ### Bug Fixes

  * Bump `next` and `uuid` versions ([box/box-codegen#950](https://github.com/box/box-codegen/issues/950)) ([box-node-sdk#1462](https://github.com/box/box-node-sdk/issues/1462)) ([`fe77f37`](https://github.com/box/box-node-sdk/commit/fe77f376c71afd5fe726cdc4991a1f6e3f0cba6b))

  ### New Features and Enhancements

  * Sanitize request body in `BoxAPIError` ([box/box-codegen#948](https://github.com/box/box-codegen/issues/948)) ([box-node-sdk#1460](https://github.com/box/box-node-sdk/issues/1460)) ([`d64ffc2`](https://github.com/box/box-node-sdk/commit/d64ffc2309e68a21724c514dc7be63161971ba4a))
  * Setup bundle analytics header ([box/box-codegen#949](https://github.com/box/box-codegen/issues/949)) ([box-node-sdk#1458](https://github.com/box/box-node-sdk/issues/1458)) ([`f00b087`](https://github.com/box/box-node-sdk/commit/f00b08726fc8fc2cce2b85ccb3a20107ec76dd38))
</Update>

<Update label="2026-05-15">
  ## Box Node SDK `v4.10.0` released

  ### Bug Fixes

  * Bump `uuid` version ([box-node-sdk#1464](https://github.com/box/box-node-sdk/issues/1464)) ([`162b075`](https://github.com/box/box-node-sdk/commit/162b075c19b9c8ebe1e3b8c17a72d3f9b6b09b87))

  ### New Features and Enhancements

  * **boxsdk:** Bundle analytics header combined SDK ([box-node-sdk#1459](https://github.com/box/box-node-sdk/issues/1459)) ([`c09168d`](https://github.com/box/box-node-sdk/commit/c09168dfdef9d675ef4934490b51e421a854ed20))
  * **boxsdkgen:** Sanitize request body in `BoxAPIError` ([box/box-codegen#948](https://github.com/box/box-codegen/issues/948)) ([box-node-sdk#1461](https://github.com/box/box-node-sdk/issues/1461)) ([`68ab417`](https://github.com/box/box-node-sdk/commit/68ab41727ce9c8846adfdbac85b5cbb7f4164c8a))
  * **boxsdkgen:** Setup bundle analytics header ([box/box-codegen#949](https://github.com/box/box-codegen/issues/949)) ([box-node-sdk#1454](https://github.com/box/box-node-sdk/issues/1454)) ([`10c7f1e`](https://github.com/box/box-node-sdk/commit/10c7f1eecfee803c0f22a747d31e2f8f85e251be))
  * **boxsdkgen:** Update events [box/box-openapi#1671](https://github.com/box/box-openapi/issues/1671) ([box/box-openapi#597](https://github.com/box/box-openapi/issues/597)) ([box-node-sdk#1453](https://github.com/box/box-node-sdk/issues/1453)) ([`89a9877`](https://github.com/box/box-node-sdk/commit/89a9877b01ca6a16b156234baae279ee9910597f))
</Update>

<Update label="2026-05-07">
  ## Box Windows SDK `v10.12.0` released

  ### ⚠  BREAKING CHANGES

  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-windows-sdk-v2#1499](https://github.com/box/box-windows-sdk-v2/issues/1499)) ([`dcb59f8`](https://github.com/box/box-windows-sdk-v2/commit/dcb59f8bebe8ef516fe04b0b3bb2f1f936500839))

  ### Bug Fixes

  * Fix error handling for binary responses ([box/box-codegen#947](https://github.com/box/box-codegen/issues/947)) ([box-windows-sdk-v2#1506](https://github.com/box/box-windows-sdk-v2/issues/1506)) ([`b0db448`](https://github.com/box/box-windows-sdk-v2/commit/b0db448e4b6e6b080cbff5a90f4de544cc609150))
  * Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-windows-sdk-v2#1500](https://github.com/box/box-windows-sdk-v2/issues/1500)) ([`4145bfc`](https://github.com/box/box-windows-sdk-v2/commit/4145bfcaa816b80f353518664dec14be383faeef))
  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-windows-sdk-v2#1499](https://github.com/box/box-windows-sdk-v2/issues/1499)) ([`dcb59f8`](https://github.com/box/box-windows-sdk-v2/commit/dcb59f8bebe8ef516fe04b0b3bb2f1f936500839))
</Update>

<Update label="2026-05-07">
  ## Box Windows SDK `v6.11.0` released

  ### ⚠  BREAKING CHANGES

  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-windows-sdk-v2#1498](https://github.com/box/box-windows-sdk-v2/issues/1498)) ([`0feb396`](https://github.com/box/box-windows-sdk-v2/commit/0feb3963d02f245c18d4558c91637e0fa4236795))

  ### **Bug Fixes:**

  * **boxsdkgen:** Fix error handling for binary responses ([box/box-codegen#947](https://github.com/box/box-codegen/issues/947)) ([box-windows-sdk-v2#1507](https://github.com/box/box-windows-sdk-v2/issues/1507)) ([`7ea8328`](https://github.com/box/box-windows-sdk-v2/commit/7ea832817377f0e673958a766a19c403ceb23a06))
  * **boxsdkgen:** Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-windows-sdk-v2#1501](https://github.com/box/box-windows-sdk-v2/issues/1501)) ([`db01cba`](https://github.com/box/box-windows-sdk-v2/commit/db01cbafe98a49f7852b9976d60d0dca2e46c193))
  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-windows-sdk-v2#1498](https://github.com/box/box-windows-sdk-v2/issues/1498)) ([`0feb396`](https://github.com/box/box-windows-sdk-v2/commit/0feb3963d02f245c18d4558c91637e0fa4236795))
</Update>

<Update label="2026-05-07">
  ## Box iOS SDK `10.9.0` released

  ### ⚠ BREAKING CHANGES

  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-ios-sdk#1488](https://github.com/box/box-ios-sdk/issues/1488)) ([`907f3f4`](https://github.com/box/box-ios-sdk/commit/907f3f403366452c93afc470818a97118c5383c9))

  ### Bug Fixes

  * Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-ios-sdk#1489](https://github.com/box/box-ios-sdk/issues/1489)) ([`bed6d9c`](https://github.com/box/box-ios-sdk/commit/bed6d9c1a70b1927853bfcf38ddc08164633e1ab))
  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-ios-sdk#1488](https://github.com/box/box-ios-sdk/issues/1488)) ([`907f3f4`](https://github.com/box/box-ios-sdk/commit/907f3f403366452c93afc470818a97118c5383c9))
</Update>

<Update label="2026-05-06">
  ## Box Node SDK `v10.9.0` released

  ### ⚠ BREAKING CHANGES

  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-node-sdk#1440](https://github.com/box/box-node-sdk/issues/1440)) ([`3082fc3`](https://github.com/box/box-node-sdk/commit/3082fc30d5e32c1290063a1a5d732c2549a03db3))

  ### Bug Fixes

  * Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-node-sdk#1441](https://github.com/box/box-node-sdk/issues/1441)) ([`be3b952`](https://github.com/box/box-node-sdk/commit/be3b952a91329605f4cb7fb2474f039201263d07))
  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-node-sdk#1440](https://github.com/box/box-node-sdk/issues/1440)) ([`3082fc3`](https://github.com/box/box-node-sdk/commit/3082fc30d5e32c1290063a1a5d732c2549a03db3))
</Update>

<Update label="2026-05-06">
  ## Box iOS SDK `6.9.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-ios-sdk#1487](https://github.com/box/box-ios-sdk/issues/1487)) ([`06facee`](https://github.com/box/box-ios-sdk/commit/06facee260a003198f8996f973d78755b9b6ba3b))

  ### Bug Fixes

  * **boxsdkgen:** Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-ios-sdk#1490](https://github.com/box/box-ios-sdk/issues/1490)) ([`72f479f`](https://github.com/box/box-ios-sdk/commit/72f479fbdc6a09e1a33649bcd1b98e66f10be12c))
  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-ios-sdk#1487](https://github.com/box/box-ios-sdk/issues/1487)) ([`06facee`](https://github.com/box/box-ios-sdk/commit/06facee260a003198f8996f973d78755b9b6ba3b))
</Update>

<Update label="2026-05-06">
  ## Box Java SDK `v10.11.0` released

  ### ⚠ BREAKING CHANGES

  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-java-sdk#1827](https://github.com/box/box-java-sdk/issues/1827)) ([`1c59b46`](https://github.com/box/box-java-sdk/commit/1c59b46e90ef5d33ff85eff45125cefe00e5e950))

  ### Bug Fixes

  * Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-java-sdk#1828](https://github.com/box/box-java-sdk/issues/1828)) ([`193718a`](https://github.com/box/box-java-sdk/commit/193718a5eb07e0816f7fc23daad3ebbe5cba993b))
  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-java-sdk#1827](https://github.com/box/box-java-sdk/issues/1827)) ([`1c59b46`](https://github.com/box/box-java-sdk/commit/1c59b46e90ef5d33ff85eff45125cefe00e5e950))
</Update>

<Update label="2026-05-06">
  ## Box Python SDK `v10.9.0` released

  ### ⚠ BREAKING CHANGES

  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-python-sdk#1422](https://github.com/box/box-python-sdk/issues/1422)) ([`d31bca4`](https://github.com/box/box-python-sdk/commit/d31bca44f67decd8e2a65eab8d95f45971bba591))

  ### Bug Fixes

  * Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-python-sdk#1423](https://github.com/box/box-python-sdk/issues/1423)) ([`3ef0ffe`](https://github.com/box/box-python-sdk/commit/3ef0ffe6288161d0f0216ddb0b07024307094fe9))
  * Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-python-sdk#1422](https://github.com/box/box-python-sdk/issues/1422)) ([`d31bca4`](https://github.com/box/box-python-sdk/commit/d31bca44f67decd8e2a65eab8d95f45971bba591))
</Update>

<Update label="2026-05-06">
  ## Box Python SDK `v4.9.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-python-sdk#1421](https://github.com/box/box-python-sdk/issues/1421)) ([`154b7ce`](https://github.com/box/box-python-sdk/commit/154b7ce7e95c61c9b8a69cf9dd0667c1484a8939))

  ### Bug Fixes

  * **boxsdkgen:** Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-python-sdk#1424](https://github.com/box/box-python-sdk/issues/1424)) ([`785457c`](https://github.com/box/box-python-sdk/commit/785457cd017c3266aed2581f5ade1263242e680b))
  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-python-sdk#1421](https://github.com/box/box-python-sdk/issues/1421)) ([`154b7ce`](https://github.com/box/box-python-sdk/commit/154b7ce7e95c61c9b8a69cf9dd0667c1484a8939))
</Update>

<Update label="2026-05-06">
  ## Box Node SDK `v4.9.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-node-sdk#1439](https://github.com/box/box-node-sdk/issues/1439)) ([`3ab5519`](https://github.com/box/box-node-sdk/commit/3ab5519c91695b1b3f42092655f57baa957ae0ef))

  ### Bug Fixes

  * **boxsdkgen:** Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-node-sdk#1442](https://github.com/box/box-node-sdk/issues/1442)) ([`11aa977`](https://github.com/box/box-node-sdk/commit/11aa97767a4653449b43da7a0397dc40abf39e97))
  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-node-sdk#1439](https://github.com/box/box-node-sdk/issues/1439)) ([`3ab5519`](https://github.com/box/box-node-sdk/commit/3ab5519c91695b1b3f42092655f57baa957ae0ef))
</Update>

<Update label="2026-05-06">
  ## Box iOS SDK `6.8.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-ios-sdk#1476](https://github.com/box/box-ios-sdk/issues/1476)) ([`eae1640`](https://github.com/box/box-ios-sdk/commit/eae16401f09d0a1a4edb289d3816f5ebf4eedeb1))
</Update>

<Update label="2026-05-06">
  ## Box Java SDK `v5.10.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-java-sdk#1826](https://github.com/box/box-java-sdk/issues/1826)) ([`7109d88`](https://github.com/box/box-java-sdk/commit/7109d8810b8ca916d50cf00a5ac024d9d28f9f31))

  ### Bug Fixes

  * **boxsdkgen:** Fix metadata template schema ([box/box-openapi#596](https://github.com/box/box-openapi/issues/596)) ([box-java-sdk#1829](https://github.com/box/box-java-sdk/issues/1829)) ([`9b51193`](https://github.com/box/box-java-sdk/commit/9b511934e70e93beeb0b5c5d4c66d4aba43077c0))
  * **boxsdkgen:** Mark `id` field of `AIAgentReference` required ([box/box-openapi#1629](https://github.com/box/box-openapi/issues/1629)) ([box/box-openapi#595](https://github.com/box/box-openapi/issues/595)) ([box-java-sdk#1826](https://github.com/box/box-java-sdk/issues/1826)) ([`7109d88`](https://github.com/box/box-java-sdk/commit/7109d8810b8ca916d50cf00a5ac024d9d28f9f31))
</Update>

<Update label="2026-05-05">
  ## New field types in the Box AI Extract Structured API

  We have introduced two new [complex field](/guides/box-ai/ai-tutorials/extract-metadata-structured#struct-and-table-field-types) types: `struct` and `table` in the Box AI
  `extract_structured`API.

  * Use `struct` to group multiple related sub-fields and extract them as a single JSON object.
    This is useful for extracting a set of related values that belong together, such as an address or a person’s contact details.
  * Use `table` to extract repeating rows of structured data as an array of JSON objects.
    This is useful for extracting multi-row data such as invoice line items or tax tables,
    regardless of how that data is formatted in the source document.

  Both types accept a `fields` array that defines their sub-fields, using the same scalar
  types already supported by the API (`string`, `float`, `date`, `enum`, `multiSelect`, and others).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-04-30">
  ## Box Windows SDK `v6.10.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-windows-sdk-v2#1485](https://github.com/box/box-windows-sdk-v2/issues/1485)) ([`e342583`](https://github.com/box/box-windows-sdk-v2/commit/e342583ade62a076ca192216745cbaa453da31a5))
</Update>

<Update label="2026-04-30">
  ## Box Windows SDK `v10.11.0` released

  ### New Features and Enhancements

  * Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-windows-sdk-v2#1488](https://github.com/box/box-windows-sdk-v2/issues/1488)) ([`ba6f6be`](https://github.com/box/box-windows-sdk-v2/commit/ba6f6befe999820ac60d70514ecb827dbfaf26b2))
</Update>

<Update label="2026-04-30">
  ## Box iOS SDK `10.8.0` released

  ### New Features and Enhancements

  * Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-ios-sdk#1478](https://github.com/box/box-ios-sdk/issues/1478)) ([`1df6e4b`](https://github.com/box/box-ios-sdk/commit/1df6e4b16c79ef9d22d9b103cbe7b09dc1f5d09f))
</Update>

<Update label="2026-04-30">
  ## Box Node SDK `v4.8.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Support Automate API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-node-sdk#1432](https://github.com/box/box-node-sdk/issues/1432)) ([`010fcdc`](https://github.com/box/box-node-sdk/commit/010fcdc947003675403b4acc9d9a1485ee9c4bac))
</Update>

<Update label="2026-04-30">
  ## Box Node SDK `v10.8.0` released

  ### New Features and Enhancements

  * Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-node-sdk#1429](https://github.com/box/box-node-sdk/issues/1429)) ([`ab49fe5`](https://github.com/box/box-node-sdk/commit/ab49fe5d7fcb97d5295d813008f1f1cf113134b8))
</Update>

<Update label="2026-04-30">
  ## Box Java SDK `v10.10.0` released

  ### Bug Fixes

  * Fix java `oneOf` serialization ([box/box-codegen#942](https://github.com/box/box-codegen/issues/942)) ([box-java-sdk#1806](https://github.com/box/box-java-sdk/issues/1806)) ([`dcd5df6`](https://github.com/box/box-java-sdk/commit/dcd5df60f3545983209e58c50ab1648a6d5fb167))

  ### New Features and Enhancements

  * Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-java-sdk#1820](https://github.com/box/box-java-sdk/issues/1820)) ([`41e859a`](https://github.com/box/box-java-sdk/commit/41e859acf78844b0a2e28d3d14ca721b88e2a108))
</Update>

<Update label="2026-04-30">
  ## Box Python SDK `v4.8.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-python-sdk#1412](https://github.com/box/box-python-sdk/issues/1412)) ([`4a39dcc`](https://github.com/box/box-python-sdk/commit/4a39dccd6ea375d364687eb9d17f60233e98f37f))
</Update>

<Update label="2026-04-30">
  ## Box Java SDK `v5.9.0` released

  ### Bug Fixes

  * **boxsdkgen:** Fix java `oneOf` serialization ([box/box-codegen#942](https://github.com/box/box-codegen/issues/942)) ([box-java-sdk#1805](https://github.com/box/box-java-sdk/issues/1805)) ([`cf0d67f`](https://github.com/box/box-java-sdk/commit/cf0d67fa25af2ef4b9458362e9e896ce50674e62))

  ### New Features and Enhancements

  * **boxsdkgen:** Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-java-sdk#1816](https://github.com/box/box-java-sdk/issues/1816)) ([`4369d9c`](https://github.com/box/box-java-sdk/commit/4369d9c45ca6ff5d3045e7e193335560eb886b6f))
</Update>

<Update label="2026-04-30">
  ## Box Python SDK `v10.8.0` released

  ### New Features and Enhancements

  * Automate Public API ([box/box-openapi#594](https://github.com/box/box-openapi/issues/594)) ([box-python-sdk#1409](https://github.com/box/box-python-sdk/issues/1409)) ([`3cfb35c`](https://github.com/box/box-python-sdk/commit/3cfb35c6a86062658588afd779410bb426472427))
</Update>

<Update label="2026-04-23">
  ## Box CLI `v4.8.0` released

  ### New Features and Enhancements

  * Add `--raw-json` flag and fix `--json` output ([boxcli#669](https://github.com/box/boxcli/issues/669)) ([`ee6d61d`](https://github.com/box/boxcli/commit/ee6d61d576e5cb037cf1b080f49ddfbd181eee09))
  * Add support for `Box Hub Collaborations` endpoints ([boxcli#668](https://github.com/box/boxcli/issues/668)) ([`543cd60`](https://github.com/box/boxcli/commit/543cd60b0f5532bb307aefc2291c0d051e8481bb))
  * Add support for `Box Hub Document` endpoints ([boxcli#667](https://github.com/box/boxcli/issues/667)) ([`2b21328`](https://github.com/box/boxcli/commit/2b213285ee8d6205a8461756231beb372ca81059))
  * Add support for `Box Hub Items` endpoints ([boxcli#665](https://github.com/box/boxcli/issues/665)) ([`0f46680`](https://github.com/box/boxcli/commit/0f466800a65ad9d57c20057f86f2410e8343493f))
  * Add support for `Box Hubs` endpoints ([boxcli#664](https://github.com/box/boxcli/issues/664)) ([`681b312`](https://github.com/box/boxcli/commit/681b31256592bbde00ffc4426917911f51fd951c))
</Update>

<Update label="2026-04-22">
  ## Box Windows SDK `v10.10.0` released

  ### New Features and Enhancements

  * Add `max_extension_length` field to Retention Policies ([box/box-codegen#941](https://github.com/box/box-codegen/issues/941)) ([box-windows-sdk-v2#1471](https://github.com/box/box-windows-sdk-v2/issues/1471)) ([`7715a00`](https://github.com/box/box-windows-sdk-v2/commit/7715a0047d54aa5062b4819f9a7addc59f049241))
</Update>

<Update label="2026-04-22">
  ## Box Windows SDK `v6.9.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Add `max_extension_length` field to Retention Policies ([box/box-codegen#941](https://github.com/box/box-codegen/issues/941)) ([box-windows-sdk-v2#1472](https://github.com/box/box-windows-sdk-v2/issues/1472)) ([`bf0e681`](https://github.com/box/box-windows-sdk-v2/commit/bf0e6819d32e4bb08d512c27cccc733dc620144c))
</Update>

<Update label="2026-04-22">
  ## Box Node SDK `v10.7.0` released

  ### Bug Fixes

  * Update `retentionLength` field to accept both string and number ([box/box-codegen#932](https://github.com/box/box-codegen/issues/932)) ([box-node-sdk#1397](https://github.com/box/box-node-sdk/issues/1397)) ([`e589c63`](https://github.com/box/box-node-sdk/commit/e589c63e660ecfd76f0d7847613789ce809c7d16))

  ### New Features and Enhancements

  * Add `max_extension_length` field to Retention Policies ([box/box-openapi#593](https://github.com/box/box-openapi/issues/593)) ([box-node-sdk#1413](https://github.com/box/box-node-sdk/issues/1413)) ([`28d1a71`](https://github.com/box/box-node-sdk/commit/28d1a719f8f257ddb040aef604720c9eed53f80d))
</Update>

<Update label="2026-04-22">
  ## Box Java SDK `v10.9.0` released

  ### New Features and Enhancements

  * Add `max_extension_length` field to Retention Policies ([box/box-openapi#593](https://github.com/box/box-openapi/issues/593)) ([box-java-sdk#1799](https://github.com/box/box-java-sdk/issues/1799)) ([`fc91872`](https://github.com/box/box-java-sdk/commit/fc91872b19e16d919fd641e1a6b461639ebbdc54))
</Update>

<Update label="2026-04-22">
  ## Box Node SDK `v4.7.0` released

  ### Bug Fixes

  * **boxsdkgen:** Update `retentionLength` field to accept both string and number ([box/box-codegen#932](https://github.com/box/box-codegen/issues/932)) ([box-node-sdk#1396](https://github.com/box/box-node-sdk/issues/1396)) ([`556f4a6`](https://github.com/box/box-node-sdk/commit/556f4a6244e8a754c9c332da4b04dd548a57c631))

  ### New Features and Enhancements

  * **boxsdkgen:** Add `max_extension_length` field to Retention Policies ([box/box-openapi#593](https://github.com/box/box-openapi/issues/593)) ([box-node-sdk#1412](https://github.com/box/box-node-sdk/issues/1412)) ([`a9a3fce`](https://github.com/box/box-node-sdk/commit/a9a3fce3432bf6e89e759123b52f43b2e174360d))
</Update>

<Update label="2026-04-22">
  ## Box Python SDK `v10.7.0` released

  ### Bug Fixes

  * Correct `retention_length` type hint to accept both integer and string ([box/box-codegen#932](https://github.com/box/box-codegen/issues/932)) ([box-python-sdk#1382](https://github.com/box/box-python-sdk/issues/1382)) ([`e8f93ce`](https://github.com/box/box-python-sdk/commit/e8f93ce4da1d2c68d809e4af38741ebf91bc6fe2))

  ### New Features and Enhancements

  * Add `max_extension_length` field to Retention Policies ([box/box-openapi#593](https://github.com/box/box-openapi/issues/593)) ([box-python-sdk#1394](https://github.com/box/box-python-sdk/issues/1394)) ([`acbb3c6`](https://github.com/box/box-python-sdk/commit/acbb3c629be44d0fd6d507f9b164f87439d6083d))
</Update>

<Update label="2026-04-22">
  ## Box Java SDK `v5.8.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** Add `max_extension_length` field to Retention Policies ([box/box-openapi#593](https://github.com/box/box-openapi/issues/593)) ([box-java-sdk#1798](https://github.com/box/box-java-sdk/issues/1798)) ([`05548e2`](https://github.com/box/box-java-sdk/commit/05548e26213bc618ab86c9bbba8457a7cfcf5984))
</Update>

<Update label="2026-04-22">
  ## Box Python SDK `v4.7.0` released

  ### Bug Fixes

  * **boxsdkgen:** Correct `retention_length` type hint to accept both integer and string ([box/box-codegen#932](https://github.com/box/box-codegen/issues/932)) ([box-python-sdk#1381](https://github.com/box/box-python-sdk/issues/1381)) ([`c0df010`](https://github.com/box/box-python-sdk/commit/c0df0102a1dbc416f37796ee6e6aa597cf40c023))

  ### New Features and Enhancements

  * **boxsdkgen:** Add `max_extension_length` field to Retention Policies ([box/box-openapi#593](https://github.com/box/box-openapi/issues/593)) ([box-python-sdk#1393](https://github.com/box/box-python-sdk/issues/1393)) ([`5465f9c`](https://github.com/box/box-python-sdk/commit/5465f9c29a19b1a6ee0d323caa6ad16432a86774))
</Update>

<Update label="2026-04-17">
  ## Box Agent Skills released

  Box Agent Skills are pre-built instruction sets that teach AI coding assistants how to perform specific tasks. They give your AI assistant the context it needs to build Box integrations, work with Box content through MCP tools, configure webhooks, and use Box AI retrieval — no manual configuration required.

  The skills follow the [Agent Skills](https://developer.box.com/ai/agent-skills) open standard and can be installed as a plugin for [Codex](https://github.com/box/box-for-ai/blob/main/.codex-plugin/README.md), [Cursor](https://github.com/box/box-for-ai/blob/main/.cursor-plugin/README.md), or [Claude Code](https://github.com/box/box-for-ai/blob/main/.claude-plugin/README.md).

  For detailed reference material, additional examples, and contributing guidelines, see the [box-for-ai](https://github.com/box/box-for-ai) repository on GitHub.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-04-16">
  ## Box Windows SDK `v10.9.0` released

  ### Bug Fixes

  * Update `RetentionLength` field to accept both string and integer ([box/box-codegen#932](https://github.com/box/box-codegen/issues/932)) ([box-windows-sdk-v2#1445](https://github.com/box/box-windows-sdk-v2/issues/1445)) ([`ed3110e`](https://github.com/box/box-windows-sdk-v2/commit/ed3110e0d40544c80a289c48ba7cd34910933e65))

  ### New Features and Enhancements

  * Extensible enum in DotNet ([box/box-codegen#937](https://github.com/box/box-codegen/issues/937)) ([box-windows-sdk-v2#1460](https://github.com/box/box-windows-sdk-v2/issues/1460)) ([`ccb4dd9`](https://github.com/box/box-windows-sdk-v2/commit/ccb4dd985a35a674d0e0deeda1f43524ffc7c166))
</Update>

<Update label="2026-04-02">
  ## Box AI API — new models, default model tables, and updated models overview

  The <Link href="/guides/box-ai/ai-models">AI models overview</Link> page has been updated with the following changes:

  ### New AI models

  The following models are now available:

  * <Link href="/guides/box-ai/ai-models/openai-gpt-5-4-model-card">OpenAI GPT-5.4</Link>
  * <Link href="/guides/box-ai/ai-models/google-gemini-3-1-flash-lite-model-card">Google Gemini 3.1 Flash Lite</Link>

  ### Default model tables

  A new <Link href="/guides/box-ai/ai-models#default-models">Default models</Link> section now documents which AI models are used by default when you do not override the agent configuration. The section includes tables for:

  * **Legacy agents** — default models for Q\&A across Documents, Notes, and Hubs, broken down by provider and capability tier.
  * **Box agents** — default models for Box Agent, Extract Agent, Security Classification Agent, and Threat Analysis Agent.

  ### Restructured models overview

  * Models are now grouped by provider (OpenAI, Google, Anthropic, Meta, Mistral AI, xAI) using collapsible sections.
  * Model cards now display "Compatible with Box Agent" badges where applicable.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-04-01">
  ## Box Windows SDK `v10.8.0` released

  ### ⚠ BREAKING CHANGES

  * Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-windows-sdk-v2#1431](https://github.com/box/box-windows-sdk-v2/issues/1431))
  * Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-windows-sdk-v2#1427](https://github.com/box/box-windows-sdk-v2/issues/1427))

  ### Bug Fixes

  * Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-windows-sdk-v2#1427](https://github.com/box/box-windows-sdk-v2/issues/1427)) ([`2079002`](https://github.com/box/box-windows-sdk-v2/commit/207900280c25d40b500b4771e163b6fa10228cc7))
  * Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-windows-sdk-v2#1431](https://github.com/box/box-windows-sdk-v2/issues/1431)) ([d6bd881](https://github.com/box/box-windows-sdk-v2/commit/d6bd881890f442c80d5fdda9c9ebe0bdda3a8c32))
  * Fix Union members to default to null and Enum deserialization ([box/box-codegen#933](https://github.com/box/box-codegen/issues/933)) ([box-windows-sdk-v2#1438](https://github.com/box/box-windows-sdk-v2/issues/1438)) ([7a5756a](https://github.com/box/box-windows-sdk-v2/commit/7a5756afaedf66009efe1f8d96eb844706a4f676))
  * Handle empty API error bodies ([box/box-codegen#934](https://github.com/box/box-codegen/issues/934)) ([box-windows-sdk-v2#1441](https://github.com/box/box-windows-sdk-v2/issues/1441)) ([183449e](https://github.com/box/box-windows-sdk-v2/commit/183449ea98e2ca073d8f98d41213452070eb1cc1))

  ### New Features and Enhancements

  * Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-windows-sdk-v2#1418](https://github.com/box/box-windows-sdk-v2/issues/1418)) ([8527a35](https://github.com/box/box-windows-sdk-v2/commit/8527a35f5977c4f2721bf33923f3578e111d810a))
  * Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-windows-sdk-v2#1433](https://github.com/box/box-windows-sdk-v2/issues/1433)) ([a57db33](https://github.com/box/box-windows-sdk-v2/commit/a57db33fd43ad6f04f33ec81fd74353e83e02714))
</Update>

<Update label="2026-04-01">
  ## Box Windows SDK `v6.7.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-windows-sdk-v2#1432](https://github.com/box/box-windows-sdk-v2/issues/1432))

  ### **New Features and Enhancements:**

  * **boxsdkgen:** Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-windows-sdk-v2#1417](https://github.com/box/box-windows-sdk-v2/issues/1417)) ([a9ad210](https://github.com/box/box-windows-sdk-v2/commit/a9ad2107d31a36af4b0e91f9079295f1dc8e9d2a))
  * **boxsdkgen:** Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-windows-sdk-v2#1434](https://github.com/box/box-windows-sdk-v2/issues/1434)) ([3893c0c](https://github.com/box/box-windows-sdk-v2/commit/3893c0c976aed671712e88eab7b66c38c722f129))

  ### **Bug Fixes:**

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-windows-sdk-v2#1432](https://github.com/box/box-windows-sdk-v2/issues/1432)) ([189afe9](https://github.com/box/box-windows-sdk-v2/commit/189afe958b3f13b68db0167b37ee5eb60eaf8cef))
  * **boxsdkgen:** Fix Union members to default to null and Enum deserialization ([box/box-codegen#933](https://github.com/box/box-codegen/issues/933)) ([box-windows-sdk-v2#1437](https://github.com/box/box-windows-sdk-v2/issues/1437)) ([8d32a69](https://github.com/box/box-windows-sdk-v2/commit/8d32a6929ebc32ddaf39cb945c297a6d0a23dedf))
  * **boxsdkgen:** Handle empty API error bodies ([box/box-codegen#934](https://github.com/box/box-codegen/issues/934)) ([box-windows-sdk-v2#1440](https://github.com/box/box-windows-sdk-v2/issues/1440)) ([63f1d8c](https://github.com/box/box-windows-sdk-v2/commit/63f1d8ca3ccbf74d39fb2d5215e8399688248458))
</Update>

<Update label="2026-04-01">
  ## Box Java SDK `v10.7.0` released

  ### ⚠ BREAKING CHANGES

  * Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-java-sdk#1766](https://github.com/box/box-java-sdk/issues/1766))
  * Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-java-sdk#1762](https://github.com/box/box-java-sdk/issues/1762))

  ### Bug Fixes

  * Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-java-sdk#1762](https://github.com/box/box-java-sdk/issues/1762)) ([8f82b46](https://github.com/box/box-java-sdk/commit/8f82b46afe978342fb93af6ad31006342a1f5b5a))
  * Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-java-sdk#1766](https://github.com/box/box-java-sdk/issues/1766)) ([52b408e](https://github.com/box/box-java-sdk/commit/52b408ec649dd7d36d3ecc6f2506f34afde644bd))

  ### New Features and Enhancements

  * Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-java-sdk#1741](https://github.com/box/box-java-sdk/issues/1741)) ([fccccb7](https://github.com/box/box-java-sdk/commit/fccccb766d961e9badd1cde274595e07ba88b7a2))
  * Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-java-sdk#1767](https://github.com/box/box-java-sdk/issues/1767)) ([8b2ef9f](https://github.com/box/box-java-sdk/commit/8b2ef9f003b76f88ea0481a0539efad38ae63a3b))
</Update>

<Update label="2026-04-01">
  ## Box Java SDK `v5.6.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-java-sdk#1761](https://github.com/box/box-java-sdk/issues/1761))

  ### Bug Fixes:

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-java-sdk#1761](https://github.com/box/box-java-sdk/issues/1761)) ([1fff919](https://github.com/box/box-java-sdk/commit/1fff919577062ac54338f53f87d3c910312283f5))

  ### New Features and Enhancements:

  * **boxsdkgen:** Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-java-sdk#1740](https://github.com/box/box-java-sdk/issues/1740)) ([92289cb](https://github.com/box/box-java-sdk/commit/92289cbd9cb0765c742229767be70d63cd220f19))
  * **boxsdkgen:** Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-java-sdk#1763](https://github.com/box/box-java-sdk/issues/1763)) ([2f17efe](https://github.com/box/box-java-sdk/commit/2f17efe105a1a732d4f3bb6815fe18f360a8cb9c))
</Update>

<Update label="2026-04-01">
  ## Box Python SDK `v10.6.0` released

  ### ⚠ BREAKING CHANGES

  * Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-python-sdk#1369](https://github.com/box/box-python-sdk/issues/1369))

  ### Bug Fixes

  * Add missing discriminators for schema types ([box/box-codegen#931](https://github.com/box/box-codegen/issues/931)) ([box-python-sdk#1368](https://github.com/box/box-python-sdk/issues/1368)) ([fe0a3b8](https://github.com/box/box-python-sdk/commit/fe0a3b86b292d7304c244e4b6933612bbce5f332))
  * Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-python-sdk#1365](https://github.com/box/box-python-sdk/issues/1365)) ([feb2010](https://github.com/box/box-python-sdk/commit/feb201068f851701ecd6f2dfea522182a33a6846))
  * Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-python-sdk#1369](https://github.com/box/box-python-sdk/issues/1369)) ([39fbc7c](https://github.com/box/box-python-sdk/commit/39fbc7cd88a3e0a6a002cd2aa202d10730c6d91a))

  ### New Features and Enhancements

  * Add `include_reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-python-sdk#1360](https://github.com/box/box-python-sdk/issues/1360)) ([59c1d3c](https://github.com/box/box-python-sdk/commit/59c1d3c156cc079aa1ad66f7bb2476d48c67a57c))
  * Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-python-sdk#1371](https://github.com/box/box-python-sdk/issues/1371)) ([720b948](https://github.com/box/box-python-sdk/commit/720b94835b1b5308d8c1b8b3a7bc176766d98a04))
</Update>

<Update label="2026-04-01">
  ## Box Python SDK `v4.6.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-python-sdk#1370](https://github.com/box/box-python-sdk/issues/1370))

  ### Bug Fixes:

  * **boxsdkgen:** Add missing discriminators for schema types ([box/box-codegen#931](https://github.com/box/box-codegen/issues/931)) ([box-python-sdk#1367](https://github.com/box/box-python-sdk/issues/1367)) ([113faa3](https://github.com/box/box-python-sdk/commit/113faa396043e1e82cf9c73ec43034d7e6be62a6))
  * **boxsdkgen:** Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-python-sdk#1366](https://github.com/box/box-python-sdk/issues/1366)) ([6df014e](https://github.com/box/box-python-sdk/commit/6df014e00d3467e85004e5d0a1f38cbe7847bcea))
  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-python-sdk#1370](https://github.com/box/box-python-sdk/issues/1370)) ([213960d](https://github.com/box/box-python-sdk/commit/213960dfd1a09bfce82bdc0e5b52297265607e57))

  ### New Features and Enhancements:

  * **boxsdkgen:** Add `include_reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-python-sdk#1359](https://github.com/box/box-python-sdk/issues/1359)) ([94cfd09](https://github.com/box/box-python-sdk/commit/94cfd09a89b3b9649656dd38cea3e088f3916d6c))
  * **boxsdkgen:** Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-python-sdk#1372](https://github.com/box/box-python-sdk/issues/1372)) ([f346676](https://github.com/box/box-python-sdk/commit/f34667680ed70f952fa85a41aa5281f16ff40d70))
</Update>

<Update label="2026-04-01">
  ## Box iOS SDK `10.6.0` released

  ### ⚠ BREAKING CHANGES

  * Correct search content type 'tags' to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-ios-sdk#1442](https://github.com/box/box-ios-sdk/issues/1442))
  * Align `LegalHoldPolicyAssignedItem` with API  ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-ios-sdk#1440](https://github.com/box/box-ios-sdk/issues/1440))

  ### Bug Fixes

  * Align `LegalHoldPolicyAssignedItem` with API  ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-ios-sdk#1440](https://github.com/box/box-ios-sdk/issues/1440)) ([c6e9f9b](https://github.com/box/box-ios-sdk/commit/c6e9f9b4b0bd838859b9971032c5fd3965e36e61))
  * Correct search content type 'tags' to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-ios-sdk#1442](https://github.com/box/box-ios-sdk/issues/1442)) ([4c35f6f](https://github.com/box/box-ios-sdk/commit/4c35f6fb383bde5579d00c9d735720a6285361cb))

  ### New Features and Enhancements

  * Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-ios-sdk#1424](https://github.com/box/box-ios-sdk/issues/1424)) ([330e763](https://github.com/box/box-ios-sdk/commit/330e763cc5ca08ab936b20130bda0ea28a8153d2))
  * Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-ios-sdk#1443](https://github.com/box/box-ios-sdk/issues/1443)) ([e176bef](https://github.com/box/box-ios-sdk/commit/e176bef06ab8b80ce3d5f6a4a3890a8d86e53c98))
</Update>

<Update label="2026-04-01">
  ## Box iOS SDK `6.6.0` released

  ### ⚠ BREAKING CHANGES

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-ios-sdk#1437](https://github.com/box/box-ios-sdk/issues/1437))

  ### Bug Fixes

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-ios-sdk#1437](https://github.com/box/box-ios-sdk/issues/1437)) ([ae3f23a](https://github.com/box/box-ios-sdk/commit/ae3f23a570cb19121f03e91d8ec4cfc049878f24))

  ### New Features and Enhancements

  * **boxsdkgen:** Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-ios-sdk#1423](https://github.com/box/box-ios-sdk/issues/1423)) ([a038414](https://github.com/box/box-ios-sdk/commit/a038414b3d635ae8521cd3bfb695d1279161b3cb))
  * **boxsdkgen:** Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-ios-sdk#1438](https://github.com/box/box-ios-sdk/issues/1438)) ([2fd2f2a](https://github.com/box/box-ios-sdk/commit/2fd2f2ad295af902b32732a61eac01ce33ae4cd8))
</Update>

<Update label="2026-04-01">
  ## Box Node SDK `v10.6.0` released

  ### ⚠ BREAKING CHANGES

  * Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-node-sdk#1378](https://github.com/box/box-node-sdk/issues/1378))

  ### Bug Fixes

  * Align `LegalHoldPolicyAssignedItem` with API ([box/box-openapi#1554](https://github.com/box/box-openapi/issues/1554)) ([box/box-openapi#590](https://github.com/box/box-openapi/issues/590)) ([box-node-sdk#1378](https://github.com/box/box-node-sdk/issues/1378)) ([466d6cf](https://github.com/box/box-node-sdk/commit/466d6cf61113bf5bac8eef14644d047124f6ef03))
  * Correct search content type 'tags' to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-node-sdk#1382](https://github.com/box/box-node-sdk/issues/1382)) ([6f5d307](https://github.com/box/box-node-sdk/commit/6f5d3071116113ee6e3afe082cfb6554f44c6156))

  ### New Features and Enhancements

  * Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-node-sdk#1372](https://github.com/box/box-node-sdk/issues/1372)) ([e55c51f](https://github.com/box/box-node-sdk/commit/e55c51f32227e5d0d4ab7b29a51e996867a39b15))
  * Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-node-sdk#1388](https://github.com/box/box-node-sdk/issues/1388)) ([0b5fbeb](https://github.com/box/box-node-sdk/commit/0b5fbebf18e582a36a17d84c3584ab80f880ea04))
</Update>

<Update label="2026-04-01">
  ## Box Node SDK `v4.6.0` released

  ### Bug Fixes

  * **boxsdkgen:** Correct search content type `tags` to match API ([box/box-openapi#591](https://github.com/box/box-openapi/issues/591)) ([box-node-sdk#1383](https://github.com/box/box-node-sdk/issues/1383)) ([d6bca72](https://github.com/box/box-node-sdk/commit/d6bca725910f2539bfb8ac984295e0c19b610191))

  ### New Features and Enhancements

  * **boxsdkgen:** Add `reference` to `AI` and `parent_id` to `HubsItems` ([box/box-openapi#588](https://github.com/box/box-openapi/issues/588)) ([box-node-sdk#1371](https://github.com/box/box-node-sdk/issues/1371)) ([5c299f0](https://github.com/box/box-node-sdk/commit/5c299f09268c546528c1748ea6e0774312a3f9f0))
  * **boxsdkgen:** Support Hub Document API ([box/box-codegen#930](https://github.com/box/box-codegen/issues/930)) ([box-node-sdk#1385](https://github.com/box/box-node-sdk/issues/1385)) ([306c96c](https://github.com/box/box-node-sdk/commit/306c96cb988f0091fb146e1a4b15c12284f6d572))
</Update>

<Update label="2026-03-26">
  ## Box CLI `v4.7.0` released

  ### New Features and Enhancements

  * Mask client secret in configure environments command ([boxcli#654](https://github.com/box/boxcli/issues/654))
  * Secure OAuth callback handling ([boxcli#653](https://github.com/box/boxcli/issues/653))

  ### Bug Fixes

  * Fix `oss` command ([boxcli#650](https://github.com/box/boxcli/issues/650))
</Update>

<Update label="2026-03-19">
  ## Box iOS SDK `10.5.0` released

  ### New Features and Enhancements

  * `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-ios-sdk#1420](https://github.com/box/box-ios-sdk/issues/1420))
  * Configurable timeouts have been added to SDKs ([box-ios-sdk#1414](https://github.com/box/box-ios-sdk/issues/1414))
</Update>

<Update label="2026-03-19">
  ## Box iOS SDK `6.5.0` released

  ### New Features and Enhancements

  * **boxsdkgen:** `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-ios-sdk#1419](https://github.com/box/box-ios-sdk/issues/1419))
  * **boxsdkgen:** Configurable timeouts have been added to SDKs ([box-ios-sdk#1413](https://github.com/box/box-ios-sdk/issues/1413))
</Update>

<Update label="2026-03-18">
  ## Box Windows SDK `v10.7.0` released

  ### New Features and Enhancements

  * `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-windows-sdk-v2#1414](https://github.com/box/box-windows-sdk-v2/issues/1414))
</Update>

<Update label="2026-03-18">
  ## Box Windows SDK `v6.6.0` released

  ### **New Features and Enhancements:**

  * **boxsdkgen:** `canPublicSharedLinkBeCreated` has been added to `Hubs`([box-windows-sdk-v2#1413](https://github.com/box/box-windows-sdk-v2/issues/1413))
</Update>

<Update label="2026-03-18">
  ## Box Java SDK `v10.6.0` released

  ### New Features and Enhancements

  * `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-java-sdk#1737](https://github.com/box/box-java-sdk/issues/1737))
  * Configurable timeouts have been added to SDKs ([box-java-sdk#1730](https://github.com/box/box-java-sdk/issues/1730))
</Update>

<Update label="2026-03-18">
  ## Reference in extract

  The [`extract_structured` endpoint](/reference/post-ai-extract-structured) now supports the `include_reference` parameter.
  This parameter allows you to include the information about the location (where in the document the text was extracted) as well as the reference (exact text extracted) in the response.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-03-18">
  ## Box Node SDK `v10.5.0` released

  ### Bug Fixes

  * `retryAfter` has been converted from seconds to milliseconds for `setTimeout` ([box-node-sdk#1356](https://github.com/box/box-node-sdk/issues/1356))

  ### New Features and Enhancements

  * `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-node-sdk#1367](https://github.com/box/box-node-sdk/issues/1367))
  * Configurable timeouts have been added to SDKs ([box-node-sdk#1360](https://github.com/box/box-node-sdk/issues/1360))
</Update>

<Update label="2026-03-18">
  ## Box Python SDK `v10.5.0` released

  ### New Features and Enhancements

  * `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-python-sdk#1356](https://github.com/box/box-python-sdk/issues/1356))
  * Configurable timeouts have been added to SDKs ([box-python-sdk#1349](https://github.com/box/box-python-sdk/issues/1349))
</Update>

<Update label="2026-03-18">
  ## Box Java SDK `v5.5.0` released

  ### New Features and Enhancements:

  * `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-java-sdk#1736](https://github.com/box/box-java-sdk/issues/1736))
  * Customizable timeouts have been added to SDKs ([box-java-sdk#1731](https://github.com/box/box-java-sdk/issues/1731))
</Update>

<Update label="2026-03-18">
  ## Box Node SDK `v4.5.0` released

  ### Bug Fixes

  * `retryAfter` has been converted from seconds to milliseconds for `setTimeout`

  ### New Features and Enhancements

  * `canPublicSharedLinkBeCreated` has been added to `Hubs`([box-node-sdk#1366](https://github.com/box/box-node-sdk/issues/1366))
  * Configurable timeouts have been added to SDKs ([box-node-sdk#1361](https://github.com/box/box-node-sdk/issues/1361))
</Update>

<Update label="2026-03-18">
  ## Box Python SDK `v4.5.0` released

  ### New Features and Enhancements:

  * `canPublicSharedLinkBeCreated` has been added to `Hubs` ([box-python-sdk#1355](https://github.com/box/box-python-sdk/issues/1355))
  * Configurable timeouts have been added to SDKs ([box-python-sdk#1348](https://github.com/box/box-python-sdk/issues/1348))
</Update>

<Update label="2026-03-17">
  ## Box CLI `v4.6.0` released

  ### New Features and Enhancements

  * Add `--overwrite` flag to `files:upload` command ([boxcli#637](https://github.com/box/boxcli/issues/637)) ([`6231663`](https://github.com/box/boxcli/commit/6231663c3e79eacfd52bcfe399527e12d589adb0))
  * Add support for Box Official App in login command ([boxcli#638](https://github.com/box/boxcli/issues/638)) ([bcd6835](https://github.com/box/boxcli/commit/bcd6835fb631ef7cd88ba8545b42b177ed2b3644))
  * Improve developer and agent experience in `boxcli` commands ([boxcli#643](https://github.com/box/boxcli/issues/643)) ([fbc817f](https://github.com/box/boxcli/commit/fbc817f6e25c6f0236777473e8a3e3ef5241df13))
  * Improve login prompt ([boxcli#642](https://github.com/box/boxcli/issues/642)) ([a58ff34](https://github.com/box/boxcli/commit/a58ff34dde121285233c174785071057e04c13a6))
  * Store access token encrypted in secure storage ([boxcli#639](https://github.com/box/boxcli/issues/639)) ([bed6db3](https://github.com/box/boxcli/commit/bed6db362aa501cfa1b47d9db74f26456adfa1be))
  * Support logout command ([boxcli#635](https://github.com/box/boxcli/issues/635)) ([842e308](https://github.com/box/boxcli/commit/842e308f38af8351ea469dfb1ecd705304611dc0))
  * Unify secure storage backend across platforms ([boxcli#647](https://github.com/box/boxcli/issues/647)) ([6b2ed36](https://github.com/box/boxcli/commit/6b2ed36655f7e896ee5a41308b60c28594fe693c))

  ### Bug Fixes

  * Fix encoding for example scripts on Windows ([boxcli#613](https://github.com/box/boxcli/issues/613)) ([0265e2a](https://github.com/box/boxcli/commit/0265e2a65c4a985404b07ef2f83f56a903be329d))
  * fix help commands ([boxcli#611](https://github.com/box/boxcli/issues/611)) ([7aec97b](https://github.com/box/boxcli/commit/7aec97b0a63d2c1b3496cb296cf6dddaf539a9aa))
  * Normalize inquirer `signal-exit` compatibility on Windows ([boxcli#645](https://github.com/box/boxcli/issues/645)) ([310b2f6](https://github.com/box/boxcli/commit/310b2f6ea07a856709b6a46454d1852fa66b7a66))
</Update>

<Update label="2026-03-17">
  ## New Box CLI launched

  We've launched a new version of the Box CLI, so you can:

  * Authenticate instantly with your own Box credentials using OAuth
  * Automate complex, multi-step workflows — upload files, extract metadata, apply watermarks, trigger document signing — all from the command line
  * Give your AI agents a composable interface to retrieve, transform, and act on content in Box without extra configuration

  Developers and agents can now work together seamlessly, with Box content at the center. To learn more, visit our <Link href="/guides/cli">CLI documentation</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-02-20">
  ## Box AI API — Claude Sonnet 4.6 and Gemini 3.1 Pro now available

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been updated with the following models:

  * <Link href="/guides/box-ai/ai-models/aws-claude-4-6-sonnet-model-card">Claude Sonnet 4.6</Link> (Beta)
  * <Link href="/guides/box-ai/ai-models/google-gemini-3-1-pro-model-card">Gemini 3.1 Pro</Link> (Beta)

  <Note>
    Models offered in **Beta** mode have not been fully performance-tested at scale and are provided on an as-is basis.
  </Note>

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-02-18">
  ## Box Windows SDK `v6.5.0` released

  ### **Bug Fixes:**

  * **boxsdkgen:** Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-windows-sdk-v2#1377](https://github.com/box/box-windows-sdk-v2/issues/1377)) ([dbd17a9](https://github.com/box/box-windows-sdk-v2/commit/dbd17a92e3670f58357e70ec19cbfa22f089f412))
  * **boxsdkgen:** Fix casing for `PATCH` in `Network Client` ([box/box-codegen#913](https://github.com/box/box-codegen/issues/913)) ([box-windows-sdk-v2#1365](https://github.com/box/box-windows-sdk-v2/issues/1365)) ([c90bfaf](https://github.com/box/box-windows-sdk-v2/commit/c90bfafba4ac5d6b3a018d5c8291609e30ec2530))

  ### **New Features and Enhancements:**

  * **boxsdkgen:** add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-windows-sdk-v2#1379](https://github.com/box/box-windows-sdk-v2/issues/1379)) ([769f39f](https://github.com/box/box-windows-sdk-v2/commit/769f39f3b1504fbd48804fdb16bf7faf26893450))
  * **boxsdkgen:** Add configurable timeouts ([box/box-codegen#924](https://github.com/box/box-codegen/issues/924)) ([box-windows-sdk-v2#1404](https://github.com/box/box-windows-sdk-v2/issues/1404)) ([`5824149`](https://github.com/box/box-windows-sdk-v2/commit/5824149d9ea5c2c5ea81550f5ad01971aca04087))
  * **boxsdkgen:** add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-windows-sdk-v2#1395](https://github.com/box/box-windows-sdk-v2/issues/1395)) ([ab436df](https://github.com/box/box-windows-sdk-v2/commit/ab436dfeb06a158d105bd488b488174cc50df07b))
  * **boxsdkgen:** Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-windows-sdk-v2#1369](https://github.com/box/box-windows-sdk-v2/issues/1369)) ([04bc507](https://github.com/box/box-windows-sdk-v2/commit/04bc507abfab95a04a01152b7684fc63d27d3e27))
</Update>

<Update label="2026-02-18">
  ## Box Windows SDK `v10.6.0` released

  ### Bug Fixes

  * Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-windows-sdk-v2#1378](https://github.com/box/box-windows-sdk-v2/issues/1378)) ([d756351](https://github.com/box/box-windows-sdk-v2/commit/d756351f13b49da69e4fbd66fe274af38c5d56a1))
  * Fix casing for `PATCH` in `Network Client` ([box/box-codegen#913](https://github.com/box/box-codegen/issues/913)) ([box-windows-sdk-v2#1366](https://github.com/box/box-windows-sdk-v2/issues/1366)) ([53333a0](https://github.com/box/box-windows-sdk-v2/commit/53333a0a53a89435e277332e609f4981a19b547e))

  ### New Features and Enhancements

  * add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-windows-sdk-v2#1380](https://github.com/box/box-windows-sdk-v2/issues/1380)) ([8c18af1](https://github.com/box/box-windows-sdk-v2/commit/8c18af18b5b26e84f256e93a8eeefd7080b9708c))
  * Add configurable timeouts ([box/box-codegen#924](https://github.com/box/box-codegen/issues/924)) ([box-windows-sdk-v2#1403](https://github.com/box/box-windows-sdk-v2/issues/1403)) ([fed7629](https://github.com/box/box-windows-sdk-v2/commit/fed7629d663c2ac868d79855d3ba0236d6df6f77))
  * add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-windows-sdk-v2#1396](https://github.com/box/box-windows-sdk-v2/issues/1396)) ([29a5332](https://github.com/box/box-windows-sdk-v2/commit/29a5332490a994d955f4aae2285e1d6520c7ddfc))
  * Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-windows-sdk-v2#1371](https://github.com/box/box-windows-sdk-v2/issues/1371)) ([16e2c6a](https://github.com/box/box-windows-sdk-v2/commit/16e2c6a80c9cb2570220a9814b3a86576e22dcc1))
</Update>

<Update label="2026-02-17">
  ## New tools for remote Box MCP server

  We've added new tools to the [remote Box MCP server](/guides/box-mcp/tools) so AI agents can do more with Box content and collaboration.

  **Search**

  * **`search_files_metadata`** — Search for files using SQL-like metadata queries, with support for complex filtering, field selection, and folder scoping.

  **Box AI**

  * **`ai_extract_structured_from_fields_enhanced`** — Extract structured metadata from files using the Box AI Enhanced Extract Agent and custom field definitions.

  **Collaboration**

  * **`list_item_collaborations`** — List all existing collaborations on an item.

  **Hubs**

  * **`copy_hub`** — Create a copy of an existing Box Hub with all its structure and settings. The original hub stays unchanged.

  **Doc Gen**

  * **`get_docgen_template_by_id`** — Get details about a Doc Gen template.
  * **`list_docgen_templates`** — List all Box Doc Gen templates available to the authenticated user.
  * **`create_docgen_batch`** — Generate documents from a Doc Gen template by filling placeholder tags with provided data.

  For setup and client-side steps, see [Set up the MCP server](/guides/box-mcp/setup).

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-02-11">
  ## Box Python SDK `v4.4.0` released

  ### Bug Fixes

  * **boxsdkgen:** Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-python-sdk#1309](https://github.com/box/box-python-sdk/issues/1309)) ([`83f7014`](https://github.com/box/box-python-sdk/commit/83f701492131b3e6b92691658f0c81e5c0fa6630))

  ### New Features and Enhancements

  * **boxsdkgen:** add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-python-sdk#1310](https://github.com/box/box-python-sdk/issues/1310)) ([`cd3e910`](https://github.com/box/box-python-sdk/commit/cd3e910a73fb5bc8b2919924682d08ccd72b03cd))
  * **boxsdkgen:** add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-python-sdk#1329](https://github.com/box/box-python-sdk/issues/1329)) ([`db79b21`](https://github.com/box/box-python-sdk/commit/db79b2130315b23f4c8baee9609f6c376aa158f1))
  * **boxsdkgen:** Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-python-sdk#1305](https://github.com/box/box-python-sdk/issues/1305)) ([`8b19658`](https://github.com/box/box-python-sdk/commit/8b196585136120fa47a131e7850f03bae04b4ed5))
  * **boxsdk:** shared network client and token storage ([box-python-sdk#1299](https://github.com/box/box-python-sdk/issues/1299)) ([`246bac9`](https://github.com/box/box-python-sdk/commit/246bac9c31343ef4d16ab5a28899fa573e663e6e))
</Update>

<Update label="2026-02-11">
  ## Box Python SDK `v10.4.0` released

  ### Bug Fixes

  * Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-python-sdk#1304](https://github.com/box/box-python-sdk/issues/1304)) ([`d51b4ea`](https://github.com/box/box-python-sdk/commit/d51b4eac0a0e2cbb593871bd35e48f0e4cbe6693))

  ### New Features and Enhancements

  * add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-python-sdk#1311](https://github.com/box/box-python-sdk/issues/1311)) ([`9db7a80`](https://github.com/box/box-python-sdk/commit/9db7a80514e4d0c45baf05cd6823c88e6666b395))
  * add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-python-sdk#1331](https://github.com/box/box-python-sdk/issues/1331)) ([`fcca2a4`](https://github.com/box/box-python-sdk/commit/fcca2a47439189c2f4986596cdfd7d3c303c9ec2))
  * Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-python-sdk#1300](https://github.com/box/box-python-sdk/issues/1300)) ([`7a2c7e3`](https://github.com/box/box-python-sdk/commit/7a2c7e3596c352a3f4d1f73f57c8032bd02f8cdf))
</Update>

<Update label="2026-02-11">
  ## Box Node SDK `v4.4.0` released

  ### Bug Fixes

  * **boxsdk:** Bump `cypress/request` to fix `CVE-2025-15284` ([box-node-sdk#1309](https://github.com/box/box-node-sdk/issues/1309)) ([`bbd6b88`](https://github.com/box/box-node-sdk/commit/bbd6b88df606cc8c496b7a943a72ebb8f02f159c))
  * **boxsdkgen:** Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-node-sdk#1318](https://github.com/box/box-node-sdk/issues/1318)) ([`00305a0`](https://github.com/box/box-node-sdk/commit/00305a0d2c346bb23fa0039265933c5c7dd792c6))

  ### New Features and Enhancements

  * **boxsdkgen:** add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-node-sdk#1320](https://github.com/box/box-node-sdk/issues/1320)) ([`e8435d0`](https://github.com/box/box-node-sdk/commit/e8435d02ff7700bc0c3638c48a851f46d6a2bdec))
  * **boxsdkgen:** add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-node-sdk#1342](https://github.com/box/box-node-sdk/issues/1342)) ([`f77ee6b`](https://github.com/box/box-node-sdk/commit/f77ee6b454c4f1ecfa15e74085921c4efe72b84c))
  * **boxsdkgen:** Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-node-sdk#1310](https://github.com/box/box-node-sdk/issues/1310)) ([`4c89711`](https://github.com/box/box-node-sdk/commit/4c89711d2840e904f297b9b84d999cd9bd482a82))
</Update>

<Update label="2026-02-11">
  ## Box Node SDK `v10.4.0` released

  ### Bug Fixes

  * Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-node-sdk#1319](https://github.com/box/box-node-sdk/issues/1319)) ([`c14bb0d`](https://github.com/box/box-node-sdk/commit/c14bb0d84c92cbd8b86749b00b51d29a394858c5))
  * Fix config to make `esm` build `esm` compatible ([box/box-codegen#915](https://github.com/box/box-codegen/issues/915)) ([box-node-sdk#1315](https://github.com/box/box-node-sdk/issues/1315)) ([`ecb8967`](https://github.com/box/box-node-sdk/commit/ecb89678f13ac2a2f0505f9531e1cb44a97da1ff))

  ### New Features and Enhancements

  * add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-node-sdk#1321](https://github.com/box/box-node-sdk/issues/1321)) ([`e7738ba`](https://github.com/box/box-node-sdk/commit/e7738bac1d598bf619697a9aa32c2ed463e653e8))
  * add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-node-sdk#1343](https://github.com/box/box-node-sdk/issues/1343)) ([`f4def35`](https://github.com/box/box-node-sdk/commit/f4def35f3e06c0ff01922dc6bc0cb344d01b63c0))
  * Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-node-sdk#1312](https://github.com/box/box-node-sdk/issues/1312)) ([`92a3ed4`](https://github.com/box/box-node-sdk/commit/92a3ed4cc9f82cae7133a4e4eeefdf8181d7fe81))
</Update>

<Update label="2026-02-11">
  ## Box iOS SDK `6.4.0` released

  ### Bug Fixes

  * **boxsdkgen:** Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-ios-sdk#1375](https://github.com/box/box-ios-sdk/issues/1375)) ([`d16f003`](https://github.com/box/box-ios-sdk/commit/d16f003c1a4ec93e7d7dac59d3636ef54ac162be))

  ### New Features and Enhancements

  * **boxsdkgen:** add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-ios-sdk#1378](https://github.com/box/box-ios-sdk/issues/1378)) ([`26bf4de`](https://github.com/box/box-ios-sdk/commit/26bf4de255953975b4865f943b71d4e1c5feca0a))
  * **boxsdkgen:** add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-ios-sdk#1394](https://github.com/box/box-ios-sdk/issues/1394)) ([`8526aa6`](https://github.com/box/box-ios-sdk/commit/8526aa6063315c6140b3742562222940dec87d79))
  * **boxsdkgen:** Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-ios-sdk#1367](https://github.com/box/box-ios-sdk/issues/1367)) ([`abe6e2c`](https://github.com/box/box-ios-sdk/commit/abe6e2cf6fb6866a13d51828ac1e5d721fe22395))
</Update>

<Update label="2026-02-11">
  ## Box iOS SDK `10.4.0` released

  ### Bug Fixes

  * Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-ios-sdk#1376](https://github.com/box/box-ios-sdk/issues/1376)) ([`a11c3dc`](https://github.com/box/box-ios-sdk/commit/a11c3dc50c470069e78dad858d660b03bf1d709a))

  ### New Features and Enhancements

  * Add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-ios-sdk#1379](https://github.com/box/box-ios-sdk/issues/1379)) ([`98285ef`](https://github.com/box/box-ios-sdk/commit/98285ef4739599d97bb77d0accfed13093d89a16))
  * Add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-ios-sdk#1395](https://github.com/box/box-ios-sdk/issues/1395)) ([`bad6e70`](https://github.com/box/box-ios-sdk/commit/bad6e70e31f415a2d3b7bfd645146142f269a854))
  * Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-ios-sdk#1369](https://github.com/box/box-ios-sdk/issues/1369)) ([`46bd796`](https://github.com/box/box-ios-sdk/commit/46bd796b50acf736406657fe6dc8950f4c514773))
</Update>

<Update label="2026-02-11">
  ## Box Java SDK `v5.4.0` released

  ### Bug Fixes

  * **boxsdkgen:** Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-java-sdk#1694](https://github.com/box/box-java-sdk/issues/1694)) ([`4620812`](https://github.com/box/box-java-sdk/commit/46208121ea5db23562b0b3c2875a0e24d12bff97))
  * **boxsdkgen:** Move assigning default values from builder constructor to `build()` method ([box/box-codegen#922](https://github.com/box/box-codegen/issues/922)) ([box-java-sdk#1712](https://github.com/box/box-java-sdk/issues/1712)) ([`aa962a0`](https://github.com/box/box-java-sdk/commit/aa962a07fda8847b4beb3a0d4bac504bd13f3cb5))

  ### New Features and Enhancements

  * **boxsdkgen:** add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-java-sdk#1696](https://github.com/box/box-java-sdk/issues/1696)) ([`241b5f2`](https://github.com/box/box-java-sdk/commit/241b5f22ee2b62cc8bda6166cc8c47f98bfd5eca))
  * **boxsdkgen:** add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-java-sdk#1720](https://github.com/box/box-java-sdk/issues/1720)) ([`f838a35`](https://github.com/box/box-java-sdk/commit/f838a35286768d7a551b5053780b245a4bfb85c4))
  * **boxsdkgen:** Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-java-sdk#1686](https://github.com/box/box-java-sdk/issues/1686)) ([`d13c98b`](https://github.com/box/box-java-sdk/commit/d13c98bb5caaada6fc819e964538edb9c79986e8))
</Update>

<Update label="2026-02-11">
  ## Box Java SDK `v10.5.0` released

  ### Bug Fixes

  * Correct enum value for legal hold policy changes ([box/box-openapi#581](https://github.com/box/box-openapi/issues/581)) ([box-java-sdk#1695](https://github.com/box/box-java-sdk/issues/1695)) ([`f9e3d5e`](https://github.com/box/box-java-sdk/commit/f9e3d5ee3c54d074d5b5aef1c5c01599c0b8c9e9))
  * Move assigning default values from builder constructor to `build()` method ([box/box-codegen#922](https://github.com/box/box-codegen/issues/922)) ([box-java-sdk#1716](https://github.com/box/box-java-sdk/issues/1716)) ([`0a9dbe3`](https://github.com/box/box-java-sdk/commit/0a9dbe3bebb618a0a33c53cd1e9a90582c0504e2))

  ### New Features and Enhancements

  * add confidence scores for structured extract ([box/box-openapi#582](https://github.com/box/box-openapi/issues/582)) ([box-java-sdk#1697](https://github.com/box/box-java-sdk/issues/1697)) ([`112b954`](https://github.com/box/box-java-sdk/commit/112b9545d0ef1839d007bf215356b31e658daad8))
  * add signer language, cancel sign request reason ([box/box-openapi#584](https://github.com/box/box-openapi/issues/584)) ([box-java-sdk#1721](https://github.com/box/box-java-sdk/issues/1721)) ([`3c94cfc`](https://github.com/box/box-java-sdk/commit/3c94cfc69d6be2db40b72bf2902ee095824e0796))
  * Add watermarking permissions and sources information ([box/box-openapi#579](https://github.com/box/box-openapi/issues/579)) ([box-java-sdk#1688](https://github.com/box/box-java-sdk/issues/1688)) ([`215c0f3`](https://github.com/box/box-java-sdk/commit/215c0f3cce4042332373eec66b1695ed958f1f3b))
</Update>

<Update label="2026-02-11">
  ## Box UI Elements `v26.3.0` released

  ### [26.3.0](https://github.com/box/box-ui-elements/compare/v26.2.0...v26.3.0) (2026-02-11)

  ### Bug Fixes

  * **content-sharing:** Fix create shared link bug ([box-ui-elements#4443](https://github.com/box/box-ui-elements/issues/4443)) ([`8cffb09`](https://github.com/box/box-ui-elements/commit/8cffb09e846b9534c08f2eb367e535b2982f09db))
  * **preview:** annotation delete modal z-index ([box-ui-elements#4445](https://github.com/box/box-ui-elements/issues/4445)) ([`6655e8d`](https://github.com/box/box-ui-elements/commit/6655e8dce42a37f3fb4835c462088e61536f9a74))
  * USM text input not taking up full width ([box-ui-elements#4435](https://github.com/box/box-ui-elements/issues/4435)) ([`7036b71`](https://github.com/box/box-ui-elements/commit/7036b71667966cd343582920208e88e86feb89d3))

  ### Features

  * **content-sharing:** bump usm version for desktop view ([box-ui-elements#4442](https://github.com/box/box-ui-elements/issues/4442)) ([`8c84972`](https://github.com/box/box-ui-elements/commit/8c8497289b281522a0f06dad13d92184c025a806))
  * **content-sidebar:** implement for custom sidebar panels ([box-ui-elements#4326](https://github.com/box/box-ui-elements/issues/4326)) ([`7148457`](https://github.com/box/box-ui-elements/commit/71484576271471d445532ad10852cdda01ebcf62))
</Update>

<Update label="2026-02-06">
  ## Box AI API — new AI models available

  The list of <Link href="/guides/box-ai/ai-models">available AI models</Link> has been recently updated with the following models:

  * <Link href="/guides/box-ai/ai-models/aws-claude-4-6-opus-model-card">AWS Claude Opus 4.6</Link> (Beta)
  * <Link href="/guides/box-ai/ai-models/openai-gpt-5-2-model-card">OpenAI GPT-5.2</Link>
  * <Link href="/guides/box-ai/ai-models/google-gemini-3-flash-model-card">Gemini 3 Flash</Link> (Beta)

  <Note>
    Models offered in **Beta** mode have not been fully performance-tested at scale and are provided on an as-is basis.
  </Note>

  You can use the provided models to <Link href="/guides/box-ai/ai-agents/ai-agent-overrides">override the default model</Link> used in the AI agent configuration.
  For further details on Box AI API, see the <Link href="/guides/box-ai">guides</Link> and <Link href="/reference/post-ai-ask">API reference</Link>.

  ## Where to get support

  Should you have any issues or need further guidance, please post a request to our [developer forum](https://forum.box.com/) for any help needed.
</Update>

<Update label="2026-01-15">
  ## Box UI Elements `v26.1.0` released

  ### [26.1.0](https://github.com/box/box-ui-elements/compare/v26.0.0...v26.1.0) (2026-01-15)

  ### Bug Fixes

  * **content-sharing:** add error handler ([box-ui-elements#4414](https://github.com/box/box-ui-elements/issues/4414)) ([`81b0071`](https://github.com/box/box-ui-elements/commit/81b007165a0e9c1d9bf1dee899398281e5256b89))
  * **content-sharing:** improve content sharing performance and add consumer ability to override config ([box-ui-elements#4413](https://github.com/box/box-ui-elements/issues/4413)) ([`788b32f`](https://github.com/box/box-ui-elements/commit/788b32f8926b82662994180be67a70058bd6431d))
  * **docgen-sidebar:** modernized blueprint dropdown (`DOCGEN-7872`) ([box-ui-elements#4392](https://github.com/box/box-ui-elements/issues/4392)) ([`5fd9164`](https://github.com/box/box-ui-elements/commit/5fd9164384922096649a2d64e66e5e0ad1226d2c))
  * **i18n:** update translations ([box-ui-elements#4419](https://github.com/box/box-ui-elements/issues/4419)) ([`5ba3e69`](https://github.com/box/box-ui-elements/commit/5ba3e69c3fab80082d80f3bd4d87e7426d00abed))

  ### Features

  * **content-sidebar:** add ability to defer sidebar data fetching requests ([box-ui-elements#4410](https://github.com/box/box-ui-elements/issues/4410)) ([`69be418`](https://github.com/box/box-ui-elements/commit/69be41850cad033b0badb1c53ad9571813eaaa6a))
  * **deps:** bump blueprint-web to 12.115.2 ([box-ui-elements#4415](https://github.com/box/box-ui-elements/issues/4415)) ([`c60dd13`](https://github.com/box/box-ui-elements/commit/c60dd136558eaa4b3cf18e56d57ba48da8ec14f5))
  * **deps:** bump qs version ([box-ui-elements#4417](https://github.com/box/box-ui-elements/issues/4417)) ([`9f174dc`](https://github.com/box/box-ui-elements/commit/9f174dccbc0d7f985902eb3584c00e922b2eb90b))
  * **preview:** add `minimalFile` prop for content sidebar to render faster ([box-ui-elements#4412](https://github.com/box/box-ui-elements/issues/4412)) ([`70e2846`](https://github.com/box/box-ui-elements/commit/70e28463e03226d3d6901655ab3057f96d48df99))
</Update>

<Update label="2026-01-05">
  ## Box UI Elements `v26.0.0` released

  ### [26.0.0](https://github.com/box/box-ui-elements/compare/v25.5.0...v26.0.0) (2026-01-05)

  ### Features

  * **react-tether:** BREAKING CHANGE Bump BUIE to React 19 ([box-ui-elements#4278](https://github.com/box/box-ui-elements/issues/4278)) ([`02bc171`](https://github.com/box/box-ui-elements/commit/02bc1710bc41513e0faf57adca19e6c6c1317b7d))

  ### BREAKING CHANGES

  * **react-tether:** React 17 is no longer supported. This package now
    requires React 18 or 19. react-tether has been upgraded to v3, so
    components using react-tether may affect some layouts.

  * fix: update `.flowconfig` to take `.cjs`

  * fix: replace `Checkbox`, `InfoIcon`, and `FooterIndicator` tooltips with BP

  * fix: use `createRoot` instead of `ReactDOM` render

  * fix: respond to feedback

  * fix: round 2

  * fix: flow tests for `SidebarNavButton`

  * fix: legacy comment styling
</Update>

<Update label="2026-01-05">
  ## Box UI Elements `v25.5.0` released

  ### [25.5.0](https://github.com/box/box-ui-elements/compare/v25.4.0...v25.5.0) (2026-01-05)

  ### Bug Fixes

  * **classification:** preload component in jest ([box-ui-elements#4403](https://github.com/box/box-ui-elements/issues/4403)) ([`8aaa6a1`](https://github.com/box/box-ui-elements/commit/8aaa6a15de1e94557600c7d57c9c785c2e11c701))
  * **i18n:** update translations ([box-ui-elements#4396](https://github.com/box/box-ui-elements/issues/4396)) ([`03bd678`](https://github.com/box/box-ui-elements/commit/03bd678f1f10beb3d624de6c446fac9f5ce46564))
  * **i18n:** update translations ([box-ui-elements#4400](https://github.com/box/box-ui-elements/issues/4400)) ([`83917df`](https://github.com/box/box-ui-elements/commit/83917dfc3901290c14c1828e3347b9aa8b88521d))
  * **i18n:** update translations ([box-ui-elements#4408](https://github.com/box/box-ui-elements/issues/4408)) ([`7f16b5a`](https://github.com/box/box-ui-elements/commit/7f16b5a8909ef163c8f1243017f338ef73498ecd))
  * **preview:** add preview sdk load check ([box-ui-elements#4391](https://github.com/box/box-ui-elements/issues/4391)) ([`5555899`](https://github.com/box/box-ui-elements/commit/5555899acadb7885f6832f6e86c829464d64dd0c))
  * Replace `defaultProps` with inline defaults ([box-ui-elements#4385](https://github.com/box/box-ui-elements/issues/4385)) ([`72e7fbf`](https://github.com/box/box-ui-elements/commit/72e7fbfdf2a08e8adecdab6f3bebf0fd95c9e82e))
  * **timestamped-comments:** replacing dash container class with media container ([box-ui-elements#4409](https://github.com/box/box-ui-elements/issues/4409)) ([`953b6f6`](https://github.com/box/box-ui-elements/commit/953b6f67df1966c897d9dec7fcebdc92b7c5a5a0))
  * update glob 10.x dependency ([box-ui-elements#4404](https://github.com/box/box-ui-elements/issues/4404)) ([`f59e209`](https://github.com/box/box-ui-elements/commit/f59e209b83667cf36a062838e0db4f40d7b7a66b))
  * update storybook dependencies ([box-ui-elements#4406](https://github.com/box/box-ui-elements/issues/4406)) ([`7c2546c`](https://github.com/box/box-ui-elements/commit/7c2546cbca0c8e68366b8abcc8dd85e0ca7075e2))
  * **video-annotations:** changing test wording ([box-ui-elements#4394](https://github.com/box/box-ui-elements/issues/4394)) ([`f885f8c`](https://github.com/box/box-ui-elements/commit/f885f8c2bfc7aaa8cacb2ecb260ae86cc9a38874))
  * **video-annotations:** fix video annotation version change issue ([box-ui-elements#4380](https://github.com/box/box-ui-elements/issues/4380)) ([`121de79`](https://github.com/box/box-ui-elements/commit/121de79d76a69338682ac2c3294cfd84f7a31d52))
  * **video-annotations:** sidebar button fix to not propagate mousedown event ([box-ui-elements#4388](https://github.com/box/box-ui-elements/issues/4388)) ([`454ede0`](https://github.com/box/box-ui-elements/commit/454ede01675fc5e9cbdf94655272699a0502f16c))

  ### Features

  * **metadata-editor:** parse autofill values correctly for taxonomy fields ([box-ui-elements#4398](https://github.com/box/box-ui-elements/issues/4398)) ([`65f764d`](https://github.com/box/box-ui-elements/commit/65f764d765f55d8047e7066a490a07a80d039ec5))
  * **sidebar-nav:** update skills and docgen icons to BP (`WEBAPP-42958`) ([box-ui-elements#4399](https://github.com/box/box-ui-elements/issues/4399)) ([`e63cd39`](https://github.com/box/box-ui-elements/commit/e63cd39998f4e36340bd0afdd5be66bbb8c992bc))
</Update>


# Box Mount
Source: https://developer.box.com/guides/box-mount

Mount a Box folder into an agent runtime as a POSIX filesystem, kept in two-way sync, with Box permissions and governance applied to every operation.

Box Mount brings Box content into any agent runtime as a standard POSIX filesystem. Agents read, write, and edit files using familiar file operations, with Box security, governance, and access controls applied to every operation. Continuous two-way sync keeps agent and Box content aligned, so people and agents collaborate in the same folders with built-in conflict protection.

<Note>
  Box Mount is in private preview. It is not publicly available, it is not covered by a production SLA, and features can change before general availability. Box provides the binary and setup guidance to preview participants. To request access, complete the [Box Mount private preview form](https://bit.ly/box-mount-preview).
</Note>

## How Box Mount works

Box Mount runs a background sync process, the daemon, that maps a Box folder to a local directory inside the sandbox your product provisions. It works with any supported Linux sandbox, including Daytona, Docker, E2B, and Vercel Sandbox, and is not tied to one vendor.

* **Content stays in Box.** Your agent works against a local path, and every operation flows through the Box API.
* **Governance follows the content.** Every operation runs as the identity Box Mount authenticates with, so that identity's permissions, retention, legal hold, ethical walls, and audit trail apply to the agent, along with any Box Shield security policies driven by classification. In OAuth mode the identity is the user who authorized the app, so the agent can never reach content that the user cannot. In JWT mode the identity is the service account, so scope that account to the content the agent needs.
* **Sync runs both ways.** Changes an agent makes in the mount upload to Box, and updates from people or other agents are reflected back in the mount.
* **Conflicts are preserved, not overwritten.** When two writers change the same file at the same time, Box Mount detects the conflict at upload and keeps both results, either as a new Box version or as a separate conflict copy, so a reviewer can merge the work or roll back using Box version history.

Because the agent works with plain files, most tools work against Box content without knowing it is Box. Read [Known limitations](#known-limitations) first, because applications that save a file by replacing it rather than editing it in place behave differently.

## See Box Mount in action

This demo builds a contract review agent that mounts a Box folder into an E2B sandbox, runs the agent against that workspace, and syncs the finished review back to Box for a person to review.

<iframe title="Build a Contract Review Agent with Box Mount and E2B" />

For the architecture behind the demo and more workflow patterns, read [Meet Box Mount: A Box workspace for sandboxed AI agents](https://blog.box.com/meet-box-mount-box-workspace-sandboxed-ai-agents) on the Box blog.

## Before you begin

You need:

* Access to the Box Mount private preview, including the Box Mount binary. To request access, complete the [Box Mount private preview form](https://bit.ly/box-mount-preview).
* A Box app in the [Developer Console](https://app.box.com/developers/console), configured for either [OAuth 2.0](/guides/authentication/oauth2/oauth2-setup) or [JWT](/guides/authentication/jwt/jwt-setup) authentication.
* The ID of the Box folder you want to mount. This is the number at the end of the folder URL on Box.

### Supported platforms

Box Mount supports Linux runtimes on the x86\_64 and ARM64 architectures. macOS is not supported.

## Commands

| Command | What it does |
| - | - |
| `box-mount config` | Configures credentials and sync settings interactively |
| `box-mount mount "<local-dir>" "<box-id>"` | Mounts a Box folder to `<local-dir>`, an absolute local path. `<box-id>` is the Box folder ID |
| `box-mount status` | Reports the state of the current mount |
| `box-mount unmount "<local-dir>"` | Unmounts the local directory, using its absolute path |
| `box-mount unmount --reset-force "<local-dir>"` | Unmounts and force-deletes all local mount contents |

A first session looks like this:

```bash theme={null}
box-mount config
mkdir -p /mnt/box
box-mount mount "/mnt/box" "123456789"
box-mount status
```

Your agent now works against `/mnt/box`.

## Configure credentials

Box Mount reads Box credentials from a `box-config.json` file in `~/.box-mount/`, or in the path you pass to `--data-path`.

The `config` command handles configuration interactively in one step and writes `~/.box-mount/box-config.json`:

```bash theme={null}
box-mount config
```

Box Mount supports two authentication modes, OAuth and JWT. OAuth is the default. Enter `oauth` or `jwt` when prompted. Restrict the config file, and any JWT private key JSON it points at, as described in [Secure your credentials](#secure-your-credentials).

### Configure OAuth manually

Create `~/.box-mount/box-config.json` and fill in your Box app credentials:

```json theme={null}
{
  "client_id":     "YOUR_BOX_CLIENT_ID",
  "client_secret": "YOUR_BOX_CLIENT_SECRET",
  "access_token":  "",
  "refresh_token": "",
  "redirect_uri":  "http://localhost:3000/callback"
}
```

| Field | Required | Notes |
| - | - | - |
| `client_id` | Yes | From the Developer Console |
| `client_secret` | Yes | From the Developer Console |
| `access_token` | Yes | Run `box-mount config` to obtain one through OAuth |
| `refresh_token` | OAuth only | Run `box-mount config` to obtain one through OAuth. Rotated on every refresh |
| `redirect_uri` | No | Must match the Box app setting exactly. Used when configuring OAuth |

The OAuth config has no `auth_type` field because OAuth is the default mode. Set `auth_type` only to switch to JWT.

### Configure JWT manually

For a JWT service account, the config needs only two fields:

```json theme={null}
{
  "auth_type": "jwt",
  "jwt_config_path": "/path/to/box-jwt-config.json"
}
```

| Field | Required | Notes |
| - | - | - |
| `auth_type` | Yes | Must be `jwt` |
| `jwt_config_path` | Yes | Absolute path to the Developer Console JWT JSON |

`jwt_config_path` must point to the JSON file generated by the Developer Console. To create it, open your app's **Configuration** tab and, in **App Settings**, select **Generate a Public/Private Keypair**. JWT authentication does not need an `access_token` or a `refresh_token`, because the SDK obtains short-lived access tokens automatically.

### Use environment variables

You can supply credential fields through environment variables instead of the JSON file. Environment variables take precedence over file values, and the JSON file is optional when you provide every required field this way.

| Variable | Config key | Notes |
| - | - | - |
| `BOX_CLIENT_ID` | `client_id` | OAuth app client ID |
| `BOX_CLIENT_SECRET` | `client_secret` | OAuth app client secret |
| `BOX_ACCESS_TOKEN` | `access_token` | Current access token. Updated in-process and written back to the config file on refresh |
| `BOX_REFRESH_TOKEN` | `refresh_token` | Current refresh token. Same write-back behavior as the access token |
| `BOX_AUTH_TYPE` | `auth_type` | Set to `jwt` to enable JWT mode |
| `BOX_JWT_CONFIG_PATH` | `jwt_config_path` | Path to the Developer Console JWT JSON. JWT mode only |

<Warning>
  Do not persist `BOX_ACCESS_TOKEN` or `BOX_REFRESH_TOKEN` in shell startup files such as `.zprofile` or `.bashrc`. When Box Mount refreshes tokens it writes the new values to `~/.box-mount/box-config.json`, which leaves any copies baked into the environment stale, and stale tokens cause authentication failures on the next run. Export these variables only for the duration of a session.

  Do not put `BOX_*` credentials in the environment of an LLM agent or any other untrusted process. See [Secure your credentials](#secure-your-credentials).
</Warning>

### Use a developer token

[Developer tokens](/guides/authentication/tokens/developer-tokens) are short-lived tokens you generate in the Developer Console. They are valid for 60 minutes, cannot be refreshed, and are useful for quick testing without the full OAuth flow.

Set `access_token` in `~/.box-mount/box-config.json` and leave `refresh_token` empty:

```json theme={null}
{
  "client_id":     "YOUR_BOX_CLIENT_ID",
  "client_secret": "YOUR_BOX_CLIENT_SECRET",
  "access_token":  "PASTE_DEVELOPER_TOKEN_HERE",
  "refresh_token": ""
}
```

You can also pass the token through the environment and skip the config file:

```bash theme={null}
export BOX_ACCESS_TOKEN="PASTE_DEVELOPER_TOKEN_HERE"
box-mount mount "/local/path" "123456789"
```

Because developer tokens cannot be refreshed, Box Mount stops syncing when the token expires. Generate a new token in the Developer Console and update `access_token`, or re-export the environment variable, to resume.

## Token lifecycle

In OAuth mode:

* Access tokens expire after about 60 minutes, and the SDK refreshes them automatically.
* Each refresh rotates the refresh token, and the old one is invalidated immediately.
* Rotated tokens are written back to `~/.box-mount/box-config.json`.
* Refresh tokens expire after 60 days without use. Run `box-mount config` again to repeat the OAuth flow.

In JWT mode:

* The SDK signs a JWT assertion, exchanges it for a short-lived access token, and refreshes that token automatically. Tokens are held in memory only, so nothing is written to `box-config.json`.
* Authentication needs no user interaction as long as the JWT config JSON and private key are valid.

## Secure your credentials

Box credentials are a Box API identity, and that identity is usually broader than the folder you mount. This applies to the OAuth client secret and tokens in `box-config.json`, the `BOX_*` environment variables, and the JWT private key JSON on disk. Anyone who reads them can call the Box API as that app or user, not only read the files in the mount.

The daemon that `box-mount mount` starts needs those credentials, and the mount directory is the only surface other processes should share. Keep `~/.box-mount/`, which holds the config, database, process ID, and logs, private to the account that runs Box Mount.

### Recommended setup on an agent sandbox

When an LLM agent runs on the same machine as Box Mount, do not run the agent as the same Unix user as the daemon. Use two users:

| Role | Unix user | What it can access |
| - | - | - |
| Box Mount daemon | User A | `~/.box-mount/`, the JWT JSON, and the mount directory |
| LLM agent | User B | The mount directory only |

1. Create the two users. Run `box-mount config` as user A so that `~/.box-mount/` lives in the home directory of user A. Do not mount yet, because bootstrap fills the tree and the share permissions must be set on an empty mount directory first.

2. Restrict the credentials so that only user A can read them, then confirm ownership with `ls -l`. Mode `644`, which is world-readable, is not appropriate for these files.

   ```bash theme={null}
   chmod 700 ~/.box-mount
   chmod 600 ~/.box-mount/box-config.json
   chmod 600 /path/to/box-jwt-config.json   # JWT mode only
   ```

3. Share only the mount directory with user B, using a shared group, setgid, and a default POSIX ACL. Setgid copies group ownership onto new inodes, and the default ACL inherits group write access. Apply this to an empty directory, then mount. The `setfacl` command ships in the `acl` package.

   ```bash theme={null}
   sudo mkdir -p /path/to/mount
   sudo groupadd boxmount
   sudo usermod -aG boxmount userA
   sudo usermod -aG boxmount userB
   sudo chown userA:boxmount /path/to/mount
   sudo chmod 2770 /path/to/mount
   sudo setfacl -m g:boxmount:rwx -m d:g:boxmount:rwx /path/to/mount
   box-mount mount "/path/to/mount" "<box-id>"   # as user A
   ```

   User B must not have read access to the home directory of user A, to `--data-path`, or to the JWT file. User B must also be able to traverse every directory above the mount, which is why the example puts the mount outside any home directory. If you place the mount inside the home directory of user A instead, a home directory set to `750` blocks user B even when the mount directory itself is `2770`.

4. Start the agent as user B. Do not export `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET`, `BOX_ACCESS_TOKEN`, `BOX_REFRESH_TOKEN`, or `BOX_JWT_CONFIG_PATH` in the shell, systemd unit, or container spec of the agent. Those values are visible in the process environment and belong only to the daemon process of user A.

5. In JWT mode, use a service account scoped to the content the agent needs, rather than an enterprise admin keypair.

On a personal machine, where you are the only process using the mount, running Box Mount as your own user is expected, and follows the same model as SSH keys in `$HOME`. That layout is not appropriate when the other process is an untrusted agent.

<Warning>
  This isolation does not protect against root on the machine, kernel exploits, or running the agent as user A. It also does not reduce what the agent can do inside the mount, because user B has normal filesystem access to that tree.
</Warning>

## Data and log locations

By default, `--data-path` points to `~/.box-mount/`, and Box Mount derives all other paths from it:

| Path | Contents |
| - | - |
| `~/.box-mount/mount.json` | Mount record |
| `~/.box-mount/box-config.json` | Box credentials |
| `~/.box-mount/local-config.json` | Local sync settings |
| `~/.box-mount/data/` | `sync.sqlite3`, `bdlc.pid`, and `teardown.json`, which is present only during an incomplete reset or unmount |
| `~/.box-mount/logs/` | `box-mount-sync.stdout.log` and `box-mount-sync.stderr.log` for daemon output, plus a `box-mount-sync-YYYYMMDD-HHMMSS-ffffff.log` file for each run |

Treat this tree as private to the daemon. See [Secure your credentials](#secure-your-credentials).

## Known limitations

### No support for atomic save

Box Mount does not support atomic save, also called safe write, where an application saves a file by writing a temporary file and renaming it over the original instead of editing in place. Files saved this way lose their Box version history, because Box Mount syncs the replacement as a new file rather than as a new version of the existing file.

### Workload limits

For the preview, use non-production workloads of up to 5 GB of content and 10,000 files per mount.

## Related tools

Box Mount complements the other ways agents reach Box content. Use Box Mount when an agent needs to do file work in place, and use the following tools for API-level and command-line access:

| Tool | Use it for |
| - | - |
| [Box MCP server](/guides/box-mcp) | Giving agents tool-based access to Box search, Box AI, and file operations |
| [Box CLI](/guides/cli) | Running routine or bulk Box actions from the command line |
| [Box SDKs](/guides/tooling/sdks) | Building applications directly against the Box API |


# Box CLI with JWT Authentication
Source: https://developer.box.com/guides/cli/cli-with-jwt-authentication/jwt-cli



<RelatedLinks title="REQUIRED GUIDES" />

Previously, our <Link href="/guides/cli">Box CLI Quick Start Guide</Link>, followed the JWT or server
authentication application setup flow. Since we released a new OAuth 2.0
version of the Box CLI, we updated it to use the new feature. We migrated
the original JWT setup instructions here, in case you would still like
to use the server authentication application type.

## Setup a JWT application

The first step to using the CLI with server authentication is creating a Box
application in the
[Developer Console][dc], which the CLI can use behind the scenes to make API
calls. If you would like to associate your CLI with an existing JWT application
you can skip this step. However, you will want to ensure that, at a minimum, the
following scopes are set in the **Configuration** tab of your application:

* Read all files and folders stored in Box
* Write all files and folders stored in Box

1. From the left-hand navigation panel on your All Files page, open the [Developer Console][dc]. If this is your first time using the Box API and this option is not already available, you can add it to your account by clicking [here][dc].

2. Click **Create Platform App** > **Platform App** > **Server Authentication (with JWT)** > name the application > **Create App**

<Warning>
  Server Authentication (with JWT) always requires Admin authorization before use.
</Warning>

## Configure the application

This brings you to the application's configuration page where you need to
choose its access and permissions. Again, keep in mind that because of the
application's authentication type, it requires Admin approval.

At a minimum, you need the following <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link>:

* Read all files and folders stored in Box
* Write all files and folders stored in Box

You can choose either App Access Only or App + Enterprise Access as the
<Link href="/guides/authentication/jwt/jwt-setup/#application-access">application access</Link>.

## Authorize the application

All applications leveraging Server Authentication must be authorized in the
Admin Console before making successful API calls. This is because all JWT
applications have a <Link href="/guides/getting-started/users#service-account">Service Account</Link>, which, based on the application's
<Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link>, may be able to perform Admin actions.

Steps for developers and Admins can be found in our <Link href="/guides/authorization/platform-app-approval">authorization guide</Link>.

If you would like more information on how scopes, application access, tokens,
and permissions work together, please see our article on understanding
[Box's security mechanisms][blogpost].

<Warning>
  If configuration changes are made to this application, it will need to be
  reauthorized in order for the changes to take effect.
</Warning>

You will know when an application is ready for use by visiting its Authorization
tab in the [Developer Console][dc]. The state and status must be enabled and
authorized.

<Frame>
  <img alt="App Authorized" />
</Frame>

## Download Required Data

The CLI needs a configuration file stored locally in order to make API calls.

To download the configuration file, visit the **Configuration** tab in the
[Developer Console][dc]. Click **Generate a Public/Private Keypair**, which will
send you through 2FA verification before automatically downloading the
configuration file for your application. For more information see
our <Link href="/guides/authentication/jwt/jwt-setup/#public-and-private-key-pair">guide</Link>.

<Warning>
  For security reasons 2FA must be enabled on your Box account to successfully
  generate a public/private keypair.
</Warning>

Locate the downloaded file on your machine which has a default name in the
format: `EnterpriseID_publicKeyID_config.json`. You may leave this name or
choose to rename it. This guide assumes the file is renamed to `config.json`.

<Warning>
  It is critical you place the file in a location where it will not be
  inadvertently deleted or moved. If this occurs you will need to repeat
  step 2 to reconfigure the CLI.
</Warning>

## CLI Installation and Configuration

The CLI can be installed as a Node package on any platform,
including Linux. For this to work you will need to have
[Node JS](https://nodejs.org/) installed on your machine.

```bash theme={null}
npm install --global @box/cli
```

## Source Code

The source code for the CLI is available via [GitHub][cli].

## Run configuration command

You will now need to configure the CLI to point to the configuration file
downloaded in step 1.

<Frame>
  <div>
    <img alt="CLI Configuration Diagram" />
  </div>
</Frame>

Open your terminal or command line and execute the
command: `box configure:environments:add PathToConfigFileHere`, replacing
`PathToConfigHere` with the path to your `config.json` file.

For example:
`box configure:environments:add /Users/ExampleUser/Documents/CLI/config.json`

<Tip>
  You can drag the csv file from the Finder/File Explorer to the
  terminal/command line window to auto-populate the path.
</Tip>

## Confirm configuration

To confirm successful configuration, use the command `box users:get`.

A successful response will provide details about the <Link href="/guides/getting-started/users#service-account">Service Account</Link> user
associated with your <Link href="/guides/authentication/tokens">Access Token</Link>:

```json theme={null}
Type: user
ID: ''0123456789''
Name: Box CLI - Quickstart Example
Login: AutomationUser_123456_8jSo6Lqvko@boxdevedition.com
Created At: '2020-01-01T09:45:01-07:00'
Modified At: '2021-03-01T09:30:05-07:00'
Language: en
Timezone: America/Los_Angeles
Space Amount: 999999999999999
Space Used: 6291500
Max Upload Size: 16106127360
Status: active
Job Title: ''
Phone: ''
Address: example+user@box.com
Avatar URL: ''
Notification Email: []
```

<Tip>
  By default, JWT applications automatically obtain an Access Token for the
  Service Account. It is possible to change the default user, but this guide
  assumes you do not do this.
</Tip>

## Next Steps

* You can checkout the [commands][commands] page on GitHub for example code.
* You can also go to the second part of the <Link href="/guides/cli/quick-start/build-commands-help">OAuth 2.0 Quick Start</Link> for a tutorial on how to use the commands.

[cli]: https://github.com/box/boxcli

[auth]: /guides/authentication/jwt/without-sdk

[dc]: https://account.box.com/developers/console

[blogpost]: https://medium.com/box-developer-blog/box-api-understanding-security-9fcad7b1d72e

[four]: /guides/cli/quick-start/using-bulk-commands

[cache]: https://github.com/box/boxcli/blob/master/docs/configure.md#box-configureenvironmentsupdate-name

[ac]: https://github.com/box/boxcli/blob/master/docs/autocomplete.md

[commands]: https://github.com/box/boxcli#command-topics

<RelatedLinks title="RELATED GUIDES" />


# Box Embed
Source: https://developer.box.com/guides/embed/box-embed



Box Embed is an HTML-based framework that allows embedding the entire
Box Web App experience in a custom-made application. Box Embed provides the ability to upload, search, comment, share, tag, and edit files using Box Edit. You can also embed Box Hubs AI Chat for a focused chatbot experience.

## Before you start

To create a widget, you need to:

* Set an embeddable element, such as a folder, file, hub, note, or app for sharing.
* Have at least **Viewer** [permissions][5].

## Using web app

To fetch the Box Embed widget code from the Box web app, perform the following steps.

### Files and folders

1. Navigate to the chosen file or folder.
2. Click on the ellipsis next to the folder.
3. Go to **More Actions** > **Embed Widget**.

### Hubs

1. Navigate to the chosen hub.
2. Click on the ellipsis menu in the upper-right corner.
3. Click **Embed Hub**.

<Note>
  You can also embed only the AI chat interface from a hub. Users can ask questions and get AI-powered answers based on the hub's files, without accessing navigation or file browsing features. For more information, see the <Link href="/guides/embed/box-embed/#box-hubs-ai-chat-embedding">Box Hubs AI Chat embedding</Link> section.
</Note>

### Notes

1. Navigate to the chosen note.
2. Click on the ellipsis menu.
3. Click **Embed Box Note**.

### Apps

1. Navigate to the chosen app or Box App View.
2. Click on the ellipsis menu.
3. Click **Embed**.

<Frame>
  <img alt="Box Embed" />
</Frame>

In the next step, configure the parameters of an embeddable element.

| Element Type | Configuration Options |
| - | - |
| Files | Size of the widget. |
| Folders | Size of the widget, sorting of the files in a folder, hiding the navigation path and sidebar. |
| Hubs | Size of the widget, hiding the parent navigation path and sidebar. |
| Hubs AI Chat | Chat mode: button or widget. |
| Notes | Size of the widget, hiding notes navigation. |
| Apps | Size of the widget. |

<Frame>
  <img alt="Box Embed Configuration" />
</Frame>

When you are done customizing the embed widget, copy
and paste the embed code into your site or web application.

## Programmatically

If you want to customize Box Embed even further, you can do it programmatically. The format for an embed snippet is as follows:

```html theme={null}
<iframe
  src="https://{custom_domain}.app.box.com/embed/s/{shared link value}?view={list or icon}&sortColumn={name, date, or size}&sortDirection=ASC"
  width="{pixels}"
  height="{pixels}"
  frameborder="0"
  <!-- Optionally replace * with your enterprise-specific domain (for example, mycompanydomain.app.box.com) -->
  allow="local-network-access *; clipboard-read *; clipboard-write *" 
  allowfullscreen
  webkitallowfullscreen
  msallowfullscreen>
</iframe>
```

### Browser permissions

The `allow` attribute enables clipboard operations and local network access for Google Chrome 142 and above and Microsoft Edge 143 and above. While designed for these browser versions, this attribute can be safely included for all browsers. Other browsers will ignore it.

Without this attribute, embedded Box content might not work correctly with Box Tools, Device Trust, or the clipboard copy button.

<Note>
  The Embed Widget Link Generation modal automatically includes this parameter in the generated code.
</Note>

### Finding your shared link value

The first step to building an embed `iframe` programmatically is to generate
or find the value for the shared link. One way to find this value is by
using the Box web app.

<Frame>
  <img alt="Box Share" />
</Frame>

Another way is to create a shared link with the API using the
<Link href="/reference/put-files-id--add-shared-link">`PUT /files/:file_id`</Link> or <Link href="/reference/put-folders-id--add-shared-link">`PUT /folders/:folder_id`</Link>.

Then you can find this shared link value using the
<Link href="/reference/get-files-id">`GET /files/:id`</Link> or <Link href="/reference/get-folders-id">`GET /folders/:id`</Link> endpoint and passing in the
query parameter `fields=shared_link`.

```curl theme={null}
curl https://api.box.com/2.0/folders/12345?fields=shared_link \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
"shared_link": {
  "url": "https://app.box.com/s/dsbJFzdO7qZxdfOHFzdO7qZxdfOH",
  "download_url": null,
  "vanity_url": null,
  ...
}
```

You can also set the page to Root Folder/All Files page. Set the URL to
`/folder/0` instead of the share link:
`<iframe src=“https://app.box.com/embed/folder/0”….></iframe>`

### Parameters

Next, you will want to choose your view customization options. The following is
a list of optional parameters you can configure.

| | |
| - | - |
| `hideHubsGallery` | Hide or show navigation chevron button to go back to Hubs gallery. Can be `true` or `false` (default). |
| `hideNavigationControls` | Hide or show navigation controls in Box Notes. |
| `hidePreviewCloseButton` | Hide or show navigation controls in Box Preview. |
| `showItemFeedActions` | Hide or show file comments or tasks. Can be `true` (default) or `false`. |
| `showParentPath` | Hide or show the folder path in the header of the frame. Can be `true` (default) or `false`. |
| `sortColumn` | The order the files or folders are sorted in. Can be `name`, `date` (default), or `size`. |
| `sortDirection` | The sort direction of files or folders. Can be `ASC` (default) or `DESC`. |
| `view` | The view type for your files or folders. Can be `list` (default) or `icon`. For logged-in users the view type from user preferences takes precedence. |
| `uxLite` | Show the simplified content preview (Preview Light). Works only for files and Box Notes. |

<Note>
  When you use `uxLite` with Box Notes, navigation controls are not displayed, regardless of the `hideNavigationControls` setting.
</Note>

All custom search parameters from the first-party app URL are passed to the embed widget modal and Content Preview.

### Full screen capabilities

To enable full screen capabilities for the Box Embed snippet, include one or more
of the following parameters if you want the object to be viewable in full screen
within an `<iframe>`:

* `allowfullscreen`
* `webkitallowfullscreen`
* `mozallowfullscreen`
* `oallowfullscreen`
* `msallowfullscreen`

## Box Hubs AI Chat embedding

In addition to embedding the complete Box Hub experience, you can embed only the AI-powered chat interface. This mode provides a focused chatbot experience powered by the files within a specific hub, without navigation or content browsing options.

### Prerequisites

To access a hub embedded in AI Chat mode:

* The enterprise that owns the hub must have Box AI for Hubs enabled.
* The user must be authenticated and have Box AI for Hubs enabled at their enterprise.
* The user needs at least Viewer [permissions][5] on the hub.

### Creating an AI Chat embed

1. Navigate to the hub that will serve as the knowledge source for the AI Chat.

2. Click the ellipsis menu in the upper-right corner.

3. Click **Embed Hub**.

4. Select the **Hub AI Chat** tab.

5. Select chat mode:

   * <Link href="/guides/embed/box-embed/#chat-button">Chat button</Link>
   * <Link href="/guides/embed/box-embed/#chat-widget">Chat widget</Link>

6. Copy the embed code.

<Note>
  If you experience issues with the Box Hubs AI Chat embedding, regenerate the embed code to get the latest version of the script by repeating steps 1-6 above.
</Note>

### Chat button

In **Chat button** mode, the AI chat widget opens after the user clicks the button. It is generated as a Box-hosted `script` and displays a floating chat button on your page.

<img alt="Chat button mode" />

#### Chat button parameters

The **Chat button** mode supports the following parameters:

| Parameter | Required | Description |
| - | - | - |
| `data-hub-id` | Yes | The ID of the hub that powers the chatbot. |
| `data-custom-box-domain` | No | For Box instances with custom domains. Default: `app.box.com`. Example: `mycompanydomain.app.box.com`. |
| `data-button-text` | No | Custom text to display on the chat button. Default: `Box AI`. This value is also used for the button's aria label for accessibility. |
| `data-shared-link` | No | Optional shared link for hub access. If not provided, the chat loads only for users who are collaborators on the hub. |

The following example shows a fully configured chat button with all available parameters:

```html theme={null}
<script 
  src="https://cdn01.boxcdn.net/embeddable-ai-chat-script/2.8.0/box_integrations_ai_chat_button.js" 
  data-hub-id="123456789" 
  data-custom-box-domain="mycompanydomain.app.box.com" 
  data-shared-link="abcdefghijklmnopqrst123" 
  data-button-text="Ask our HR chatbot">
</script>
```

### Chat widget

In **Chat widget** mode, the AI chat widget is embedded directly on page load. It is generated as an `iframe` and displays the full chat interface immediately.

<Note>
  Currently, only legacy agents are available from the agent selector dropdown.
</Note>

<Frame>
  <img alt="Chat widget mode" />
</Frame>

#### Chat widget parameters

In **Chat widget** mode, the AI chat widget is embedded directly on the page using an `iframe`. You can customize the behavior by adding URL parameters to the iframe's `src` attribute:

| Parameter | Description |
| - | - |
| `hubId` | The ID of the hub that powers the chatbot. |
| `sharedLink` | The shared link hash for hub access. If not provided, the chat loads only for users who are collaborators on the hub. |
| `showCloseButton` | Whether to show the <Link href="/guides/embed/box-embed/#using-the-close-button">X (close) button</Link> in the chat interface. When set to `true`, the close button is displayed. When a user clicks this button, Box generates an event that is sent to the parent web application, enabling you to implement custom closing logic based on the user interaction. |

The following example shows a fully configured chat widget with all available parameters:

```html theme={null}
<iframe 
  src="https://yourcompanydomain.app.box.com/ai-chat?hubId=123456789&sharedLink=abcdefghijklmnop123&showCloseButton=false" 
  width="800" 
  height="550" 
  frameBorder="0" 
  <!-- Optionally replace * with your enterprise-specific domain (for example, mycompanydomain.app.box.com) -->  
  allow="local-network-access *; clipboard-read *; clipboard-write *"  
  allowfullscreen 
  webkitallowfullscreen 
  msallowfullscreen>
</iframe>
```

#### Using the close button

When embedding the Box AI chat directly with `iframe` (without using the provided script), you can enable a close button within the chat interface that communicates with your parent application through `postMessage`.

##### Enabling the close button

To display a close button (✕) in the corner of the iframe, add the `showCloseButton=true` query parameter to your `iframe` URL as follows:
`https://app.box.com/ai-chat?hubId=YOUR_HUB_ID&showCloseButton=true`

##### How it works

1. When `showCloseButton=true` is set, an X button appears in the corner of the chat iframe.
2. When a user clicks this button, the iframe sends a `postMessage` event to the parent window.
3. The event contains `event.data.type` set to `"BOX_AI_CHAT_CLOSE"`.
4. Your hosting application listens for this event and handles the closing logic.

##### Implementation example

```javascript theme={null}
window.addEventListener('message', (event) => {
    // Optional: validate origin is from Box for additional security
    // if (event.origin !== 'https://app.box.com') return;

    if (event.data && event.data.type === 'BOX_AI_CHAT_CLOSE') {
        closeChat();
    }
});
```

##### Event reference

| Property | Value | Description |
| - | - | - |
| `event.data.type` | `"BOX_AI_CHAT_CLOSE"` | Indicates the user clicked the close button in the chat iframe. |

## Expiring embed links

For files, another option is to call the <Link href="/reference/get-files-id">`GET /files/:id`</Link>
and request an `expiring_embed_link` using the `fields` query parameter.

```curl theme={null}
curl https://api.box.com/2.0/files/12345?fields=expiring_embed_link \
    -H "authorization: Bearer ACCESS_TOKEN"
```

```json theme={null}
{
  "etag": "1",
  "expiring_embed_link": {
    "token": {
      "access_token": "1!rFppcinUwwwDmB4G60nah7z...",
      "expires_in": 3646,
      "restricted_to": [
        {
          "object": {
            "etag": "1",
            "file_version": {
              "id": "34567",
              "sha1": "1b8cda4e52cb7b58b354d8da0068908ecfa4bd00",
              "type": "file_version"
            },
            "id": "12345",
            "name": "Image.png",
            "sequence_id": "1",
            "sha1": "1b8cda4e52cb7b58b354d8da0068908ecfa4bd00",
            "type": "file"
          },
          "scope": "base_preview"
        },
        ...
      ],
      "token_type": "bearer"
    },
    "url": "https://cloud.app.box.com/preview/expiring_embed/...."
  },
  "id": "12345",
  "type": "file"
}
```

The `url` attribute can be used in an `<iframe>` to embed an auto expiring Box
Embed interface.

```html theme={null}
<iframe
  src="YOUR-GENERATED-BOX-EMBED-LINK"
  width="{pixels}"
  height="{pixels}"
  frameborder="0"
  allowfullscreen
  webkitallowfullscreen
  msallowfullscreen
/>
```

### Parameters

Extra parameters can be added to this URL as well to customize the UI. To do so,
add the following parameters to the `url` as query parameters. The eventual URL
would look something like this.

```sh theme={null}
https://app.box.com/preview/expiring_embed/[HASH]?[parameterName]=true
```

| | |
| - | - |
| `showDownload` | Shows the download button in the embedded header bar if the viewer has permissions to download the file. Document file types will also show a print button since print and download are governed by the same permissions. Defaults to `false`. |
| `showAnnotations` | Enables users with permission Preview and above to annotate document and image previews. Also shows annotations that are already on the document. To learn more about the file types that annotations are available on as well as the types of annotations, you can refer to our Annotations page. Annotations are available today on web browsers only. On mobile browsers, users will be able to view annotations but not create new ones. |

## Custom logo

Paid Box customers have the option to remove the Box logo in the file Preview.
To do so, visit the **Admin Console**, **Enterprise Settings**, **Custom
Setup** and toggle the **Embed widget customization** off to hide the Box
logo.

## Limitations

Box Embed is not optimized for mobile browsers and should not be used in web
experiences designed for mobile devices. Many UI elements, like the **download**
and **print** options might not show in mobile browsers.

[logo]: https://support.box.com/hc/en-us/articles/360044193633-Customize-Your-Account-s-Branding

[5]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels


# Box View best practices
Source: https://developer.box.com/guides/embed/box-view/best-practices



## Rotate Tokens

Your application should request a new token before the current one expires. All Box SDKs handle this automatically.

## Downscope Tokens

Access tokens hold elevated privileges over the content managed by your application. Your application can use them to upload, download, preview and modify any Box content.

We strongly recommend that you use a <Link href="/guides/authentication/tokens/downscope">downscoped</Link> version of the original access token if you need to make the token available on the client side for any reason. This is because of the elevated privileges granted to these tokens. An example of when this would be needed is if you are using the Box Preview UI Element.

<RelatedLinks title="RELATED GUIDES" />


# Create File Preview
Source: https://developer.box.com/guides/embed/box-view/create-preview



<RelatedLinks title="REQUIRED GUIDES" />

Once a file is uploaded to the application, it can be previewed
using two different methods:

* Direct embed: A standard HTML `<iframe>` component with a custom embed link.
* Customized previewer: A fully customized preview widget using Box <Link href="/guides/embed/ui-elements">UI Elements</Link>.

## Direct Embed (`iframe`)

The direct embed link provides limited options to customize the preview
experience in your application. Due to the light-weight nature of the method,
the API doesn't give you options to respond to client-side actions such as
scrolling in the case of documents, play/pause interactivity for videos,
rotating an image, etc.

There are two steps to create a direct `<iframe>` embed for Box View:

1. Generate an embed URL for the file
2. Add the embed URL to an `<iframe>`

### Generate an embed URL for the file

To create a public file preview URL for a file that was uploaded to the application, you may either use a direct SDK method or make the request
directly to the APIs.

<Note>
  When generating the embed URL directly from the APIs, use the
  <Link href="/reference/get-files-id">Get File Information endpoint</Link> and request
  `expiring_embed_link` via the `fields` parameter.
</Note>

<CodeGroup>
  ```sh cURL theme={null}
  curl https://api.box.com/2.0/files/FILE_ID?fields=expiring_embed_link \
      -H "authorization: Bearer [ACCESS_TOKEN]"
  ```

  ```csharp .NET theme={null}
  String fileId = "12345678";
  Uri embedUri = await client.FilesManager.GetPreviewLinkAsync(id: fileId);
  ```

  ```java Java theme={null}
  String fileID = "12345678";
  BoxFile file = new BoxFile(api, fileID);
  URL embedLink = file.getPreviewLink();
  ```

  ```python Python theme={null}
  file_id = '12345678'
  embed_url = client.file(file_id).get_embed_url()
  ```

  ```js Node theme={null}
  const fileId = '12345678';
  client.files.getEmbedLink(fileId).then(embedURL => {
      // ...
  });
  ```
</CodeGroup>

Within the response object will be a public embed URL like the following:

```shell theme={null}
https://app.box.com/preview/expiring_embed/gvoct6FE!YT_X1LauQ8ulDTad96hTl9xLCRYJ
5iU6O61KxiduxFIgX9HSWMcCWf7zju1XkEsf6-Ul2qtKXeaFeKPT4SysQJQdxrc144KgTIBuoI3bWMf4
cfhp3jdLYrK5hnr6KMq5H6r-AW31AcFtDJi1lnT0M4b3bvvZUaE2RRJGGINMauvS6MAT2luae5PvbFSx
Ctqqx6XlN6QrqbhfJc0UeJF9qwMv3-O8q5fWn0qr8OTY4lkeYidtTs3Ux...
```

<Warning>
  For security reasons, the generated embed link will expire after 1 minute and
  should be immediately embedded in the app once generated.
</Warning>

### Add the embed URL to an `<iframe>`

Within the HTML of your application, create an `iframe` element with the `src`
attribute set to generated embed URL.

```html theme={null}
<iframe src="https://app.box.com/preview/expiring_embed/gvoct6FE!ixgtCKQAziW
  9tHPm-jueq4cmS4GnL9RTJRcVEsK_3W8xcxtVo_v6gKpoXY45odgG1QrcjBVYZMrriUyGvcoSM
  SX8s-smpaFFYQik0R-PCKFtwvbv0lonid6ZfYNbuNFl2j9hOIqBccvHrdVor7i6WvOm6zELzTY
  4EWshcyYYBhDbJmYMrq61RtU_kvBe5P..."></iframe>
```

## Customized Previewer (UI Elements)

To leverage advanced preview customization and event handling capabilities, use
the Box <Link href="/guides/embed/ui-elements/preview">UI Preview Element</Link>.

To set up the Preview Element, start by installing the required components.

<Card href={localizeLink("/guides/embed/ui-elements/installation")} title="Install Box Elements and Preview" />

The basic code will resemble the below when adding the JavaScript code to
display a new previewer.

```js theme={null}
var preview = new Box.Preview();
preview.show("FILE_ID", "ACCESS_TOKEN", {
    container: ".preview-container",
    showDownload: true
});
```

Replace the placeholders in the code sample with the following:

* `FILE_ID`: The ID of the file uploaded to the application, which can be obtained from the object returned when uploading the file.
* `ACCESS_TOKEN`: The primary Access Token set up when configuring the application or a downscoped version of the token.

<Warning>
  Due to the elevated privileges of the primary access token it's highly
  recommended that you use a downscoped version of the token in the Javascript
  code. See
  <Link href="/guides/embed/box-view/best-practices#use-downscoped-tokens">best practices for downscoping</Link>.
</Warning>

<RelatedLinks title="RELATED GUIDES" />


# FAQ
Source: https://developer.box.com/guides/embed/box-view/faq



<AccordionGroup>
  <Accordion title="How does Box View work?">
    To get started with the New Box View, follow our guide
    <Link href="/guides/embed/box-view/setup">here</Link>.
  </Accordion>

  <Accordion title="Which Preview method, Embed Link or UI Element, is right for me?">
    Please follow our guide <Link href="/guides/embed/box-view/create-preview">here</Link> to choose
    the best method for your use case.
  </Accordion>

  <Accordion title="What file types are supported by Box View?">
    Supported [file types][file_types] can be found in our support article.
  </Accordion>

  <Accordion title="Which file types are not supported on mobile with Box View?">
    * All documents supported on web preview are supported on mobile browsers (Safari for iOS and Chrome).
    * Full annotations support is available for mobile via the <Link href="/guides/embed/ui-elements/preview">Content Preview UI Element</Link>, which leverages Box Annotations.
    * Mobile SDKs (for iOS and Android) do not support 360 Videos/Images, and 3D.
    * Mobile SDKs (for iOS and Android) do not support annotations (both read and write).
  </Accordion>

  <Accordion title="What are annotations?">
    <Link href="/guides/embed/ui-elements/annotations">Annotations</Link> are markup notes on a file rendering and allow
    developers to provide collaboration capabilities right from within the
    embedded Box preview in their application.
  </Accordion>

  <Accordion title="After uploading a file, how can my application get file representations?">
    <Link href="/guides/representations">Box Representations</Link> let you get the digital assets
    created for files stored in Box. You can use these endpoints to get PDF, text,
    image, and thumbnail representations for a file.
  </Accordion>

  <Accordion title="Can I use Box View with storage providers other than Box?">
    Currently, Box View is only compatible with files that are stored in Box. You
    can delete the files from Box once you no longer need to display them. However,
    you would need to re-upload them again in order to generate the preview.
    For this reason, we recommend keeping the files stored in Box for at least as
    long as you want to be able to display them.
  </Accordion>

  <Accordion title="How do I fix the CORS error Box gives me when I embed a Box UI Element?">
    To fix the <Link href="/guides/security/cors">CORS</Link> error, add each domain you wish to allow to make CORS
    requests via the application's configuration page. Wildcards are supported for
    the subdomain (`https://*.domain.com`). See the
    <Link href="/guides/security/cors">CORS guide</Link> for more information.
  </Accordion>

  <Accordion title="How can I replace the Box logo that shows up on preview?">
    See this guide for information on customizing the logo within a
    <Link href="/guides/embed/ui-elements/logo">Preview UI Element</Link>.
  </Accordion>
</AccordionGroup>

[file_types]: https://support.box.com/hc/en-us/articles/360043695794-Viewing-Different-File-Types-Supported-in-Box-Content-Preview

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Box View
Source: https://developer.box.com/guides/embed/box-view/index



Box View is an embeddable service that allows developers to upload, convert,
and display files in their web and mobile apps via a high-fidelity,
interactive file viewer.

## Features

### View any file

Embed documents, images, videos, 360-degree videos and images, 3D models, and
dozens of other files in any web or mobile app using a standard `<iframe>`.

### Ease of use

Upload files to Box via a secure API and receive an embeddable HTML5
snippet to place into your application's UI.

### Collaboration in context

Allow end users to collaborate and mark up documents, presentations, and images
with annotations. Users can highlight text or comment on specific areas of a
file rendering.

## How does Box View work

1. Upload files into Box using our <Link href="/reference/post-files-content">secure upload API</Link>. All content is stored in Box's secure cloud storage infrastructure with virus scanning and 256 bit encryption.
2. Upon upload, files are converted into HTML5 compatible assets, which are designed to render crisply and responsively.
3. An embeddable URL is requested to access the file rendering. Previews can be embedded directly in your application using an `<iframe>` URL.

<Frame>
  <img alt="Box View flow" />
</Frame>

## Customize your experience with Box Content Preview

<Link href="/guides/embed/ui-elements/preview">Box Content Preview</Link> may be used to create
customized client-side experiences with the converted files.

## Use cases

* Convert and display PDF resumes in a recruiter application
* Convert and display course materials, including documents, videos, and PDFs in a student portal
* Convert and display HD video in a media room
* Convert and display sales collateral, including documents, videos, PDFs, and 3D models in a field sales enablement application

<RelatedLinks title="RELATED GUIDES" />


# Setup
Source: https://developer.box.com/guides/embed/box-view/setup



Before uploading files to Box and previewing them using Box View, a Box
Platform App must be created and configured for server authentication.

<Card href={localizeLink("/guides/applications/platform-apps/create#create-a-platform-app-2")} title="Create a Platform App" />

## Choose an authentication method

Box View works with any server-side authentication method. Choose the one that fits your
needs.

<Note>
  Whether you can change the authentication method after creation depends on your
  enterprise's **Switch server app auth type (CCG or JWT)** setting. If switching
  is disabled, choose carefully - the method is fixed and you must create a new app
  to use a different one. See <Link href="/guides/authentication/switch-server-auth-type">Switch between CCG and JWT</Link>.
</Note>

| Method | Best for | Key trait |
| - | - | - |
| **Client Credentials Grant (CCG)** | Most Box View use cases | Simple setup; uses client ID and a secret |
| **JWT** | Environments that require public/private key security | Key-pair based; no shared secret over the wire |

Both methods authenticate as the application's Service Account, which owns all
uploaded content — no end-user login is required.

<Note>
  **Migrating from a Limited Access App**: CCG and JWT Platform Apps support every
  endpoint that Limited Access Apps (App Token authentication) support plus 150 more. The file
  upload, download, delete, and preview workflows are identical. See the
  [authentication overview](/guides/authentication) for a full comparison.
</Note>

## Configure application settings

To configure your application, in the [Developer Console](https://app.box.com/developers/console), navigate to the **Configuration** tab of your application, and then set the following options:

1. For **Application Access**, select **App Access Only**.
   This restricts the application to its own Service Account content, which is the standard configuration for Box View.
2. For **Application Scopes**, enable at least the following options:
   * **Read all files and folders stored in Box** (root\_readonly)
   * **Read and write all files and folders stored in Box** (root\_readwrite)
3. If your application makes API calls from front-end browser code (for example, using Box UI Elements), add your domains to the CORS allow-list at the bottom of the **Configuration** tab.
4. Copy your credentials from the **Configuration** tab:
   * For CCG, copy the **Client ID** and the **Client Secret**.
     To view the secret, [multi-factor authentication](https://support.box.com/hc/en-us/articles/360043697154-Multi-Factor-Authentication-Set-Up-for-Your-Account) is required.
   * For JWT, download the JSON config file after generating a public/private key pair.

## Authorize your application

Server-authenticated Platform Apps require admin authorization before they can make API calls.

1. In the [Developer Console](https://app.box.com/developers/console), navigate to the **Authorization** tab.
2. Click **Review and Submit**.
   Your enterprise's Box Admin will receive an email to approve the application in the Admin Console. For more information, see the [Platform App Approval guide](/guides/authorization/platform-app-approval).

<Warning>
  If you try to make API calls before the app is authorized, you receive the following error:
  <code>"error": "unauthorized\_client"</code>
</Warning>

## Obtain an access token

The process for obtaining an access token depends on the authentication method of your application.

### Client Credentials Grant (CCG) authenticated Platform Apps

Request an access token by sending your client ID and secret to the token endpoint. The token authenticates as the application's Service Account.

```sh cURL theme={null}
curl -X POST https://api.box.com/oauth2/token \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "box_subject_type=enterprise" \
  -d "box_subject_id=YOUR_ENTERPRISE_ID"
```

The response contains an access token valid for approximately 60 minutes:

```json Response theme={null}
{
  "access_token": "c3FIOG9vSGV4VHo4QzAy...",
  "expires_in": 4169,
  "restricted_to": [],
  "token_type": "bearer"
}
```

Your application should request a new token before the current one expires. All Box SDKs handle this automatically:

<CodeGroup>
  ```python Python theme={null}
  from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig

  auth = BoxCCGAuth(
      config=CCGConfig(
          client_id="YOUR_CLIENT_ID",
          client_secret="YOUR_CLIENT_SECRET",
          enterprise_id="YOUR_ENTERPRISE_ID",
      )
  )
  client = BoxClient(auth=auth)
  ```

  ```js Node.js theme={null}
  const BoxSDK = require("box-node-sdk");

  const sdk = new BoxSDK({
    clientID: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET",
  });

  const client = sdk.getCCGClientForEnterprise("YOUR_ENTERPRISE_ID");
  ```

  ```java Java theme={null}
  BoxCCGAPIConnection api = BoxCCGAPIConnection.applicationServiceAccountConnection(
      "YOUR_CLIENT_ID",
      "YOUR_CLIENT_SECRET",
      "YOUR_ENTERPRISE_ID"
  );
  ```

  ```csharp .NET theme={null}
  var config = new BoxConfigBuilder("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
      .SetEnterpriseId("YOUR_ENTERPRISE_ID")
      .Build();
  var session = new BoxCCGAuth(config);
  var client = session.AdminClient();
  ```
</CodeGroup>

### JWT authenticated Platform Apps

If your application uses JWT authentication, use the JSON config file downloaded during setup:

<CodeGroup>
  ```python Python theme={null}
  from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig

  jwt_config = JWTConfig.from_config_file("/path/to/config.json")
  auth = BoxJWTAuth(config=jwt_config)
  client = BoxClient(auth=auth)
  ```

  ```js Node.js theme={null}
  const BoxSDK = require("box-node-sdk");
  const fs = require("fs");

  const configJSON = JSON.parse(fs.readFileSync("/path/to/config.json"));
  const sdk = BoxSDK.getPreconfiguredInstance(configJSON);
  const client = sdk.getAppAuthClient("enterprise");
  ```
</CodeGroup>

For more information about JWT setup, see the [JWT authentication guide](/guides/authentication/jwt).

## Downscope tokens for client-side use

If you need to pass an access token to the browser (for example, to run Box Content Preview or other Box UI Elements), always downscope the token first. Downscoping exchanges a full-privilege token for a new token with restricted permissions and an optional file-level scope.

```sh cURL theme={null}
curl -X POST https://api.box.com/oauth2/token \
  -d "subject_token=YOUR_ACCESS_TOKEN" \
  -d "subject_token_type=urn:ietf:params:oauth:token-type:access_token" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
  -d "scope=item_preview" \
  -d "resource=https://api.box.com/2.0/files/FILE_ID"
```

The downscoped token is short-lived and limited to the specified scope and file. Use it in client-side code instead of the original access token.

The following table lists common downscope scopes for Box View:

| Scope | Description |
| - | - |
| <code>item\_preview</code> | Preview a file |
| <code>item\_download</code> | Download a file |
| <code>base\_preview</code> | Basic preview (Box Content Preview element) |
| <code>annotation\_edit</code> | Edit and delete annotations |
| <code>annotation\_view\_all</code> | View all annotations |

For the full list of downscope scopes, see the [scopes guide](/guides/api-calls/permissions-and-errors/scopes#scopes-for-downscoping).

## Security best practices

Follow these guidelines to ensure your Platform Apps are secure:

* Never expose your client secret or full access token in client-side code. Always downscope before sending tokens to the browser.
* Store credentials securely. Use environment variables or a secrets manager for your client ID, client secret, and enterprise ID.
* Keep **Application Access** set to **App Access Only** unless you specifically need enterprise-wide content access.
* Add only necessary CORS domains. Restrict the allow-list to the domains that actually make browser-side API calls.

## Legacy Limited Access Apps

Limited Access Apps use App Token authentication, which provides a pair of fixed, long-lived tokens (Primary and Secondary) that are manually generated in the Developer
Console. This approach is being replaced by CCG and JWT authentication, which offer programmatic token management, automatic refresh, and access to the full Box API.
If you have an existing Limited Access App, follow these steps to migrate your content to a new CCG or JWT authentication app:

1. Create a new Platform App using CCG or JWT following the [steps above](/guides/embed/box-view/setup#choosing-an-authentication-method).
2. Reupload your content to the new app's Service Account, or use collaborations to share existing content.
3. Replace hard-coded App Tokens with programmatic CCG or JWT token acquisition.
4. Update any downscoped token calls.
   The <code>POST /oauth2/token token-exchange</code> flow is identical; only the <code>subject\_token</code> value changes.

The file upload, preview, and embed workflows are identical regardless of the authentication method. No changes are needed to your iframe embeds or Box UI Element code beyond swapping the access token.

<RelatedLinks title="RELATED GUIDES" />


# Upload Files
Source: https://developer.box.com/guides/embed/box-view/upload-file



<RelatedLinks title="REQUIRED GUIDES" />

To generate a preview embed link for a file, the file must be uploaded to
Box. For most file types, conversion is triggered automatically upon upload.
However, for video and 3D files, it is triggered upon first preview. No explicit
action is required by the user to begin conversion. In either case, conversion
is triggered only once per file, and the generated assets are available for as
long as the original file is stored in Box.

## Uploading a File

To upload a file using the <Link href="/sdks-and-tools">Box SDKs</Link> or directly with
the APIs, you need to use the CCG or JWT Access Token that is generated
during <Link href="/guides/embed/box-view/setup">application setup</Link> to authenticate your
application.

<Card href={localizeLink("/guides/authentication/tokens/")} title="Authenticate your application" />

Once an authenticated client has been created, it may be used to upload files
directly to the application for conversion.

<Card href={localizeLink("/guides/uploads/direct/file")} title="Upload files to Box" />

<RelatedLinks title="RELATED GUIDES" />


# Customize Access
Source: https://developer.box.com/guides/embed/ui-elements/access



<RelatedLinks title="REQUIRED GUIDES" />

## Motivation

Box UI Elements are initialized on the client and make API calls directly to
Box. Thus, a valid access token must live on the client because all Box API
requests need to be authenticated.

<Link href="/guides/authentication/tokens/downscope">Token Exchange</Link> is a mechanism to
exchange a "parent token" (a token for your managed or app user, service
account, or application) to a "child token" which is scoped down to the minimum
set of required permissions so it can be securely sent down to the client
without elevating client privileges.

The Box UI Elements are designed to adapt to the permissions on the token, so an
additional advantage of using Token Exchange with them is that front-end
developers won't have to manually toggle UI controls on/off as long as the
correct set of permissions are present on the client token. This behavior mimics
the experience in the Box application as well. For example, a user with
"Preview only" permissions to a folder does not see the "Download" button
present in the UI.

This blueprint covers how to use Token Exchange with UI Elements in your
application and example use cases.

<Frame>
  <img alt="Downscope overview" />
</Frame>

* **Making API calls from client more secure:** As a general security practice, we recommend generating and sending downscoped tokens per every action performed by the user to limit exposure on the client. For example, even if a user should have preview and share access to a file, instead of sending the user token to the client which would give them complete user-level access, we suggest downscoping the token using Token Exchange and sending them a "preview only" token when they wish to preview a file and a "share" token when they want to share a file.
* **Creating a custom permissions model:** If you are building an application using UI Elements and the default Box access levels don't fit your permission model, you can start out with a fully scoped token for all your users and trim them down using Token Exchange on the fly to map to your custom permissions model.
* **Using Box services transactionally (no Box user accounts):** If you are not creating users in Box and are using Box services transactionally, you won't have access to user level tokens. In such cases, you can use Token Exchange to scope down the Service Account token to an appropriately scoped token.
* **Creating a user only to give them access to another user's content:** If you need to provide an end user "one time" access to another app/managed user's content, Token Exchange can be used to downscope the app/managed user token to the specific permissions and file/folders you want to give the end user access to, and pass it down to UI Elements to give them access to that content. For example, using Token Exchange, you can downscope a user token to have read-only access to content and pass it down to another user.

## Implementation

The solution for all of the above is using Token Exchange to exchange a parent
token for a downscoped token and initializing the UI Element using that token.

Token Exchange takes in the "parent token", "list of scopes" and optionally a
file/folder ID as the input arguments, and returns a token that is scoped down
to that exact set of scopes and the respective file/folder ID, if present in
the input arguments.

<Info>
  **Dedicated scopes designed for UI Elements**

  We have designed a set of scopes that work seamlessly with the UI Elements.
  While token exchange works with all Box scopes, we recommend using these
  scopes along with UI Elements since they include the exact set of permissions
  required for base functionality as well as incremental permissions for added
  functionality.
</Info>

<Frame>
  <img alt="Downscope overview" />
</Frame>

## Developer Flow

Now that you understand the different scopes, let's walk through a
scenario for using Token Exchange with a UI Element.

**Scenario:** Provide a user with the ability to browse a folder tree using the
Box Content Explorer UI Element and allow them to preview and download files.
Sharing should be turned off.

**Steps:**

* Create a Managed User, App User or Service Account depending on your use case. You will use this user or application's token as the parent token for Token Exchange. To generate the user token follow:
  * Authentication with OAuth guide if you would like to create a Managed User
  * Authentication with JWT guide if you would like to create an App User or Service Account
* Add the user you created above as a Collaborator to the content using the Create Collaborator API as shown below. This step gives the user access to the content if not already under the user's account. If the file/folder was created under this user's account, then the user by default has "Owner" access to the folder so you can skip the collaboration step.

```sh theme={null}
curl https://api.box.com/2.0/collaborations \
    -H "authorization: Bearer [ACCESS_TOKEN]" \
    -d '{"item": { "id": "123456", "type": "folder"}, "accessible_by": { "id": "USER_ID", "type": "user" }, "role": "editor"}' \
    -X POST
```

<Info>
  **Access Levels in Box**

  There are [7 different access levels][accesslevels] that a Box user can be
  collaborated as on a file/folder in Box. If the file/folder was created under
  this user's account, then the user has "Owner" access to the folder by
  default so you can skip the collaboration step.
</Info>

* Use the Token Exchange API to exchange the parent token for a child token that contains the base scope for Content Explorer (`base_explorer`), `item_download` and `item_preview` scopes enabled for the specific `folder_id` `123456`. We strongly recommend performing this step on the application server.

### Request

```sh theme={null}
curl https://api.box.com/oauth2/token \
  -d 'subject_token=ACCESS_TOKEN' \
  -d 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' \
  -d 'scope=item_upload item_preview base_explorer' \
  -d 'resource=https://api.box.com/2.0/folders/123456' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
  -X POST
```

### Response

```json theme={null}
{
  "access_token": "CHILD_TOKEN",
  "expires_in": 4247,
  "token_type": "bearer",
  "restricted_to": [
    {
      "scope": "base_explorer",
      "object": {
        "type": "folder",
        "id": "123456",
        "sequence_id": "0",
        "etag": "0",
        "name": "FOLDER_NAME"
      }
    },
    {
      "scope": "item_download",
      "object": {
        "type": "folder",
        "id": "123456",
        "sequence_id": "0",
        "etag": "0",
        "name": "FOLDER_NAME"
      }
    },
    {
      "scope": "item_preview",
      "object": {
        "type": "folder",
        "id": "123456",
        "sequence_id": "0",
        "etag": "0",
        "name": "FOLDER_NAME"
      }
    }
  ],
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}
```

The `CHILD_TOKEN` obtained above is scoped down to only include download and
preview permissions for folder id `123456` and its children.

Use this `CHILD_TOKEN` in your Content Explorer UI Element. To see a quick demo,
you can use our [Content Explorer UI Element CodePen
Sample](https://codepen.io/box-platform/pen/wdWWdN) and replace the access token
and folder id values in the JS Tab.

<Frame>
  <img alt="Downscope overview" />
</Frame>

Click "Run". You should see the Content Explorer initialized at the folder you
specified. Also, notice that your Content Explorer no longer shows the "Share"
button as it would have with the parent (user) token.

<Frame>
  <img alt="Downscope overview" />
</Frame>

<Frame>
  <img alt="Downscope overview" />
</Frame>

## When NOT to use Token Exchange

* **Does not replace Users or Groups in Box:** We recommend not using Token Exchange as a replacement to creating users in Box. One way to determine whether you should create Box users, is by doing an assessment to determine if it makes logical sense for every end user of your application to have a copy of their own content. Here are some benefits of maintaining user level accounts in Box, which you wouldn't get by using Token Exchange alone.
  * **Content isolation/security:** It's better to have user level accounts since in the case of the parent token accidentally leaking, you would only be compromising the content of a single user vs. all users of your enterprise.
  * **Performance:** Creating users/groups in Box is also useful as your application does not have to determine the appropriate permissions at the time of accessing content since that is likely to affect the performance of your application.
  * **User level tracking/auditing:** Several Box features such as auditing, access stats, retention, etc. leverage Box's user model. If it is essential for you to use those features, then you would have to create user-level accounts.
* **Does not replace Collaborations in Box:** Collaborations is a more standard and easier to scale way to provide Box users with access to content. Also, managing content access through collaborations in Box requires your application to manage less code/data on which user should have access to what content. If you are using Token Exchange as a replacement to Collaborations, you will need to keep a mapping of every user -> every file and folder that they should have access to and that could get out of control pretty quickly.
* **Caching the downscoped tokens:** If performance is critical to your application, you should pre-cache downscoped tokens on the server side. If you are pre-caching tokens, we recommend implementing retries as the tokens expire within 1 hour.

<Info>
  **Token Lifespan**

  The lifespan of parent and child tokens is not mutually dependent, for
  example when generating a child token doesn't render the parent token
  inactive. Similarly, generating more child tokens doesn't impact the previous
  child tokens in any way.
</Info>

## Example Scenarios

### Scenario #1: More secure client API calls

An equity-investment firm is building out a partner/investor portal to broadcast
information (view-only access) to investors published by the employees.

They create app users for each of their external customers and employees have
provisioned Box accounts which they used to publish content. All app users are
collaborated on published content as Viewer Uploader, so they can both preview
as well as upload content in their account as needed. Once an investor/partner
signs in they are taken to a portal where they can view as well as upload
information.

Since both preview and upload require the API calls to be made via the client,
instead of passing down a “Viewer Uploader” token, the application uses Token
Exchange to downscope the token appropriately based on the action that the user
is trying to perform. This ensures that if the token is compromised, data
leakage is minimized thereby improving the overall security posture of the
application.

### Scenario #2: A custom permissions model

A large fin-tech company is building a secure client vault to manage investments
for their clients. They are also using Box UI Elements to build out the content
management front end of their application.

They create app users as usual for each one of their clients and app advisors.
When they wanted to share content across app users, they collaborate the app
user(s) as "Editor" role (Box's role). This guarantees that every app user had
full access to every other user’s content.

To enable a user to access content via the UI Elements, the application does not
provide the app user token to the client directly as the app user may be
collaborated as an "Editor" into other user's content (highly privileged).
Instead, it uses Token Exchange using the app user token to generate a
downscoped token that limits:

* the scope of what the token can be used for (view, upload, download, browse, share, etc.) and/or
* the specific files that the user should have access to

### Scenario #3: Process Flows

A not-for-profit union bank is developing a loan processing application using
Box's secure content layer to facilitate the sharing of documents between loan
applicants and internal users (loan processors and underwriters). The basic
process is as follows:

* When customers apply for a loan they must submit documents through a custom-built web portal as a part of the process (proof of income, identity etc.)
* Box is used as the intermediary for sending/receiving docs
* Internal employees need to upload files for customers
* Internal employees can access documents through a custom web portal as well as Box Web app

The application developers used Token Exchange along with UI Elements to build
out a loan process management solution, where the application server downscopes
the loan application's app user token based on which operations the client needs
to perform, and passes it down to the clients (customers and loan officers).
Using these downscoped tokens, the UI Elements are able to show the right
controls/buttons to indicate to the user which actions they can perform
(example: upload button is grayed out from the content explorer UI Elements if
the downscoped token passed doesn't contain upload permissions).

### Scenario #4: Transactional Flows

A Learning Management System provider is using Box to power preview in
their application. All users and associated permissions are managed by the
application outside Box. From Box's perspective, all API calls made by the
application are on its own behalf (and not any individual user), and all content
stored and previewed belongs to the application and not to a single user. In
this case, the application developer is using a sliver of Box's overall
capabilities (for example Preview) transactionally and none of the other secure
content sharing and collaboration capabilities. In fact, this is a key use case
for many customers.

Consider a straightforward use case of the application - the end user needs to
upload a file and then preview it in the application itself. To do this the
application is using the Content Uploader and Content Preview UI Elements,
respectively. Since both preview + upload are bandwidth heavy operations, the
application should not proxy the traffic and instead allow the client to perform
these operations directly against Box. To make calls against Box, all UI
Elements require a valid access token to be available on the client. But the
application should never pass down the privileged "service account" token to the
client which would give the client access to all content ever uploaded through
the application. Instead, the application uses Token Exchange to down-scope its
service account token to an upload-only token to allow the client to upload
files via the Upload UI Element, and a separate preview-only token to let the
client preview via the Preview UI Element.

## Anti-patterns

These anti-patterns have been included here to help you identify patterns that
we do not recommend as they will either make your app development more
challenging, your application less secure or performing or both. If you find
yourself implementing any of these patterns on your app, please reach out to us
via Box support so we can help you out.

### Passing privileged tokens to client

Please NEVER DO THIS. This can potentially compromise the security of content in
your Box enterprise. Always use token exchange to provide end users with the
exact set of permissions.

### Proxying/filtering API responses

If you are proxying/filtering API responses from Box only to limit data/content
exposure to the client, you should try to see if using Token Exchange allows you
to limit the exposure. This is especially true for high-bandwidth operations
such as preview, download, and upload which are bandwidth intensive and so we
recommend that the client performs those operations directly with Box.

[accesslevels]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels

<RelatedLinks title="RELATED GUIDES" />


# Annotations
Source: https://developer.box.com/guides/embed/ui-elements/annotations



<RelatedLinks title="REQUIRED GUIDES" />

Box Annotations allow developers to provide collaboration capabilities right
from within the embedded Box preview in their application. Box Annotations fit a
wide range of use cases and can be used to draw the previewer's attention and/or
provide feedback on specific parts of a document or images.

<Card href={localizeLink("/guides/embed/ui-elements/preview")} title="Learn more about Content Preview" />

Box Content Preview currently supports four annotation types - highlight
comment, highlight only, draw, and point annotation. Box Annotations are today
supported on documents and image previews only. You can find the full list of
supported file types for Box Content Preview [here][filetypes].

## Browser support

<Link href="/guides/embed/ui-elements/browser">Learn more about browser support</Link> for Box UI
element.

## Usage

Box Annotations can be used by pulling from our [NPM
package](https://www.npmjs.com/package/box-annotations).

## Initialization

```js theme={null}
/* global BoxAnnotations */
const boxAnnotations = new BoxAnnotations();
const annotatorConf = boxAnnotations.determineAnnotator(
    options,
    disabledAnnotationTypes
);

// Construct and init annotator
const annotator = new annotatorConf.CONSTRUCTOR(options);

annotator.init(scale);
```

Where `disabledAnnotationTypes` is a string of valid annotation types to
disable. See below for
more details on viewer specific annotation configurations.

## Authentication

The UI Elements are designed in an authentication agnostic way so whether
you are using UI Elements for users who have Box accounts (Managed Users) or
non-Box accounts (App Users), UI Elements should work out of the box. The
reason for this is that UI Elements only expect a "token" to be passed in for
authentication, and Box provides two different ways to generate tokens - OAuth
and JWT.

<Card href={localizeLink("/guides/authentication")} title="Compare authentication methods" />

If your application requires the end user to only be able to access a subset of
the Annotations functionality, you can use
<Link href="/guides/authentication/tokens/downscope">Downscoping</Link> to appropriately
downscope your Access Token to a resulting token that has the desired set of
permissions, and can thus, be securely passed to the end user client
initializing Annotations.

Below are a set of new Annotation-specific scopes to go alongside Downscoping.
These allow developers to enable/disable functionality on Box
Annotations by configuring the appropriate scopes on the downscoped token. To
learn more, see <Link href="/guides/embed/ui-elements/scopes">Dedicated scopes for the Box UI
Elements</Link>.

## Parameters & Options

```js theme={null}
const annotator = new annotatorConf.CONSTRUCTOR({
    annotator,
    apiHost,
    token,
    container,
    file: {
        id,
        file_version: {
            id
        },
        permissions
    },
    isMobile,
    hasTouch,
    locale,
    modeButtons: {
        // Annotation mode buttons, i.e. point, draw, etc
        point: {
          // Accessibility message for the point annotation mode button
          title: "Point annotation mode",
          // CSS selector for the point annotation mode button
          selector: ".bp-btn-annotate-point"
        }
    }
});
```

| Parameter | Default | Description |
| - | - | - |
| `annotator` | | Viewer-specific annotator configurations object |
| `apiHost` | | Host for Box API calls for example `https://app.box.com/api` |
| `fileId` | | Box file ID |
| `token` | | A string auth token, see below for details on how to generate annotator tokens with appropriate scopes |
| `container` | | DOM node or selector where Preview should be placed |
| `file` | | File metadata object |
| `file.id` | | String `Box_File` id |
| `file.file_version.id` | | String `Box_File_Version` id |
| `file.permissions` | | File permissions object, see below on how to scope permissions |

| Option | Default | Description |
| - | - | - |
| `modeButtons` | | Object containing a CSS selector and accessibility message for the annotation mode button, see parameters and options example above |
| `isMobile` | `false` | Whether the user's browser is on a mobile device |
| `hasTouch` | `false` | Whether the mobile browser has touch enabled |
| `locale` | `en-US` | Shared link URL |

### Base Scope

| Scope Name | What permissions does it grant? |
| - | - |
| `base_preview` | Allows preview access to a file or files in a folder based on user/file/token permissions |

### Feature Scopes

| Scope Name | What permissions does it grant? |
| - | - |
| `item_download` | Allows files/folders contents to be downloaded |
| `annotation_view_self` | Allows user to view their own annotations |
| `annotation_view_all` | Allows user to view all annotations on the file |
| `annotation_edit` | Allows user to edit their own annotations (includes `annotation_view_self`) |

### Sample Scenarios

| Scenario | Scope Combinations |
| - | - |
| User wants basic preview functionality + ability to edit own annotations | `base_preview` + `annotation_edit` |
| User wants basic preview functionality + ability to edit own annotations + ability to select text on documents | `base_preview` + `annotation_edit` + `item_download` |
| User wants basic preview functionality + ability to view all annotations + ability to edit own annotations | `base_preview` + `annotation_view_all` + `annotation_edit` |
| User wants basic preview functionality + ability to view only their own annotations | `base_preview` + `annotation_view_self` |

## Enabling/Disabling Annotations and Annotation Types

Annotation types can be selectively turned off through preview options. Viewer
options override global `showAnnotations` value, for that viewer. See <Link href="/guides/embed/ui-elements/preview">Box
Content Preview</Link> for more details on how to
set up the Preview instances that are used with Box Annotations here.

```js theme={null}
preview.show(..., {
    showAnnotations: Boolean
});
```

Combined with the following:

```js theme={null}
preview.show(..., {
    viewers: {
        VIEWER_NAME: {
            annotations: {
                enabled: Boolean,
                enabledTypes: String[] | null
            }
        }
    }
});
```

This turns the annotations on if `enabled` is set to `true`. This respects the
`showAnnotations` value if empty. The `enabledTypes` value is a list of
annotation types to enable for this viewer. If empty, will respect default types
for that annotator.

### Example

Enable all annotations, turn off for Image Viewers, and enable only point
annotations on Document viewer:

```js theme={null}
preview.show(fileId, token, {
    showAnnotations: true,
    viewers: {
        Image: {
            annotations: {
                enabled: false
            }
        },
        Document: {
            annotations: {
                enabled: true,
                enabledTypes: ["point"]
            }
        }
    }
});
```

## Annotators

The name of an annotator can be one of the following `DocAnnotator` or
`ImageAnnotator`. Call `boxAnnotations.getAnnotators()` to get the list of
possible annotators.

## Additional Methods

* `annotator.init()` initializes the annotator.
* `annotator.isModeAnnotatable(/* String */ type)` returns whether or not the current annotation mode is enabled for the current viewer/annotator.
* `annotator.showModeAnnotateButton(/* String */ currentMode)` shows the annotate button for the specified annotation mode.
* `annotator.getAnnotateButton(/* String */ annotatorSelector)` gets the annotation button element.
* `annotator.showAnnotations()` fetches and shows saved annotations.
* `annotator.hideAnnotations()` hides annotations.
* `annotator.hideAnnotationsOnPage(/* number */ pageNum)` hides annotations on a specified page.
* `annotator.setScale()` sets the zoom scale.
* `annotator.toggleAnnotationHandler()` toggles annotation modes on and off. When an annotation mode is on, annotation threads will be created at that location.
* `annotator.disableAnnotationMode(/* String */ mode, /* HTMLElement */ buttonEl)` disables the specified annotation mode.
* `annotator.enableAnnotationMode(/* String */ mode, /* HTMLElement */ buttonEl)` enables the specified annotation mode.
* `annotator.getAnnotatedEl(/* HTMLElement */ containerEl)` determines the annotated element in the viewer.
* `annotator.createAnnotationThread(/* Annotation[] */ annotations, /* Object */ location, /* String */ [annotation type])` creates the proper type of annotation thread, adds it to the in-memory map, and returns it.

## Events

Events can be bound to the annotator object with `addListener` and removed with
`removeListener`. Event listeners should be bound before `showAnnotations()` is
called, otherwise events can be missed.

```js theme={null}
/* global BoxAnnotations */
const boxAnnotations = new BoxAnnotations();
const annotatorConf = boxAnnotations.determineAnnotator(
    options,
    disabledAnnotationTypes
);

// Construct and init annotator
const annotator = new annotatorConf.CONSTRUCTOR(options);
var listener = value => {
    // Do something with value
};

// Attach listener before calling show otherwise events can be missed
annotator.addListener(EVENTNAME, listener);

// Initialize a annotator
annotator.showAnnotations();

// Remove listener when appropriate
annotator.removeListener(EVENTNAME, listener);
```

`EVENTNAME` can be one of the following

* `annotator` event will be triggered when we have the annotator instance first available. Box Annotations trigger this event before `load` so that clients can attach their listeners before the `load` event is triggered from Box Content Preview.
* `annotationsfetched` event will be triggered when annotations have been fetched from the Box API.
* `annotationmodeenter` event will be triggered when an annotation mode is entered. The event data will contain:

```js theme={null}
{
  // Annotation mode that was entered
  mode: 'point',
  // Optional CSS selector for the container's header
  headerSelector: '.bp-preview-header',
}
```

`annotationmodeexit` event will be triggered when an annotation mode is exited.
The event data will contain:

```js theme={null}
{
  // Annotation mode that was exited
  mode: 'point',
  // Optional CSS selector for the container's header
  headerSelector: '.bp-preview-header',
}
```

`annotationerror` event will be triggered when an annotation error has occurred.
The event data will contain:

```js theme={null}
{
  message: 'message', // Error message to show
}
```

`annotationpending` event will be triggered when an annotation thread was created
but has not yet been saved on the server. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotationthreadsaved` event will be triggered when an annotation thread was saved
on the server. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotationthreaddeleted` event will be triggered when an annotation thread was
deleted on the server. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotationsaved` event will be triggered when an annotation is added and saved to
an existing annotation thread on the server. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotationdeleted` event will be triggered when an annotation is deleted from an
existing thread on the server. The entire annotation thread is not deleted. The
event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotationcanceled` event will be triggered when an annotation is canceled from
posting on either a new or existing thread. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotationdeleteerror` event will be triggered when an error occurs while deleting
an annotation on either a new or existing thread. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotationcreateerror` event will be triggered when an error occurs while posting
an annotation on either a new or existing thread. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

`annotatorevent` Each annotator will trigger its own sets of events. For example,
the Image Annotator will trigger `rotate` or `resize`, etc. while other annotators
may trigger another set of events. The Annotator wrapper will also re-emit events
at the Preview level in Box Content Preview, with event data containing:

```js theme={null}
{
  event: EVENTNAME,             // Event name
  data: DATA,                   // Event data object
  annotatorName: ANNOTATORNAME, // Name of the annotator
  fileVersionId: fileVersionId  // The file version id
  fileId: fileId                // The file id
}
```

### Example event usage

```js theme={null}
preview.addListener("annotator", viewer => {
    annotator.addListener("annotationsfetched", () => {
        // Do something when annotations are fetched on a preview
    });
});

// Event listeners can be attached to viewers
preview.addListener("load", data => {
    var viewer = data.viewer;
    viewer.addListener("annotationsfetched", () => {
        // Do something when annotations are fetched on a preview
    });
});

// Event listeners can be attached to annotators
preview.addListener("load", data => {
    var annotator = data.viewer.annotator;
    annotator.addListener("annotationsfetched", () => {
        // Do something when annotations are fetched on a preview
    });
});

preview.addListener("annotatorevent", data => {
    if (data.event === "annotationsfetched") {
        // Do something when annotations are fetched on a preview
    } else if (data.event === "annotationerror") {
        // Do something different when an annotation error has occurred
    } else {
    }
});

preview.addListener("annotatorevent", data => {
    if (data.viewerName === "Image") {
        if (data.event === "annotationsfetched") {
            // Do something when annotations are fetched on an image preview
        }
    } else if (data.viewerName === "MultiImage") {
        if (data.event === "annotationsfetched") {
            // Do something different when annotations are fetched on a multi-page image
        }
    } else {
    }
});

preview.addListener("annotationsfetched", data => {
    if (data.viewerName === "Image") {
        // Do something when annotations are fetched on an image preview
    } else if (data.viewerName === "MultiImage") {
        // Do something different when annotations are fetched on a multi-page image
    } else {
    }
});
```

## Annotation Thread

### Thread Methods

The following methods are available for the annotation threads.

| Method Name | Explanation | Method Parameters |
| - | - | - |
| `createDialog` | Creates the dialog for the thread | |
| `show` | Shows the annotation indicator | |
| `hide` | Hides the annotation indicator | |
| `reset` | Resets thread state to 'inactive' | |
| `showDialog` | Shows the appropriate dialog for this thread | |
| `hideDialog` | Hides the appropriate indicator for this thread | |
| `saveAnnotation` | Saves an annotation locally and on the server |  annotation type,  text of annotation to save |
| `deleteAnnotation` | Deletes an annotation |  annotation ID,  whether or not to delete on server, default true |

### Thread Events

All annotation threads trigger the following events. The event data will contain:

```js theme={null}
{
  data: {
    type: 'point', // Annotation type
    threadID: '123abc',
    userId: '456def',
    threadNumber: '1' // Thread number from Annotations API
  }
}
```

| Event Name | Explanation |
| - | - |
| `annotationpending` | An annotation thread was created but has not yet been saved on the server. |
| `annotationthreadsaved` | An annotation thread was saved on the server. |
| `annotationthreaddeleted` | An annotation thread was deleted on the server. |
| `annotationsaved` | An annotation thread was added and saved to an existing annotation thread on the server. |
| `annotationdeleted` | An annotation thread was deleted from an existing thread on the server. The entire annotation thread is not deleted. |
| `annotationcanceled` | An annotation thread was canceled from posting on either a new or existing thread. |
| `annotationdeleteerror` | An error occurs while deleting an annotation on either a new or existing thread. |
| `annotationcreateerror` | An error occurs while posting an annotation on either a new or existing thread. |

See the **Events** section above for example event usage.

## Annotation Dialog

### Dialog Methods

The following methods are available for the annotation dialog.

| Method Name | Explanation | Method Parameters |
| - | - | - |
| `show` | Positions and shows the dialog | |
| `hide` | Hides the dialog | |
| `hideMobileDialog` | Hides and resets the shared mobile dialog | |
| `addAnnotation` | Adds an annotation to the dialog |  annotation to add |
| `removeAnnotation` | Removes an annotation from the dialog |  annotation ID |
| `postAnnotation` | Posts an annotation in the dialog |  annotation text to post |
| `position` | Positions the dialog | |

## Supported Annotation Types

Point annotations are supported on both document and image formats. Highlight
comment, highlight only, and draw annotations are only supported on document
formats.

Supported document file extensions: `pdf`, `doc`, `docx`, `ppt`, `pptx`, `xlsx`,
`xls`, `xlsm`.

Supported image file extensions: `ai`, `bmp`, `dcm`, `eps`, `gif`, `idml`,
`indd`, `indt`, `inx`, `png`, `ps`, `psd`, `svs`, `tga`, `tif`, `tiff`.

[filetypes]: https://support.box.com/hc/en-us/articles/360043695794-Viewing-Different-File-Types-Supported-in-Box-Content-Preview

<RelatedLinks title="RELATED GUIDES" />


# Browser Support
Source: https://developer.box.com/guides/embed/ui-elements/browser



<RelatedLinks title="REQUIRED GUIDES" />

Box UI elements are supported in the following browsers.

* Chrome, Firefox, Safari, and Edge (latest 2 versions)
* Mobile Chrome and Safari

<RelatedLinks title="RELATED GUIDES" />


# Box Edit Custom Domains
Source: https://developer.box.com/guides/embed/ui-elements/custom-domains



<RelatedLinks title="REQUIRED GUIDES" />

In order to integrate a third party web application with Box Tools, you will
need to explicitly add your application's URL. On Windows, this is achieved by
adding a registry key. On MacOS, you will need to run a few terminal commands to
add and remove domains.

<Info>
  Adding domains to a safelist was added in **Box Tools version 4.5.0**.
</Info>

## Safelisting on Windows

Before starting the domain safelisting installation, please download the
required scripts from the provided `.rar`
[here](https://cloud.box.com/s/kvc9cysgq1y2yldpvciwlpt7093ho78l).

### Per User Installation

Open `Add_OpenWith_WhiteListed_Domain.reg` in a text editor.

<Frame>
  <img alt="Box Tools" />
</Frame>

<Info>
  Additional entries can be added on a new line.
</Info>

Close the file (save changes), open a command prompt with admin privileges, and
navigate to the .reg file and type the following command.

```sh theme={null}
reg import "Add_OpenWith_WhiteListed_Domain.reg"
```

<Frame>
  <img alt="Box Tools" />
</Frame>

### Per Machine Installation

Open the following file in a text editor:

* `x64`: `Per Machine\64 bit\Add_OpenWith_WhiteListed_Domain.reg`
* `x86`: `Per Machine\32 bit\Add_OpenWith_WhiteListed_Domain.reg`

Replace the placeholder domain with the domain you would like allow.

<Frame>
  <img alt="Box Tools" />
</Frame>

<Info>
  Additional entries may be added on a new line.
</Info>

Close the file (save changes), open a command prompt with admin privileges, and
navigate to the .reg file and type the following command:

```sh theme={null}
reg import "Add_OpenWith_WhiteListed_Domain.reg"
```

<Frame>
  <img alt="Box Tools" />
</Frame>

Restart the Windows service: **Box Local Com Service** (`Box Edit.exe`) using
one of the following methods.

#### Via the command prompt

In a command prompt, enter:

* `net stop "Box Local Com Service"`
* `net start "Box Local Com Service"`

<Frame>
  <img alt="Box Tools" />
</Frame>

#### Via the UI

Press `Windows + R` and type `services.msc`.

<Frame>
  <img alt="Box Tools" />
</Frame>

Restart `Box Edit.exe` by finding `Box Edit` in the system tray.

<Frame>
  <img alt="Box Tools" />
</Frame>

Right click and select **Quit**.

Open `%programfiles%\Box\Box Edit` and run `Box Edit.exe`.

<Frame>
  <img alt="Box Tools" />
</Frame>

### Removing

* Run `Remove_ALL_OpenWith_WhiteListed_Domain.reg` to remove all domains at once
* Run `Remove_OpenWith_WhiteListed_Domain.reg` to remove specific domains. Use the instructions above to add domains to this .reg, which will remove domains.

## Safelisting on MacOS

### Steps

Download the bash script
[here](https://cloud.box.com/s/z5qhc7rts6mzrhzfx6cpxeb5ed4ve5u6).

Open the Terminal, go to the folder where the bash script was downloaded, and
add the right permissions by running this command:

```sh theme={null}
chmod u+rx OpenWith.sh
```

To **add** domains, run the following command in a terminal:

```sh theme={null}
./OpenWith.sh -a domain1 domain2 ...
```

To **remove** domains, run the following command in a terminal:

```sh theme={null}
./OpenWith.sh -r domain1 domain2 ...
```

To **clear all** domains, run the following command in a
terminal:

```sh theme={null}
./OpenWith.sh -c
```

To **list** all domains, run the following command in a terminal:

```sh theme={null}
./OpenWith.sh -l
```

### Notes

* When safelisting domains ensure you are entering the domains without the HTTP protocol (for example without `https://`) or any trailing path like `yourdomain.com/page/3`.
* All requests must come from a secure origin via HTTPS.
* Safelisting subdomains and ports is possible as the wildcard `*` is supported. For example, all subdomains could be safelisted by adding `*.yourdomain.com` to your list.

## Uninstalling

When Box Tools is uninstalled, all domains will be removed.

<RelatedLinks title="RELATED GUIDES" />


# Content Explorer
Source: https://developer.box.com/guides/embed/ui-elements/explorer



<RelatedLinks title="REQUIRED GUIDES" />

The Box Content Explorer UI Element allows developers to embed a folder view of
content stored on Box in their desktop or mobile web application. The library
fetches information about a specified folder through the Box API and then
renders the content in a folder view, similar to the main Box web application.
Users can then navigate through the folder hierarchy and perform file operations
like rename, delete, and share.

Content Explorer comes with a <Link href="/guides/embed/ui-elements/explorer-metadata-v2">metadata view</Link> that uses
metadata query to find files and folders based
on their metadata. The data is then displayed in the embedded view.

## Installation

<Link href="/guides/embed/ui-elements/installation">Learn how to install</Link> Box UI elements
either through NPM or the Box CDN.

## Authentication

The UI Elements are designed in an authentication agnostic way so whether
you are using UI Elements for users who have Box accounts (Managed Users) or
non-Box accounts (App Users), UI Elements should work out of the box. The
reason for this is that UI Elements only expect a "token" to be passed in for
authentication, and Box provides two different ways to generate tokens - OAuth
and JWT.

<Card href={localizeLink("/guides/authentication")} title="Compare authentication methods" />

## Sample HTML

```html theme={null}
<!DOCTYPE html>
<html lang="en-US">
    <head>
        <meta charset="utf-8" />
        <title>Box Content Explorer Demo</title>

        <!-- Latest version of the explorer css for your locale -->
        <link
            rel="stylesheet"
            href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.css" />
    </head>
    <body>
        <div class="container" style="height:600px"></div>
        <!-- Latest version of the explorer js for your locale -->
        <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.js"></script>
        <script>
            var folderId = "123";
            var accessToken = "abc";
            var contentExplorer = new Box.ContentExplorer();
            contentExplorer.show(folderId, accessToken, {
                container: ".container",
            });
        </script>
    </body>
</html>
```

## Demo

<iframe title="Box Content Explorer" />

## API

```js theme={null}
const { ContentExplorer } = Box;
const contentExplorer = new ContentExplorer();

/**
 * Shows the content explorer.
 *
 * @param {string} folderId - The root folder id
 * @param {string} accessToken - Box API access token
 * @param {Object} [options] - Options
 * @return {void}
 */
contentExplorer.show(folderId, accessToken, options);

/**
 * Hides the content explorer, removes all event listeners, and clears out the
 * HTML.
 *
 * @return {void}
 */
contentExplorer.hide();

/**
 * Clears out the internal in-memory
 * cache for the content explorer forcing
 * re-load of items via the API.
 *
 * @public
 * @return {void}
 */
contentExplorer.clearCache();

/**
 * Adds an event listener to the content explorer. Listeners should be added
 * before calling show() so no events are missed.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentExplorer.addListener(eventName, listener);

/**
 * Removes an event listener from the content explorer.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentExplorer.removeListener(eventName, listener);

/**
 * Removes all event listeners from the content explorer.
 *
 * @return {void}
 */
contentExplorer.removeAllListeners();
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `folderId` | String | Box Folder ID. This will be the ID of the folder you want to navigate. If you want to use the Box All Files folder, then use `0` as the `folderId`. |
| `accessToken` | String | Box API access token to use. This should have read/write access to the folder above. The value passed in for the token is assumed to never expire while the explorer is visible. |
| `options` | Object | Optional options. See below for details. For example: `contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})` would be used to hide the delete option. |

### Options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `container` | String | `document.body` | CSS selector of the container in which the content explorer should be placed. Calling hide() will clear out this container. |
| `sortBy` | String | `name` | The initial sort by option for the content list. Value can be either `id`, `name`, `date` or `size`. |
| `sortDirection` | String | `ASC` | The initial sort direction option for the content list. Value should be either `ASC` or `DESC`. |
| `logoUrl` | String | | URL of custom logo to show in header. If this value is the string box then the box logo will show. |
| `canPreview` | Boolean | `true` | If this option is set to `true` AND `can_preview` permission on the file is `true`, files on the content explorer will be clickable. Clicking on a file will launch preview of that file. This option has no effect when the file permission `can_preview` is set to `false`. This is only applicable to files that can be previewed. |
| `canDownload` | Boolean | `true` | Visually hides the download option if this is set to `false`. Hiding the option alone will not prevent downloading unless the file permissions also set `can_download` to `false`. This option has no effect when the file permission `can_download` is set to `false`. This is only applicable to files. |
| `canDelete` | Boolean | `true` | Visually hides the delete option if this is set to `false`. Hiding the option alone will not prevent deleting unless the item permissions also set `can_delete` to `false`. This option has no effect when the item permission `can_delete` is set to `false`. |
| `canRename` | Boolean | `true` | Visually hides the rename option if this is set to `false`. Hiding the option alone will not prevent renaming unless the item permissions also set `can_rename` to `false`. |
| `canUpload` | Boolean | `true` | Visually hides the upload option if this is set to `false`. Hiding the option alone will not prevent uploading unless the current folder permissions also set `can_upload` to `false`. This option has no effect when the folder permission `can_upload` is set to `false`. |
| `canCreateNewFolder` | Boolean | `true` | Visually hides the create new folder option. Hiding the option alone will not prevent creating a new folder unless the folder item permissions also set `can_upload` to `false`. This option has no effect when the folder item permission `can_upload` is set to `false`. |
| `canShare` | Boolean | `true` | Visually hides the share button if set to `false`. Hiding the button alone will not prevent sharing unless the item `permissions` also set `can_share` to false. This option has no effect when the item permission `can_share` is set to `false`. |
| `canSetShareAccess` | Boolean | `true` | Visually hides the sharing drop down select that allows changing share access, if set to `false`. Hiding the select drop down alone will not prevent changing the share access unless the item permissions also set `can_set_share_access` to `false`. This option has no effect when the item permission `can_set_share_access` is set to `false`. |
| `sharedLink` | String | | Shared link URL, required if folder is shared and the access token doesn't belong to an owner or collaborator of the file. |
| `sharedLinkPassword` | String | | Shared link password, required if shared link has a password. |
| `size` | String | `undefined` | Indicates to the content explorer to fit within a small or large width container. Value can be absent or one of `small` or `large`. If absent the UI Element will adapt to its container and automatically switch between `small` width or `large` width mode. |
| `isTouch` | Boolean | Defaults to the browser and device's default touch support | Indicates to the Content Explorer that it is being rendered on a touch enabled device. |
| `autoFocus` | Boolean | `false` | When set to `true`, the item grid will get focus on initial load. |
| `defaultView` | String | `files` | Value can be either be `files`, `recents` or `metadata`. When set to `recents`, by default you will see recent items instead of the regular file/folder structure. `metadata` is required to display the metadata view in Content Explorer. If not provided, you'll get a regular folder view. |
| `requestInterceptor` | Function | | Function to intercept requests. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |
| `responseInterceptor` | Function | | Function to intercept responses. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |
| `ContentOpenWithProps` | Object | `{ show: false }` | Allows you to show the Open With Element when previewing via the explorer. |
| `token` | String | | Developer token generated in the Developer Console. |
| `metadataQuery` | Object | | Metadata query used to get the information for the metadata view. |
| `rootFolderID` | String | | Folder ID with a metadata template applied. `metadataQuery` will apply to this folder. |
| `fieldsToShow` | Object | | The metadata fields/columns to view - must be valid field names from the metadata template. |

### Events

| Event Name | Event Data | Description |
| - | - | - |
| `select` | `Array<File \| Web Link \| Folder>` | Will be fired when item rows are selected. |
| `rename` | `File \| Web Link \| Folder` | Will be fired when an item is renamed. |
| `preview` | `File` | Will be fired when a file is previewed. |
| `download` | `Array<File>` | Will be fired when items are downloaded. |
| `delete` | `Array<File>` | Will be fired when items are deleted. |
| `upload` | `Array<File>` | Will be fired when items are uploaded. |
| `navigate` | `Folder` | Will be fired when navigating into folders. |
| `create` | `Folder` | Will be fired when a new folder is created. |

## Keyboard Shortcuts

When the item grid has focus, either manually by clicking on it or
programmatically via javascript or via the above mentioned `autoFocus` prop, the
following keyboard shortcuts will work if their corresponding operations are
applicable and allowed.

| Key | Action |
| - | - |
| `Arrow Up` | Previous item row |
| `Arrow Down` | Next item row |
| `Ctrl/Cmd + Arrow Up` | First item row |
| `Ctrl/Cmd + Arrow Down` | Last item row |
| `/` | Search |
| `Shift + X` | Select an item row |
| `Delete` | Delete the selected item |
| `Enter` | Open the selected item |
| `Shift + R` | Rename the selected item |
| `Shift + S` | Share the selected item |
| `Shift + D` | Download the selected item |
| `g then f` | Navigates to the root folder |
| `g then u` | Upload to the current folder |
| `g then b` | Focuses the root folder breadcrumb |
| `g then r` | Recent items |

## Scopes

If your application requires the end user to only be able to access a subset of
the Content Explorer functionality, you can use <Link href="/guides/authentication/tokens/downscope">Downscoping</Link> to
appropriately downscope the Access Token to a resulting token that has the
desired set of permissions, and can thus, be securely passed to the end user
client initializing the Content Explorer.

Below are a set of UI Element-specific scopes to go alongside Downscoping. These
allow developers to enable/disable UI controls on the Content Explorer by
configuring the appropriate scopes on the downscoped token. To learn
more, see <Link href="/guides/api-calls/permissions-and-errors/scopes">Dedicated Scopes for Box UI Elements</Link>.

### Base Scope

| Scope Name | Permissions granted |
| - | - |
| `base_explorer` | Allows access to content in the folder tree based on user/file/token permissions. |

### Feature Scopes

| Scope Name | Permissions granted |
| - | - |
| `item_preview` | Automatically enables preview of the file, upon user click (requires Preview UI Element to be referenced) |
| `item_download` | Allows files/folders contents to be downloaded |
| `item_rename` | Allows files/folders to be renamed |
| `item_share` | Allows sharing of resource specified under "resource" of the downscope request. |
| `item_delete` | Allows file/folders to be deleted |

### Sample Scenarios

| Scenario | Scopes |
| - | - |
| User wants to navigate folder structure (basic functionality) | `base_explorer` |
| User wants basic functionality + preview | `base_explorer` + `item_preview` |
| User wants basic functionality + preview + download | `base_explorer` + `item_preview` + `item_download` |
| User wants basic functionality + preview + download + rename file/folder names | `base_explorer` + `item_preview` + `item_download` + `item_rename` |
| User wants all functionality (basic, preview, download, rename, share, upload and delete) | `base_explorer` + `item_preview` + `item_download` + `item_rename` + `item_delete` + `item_share` + `item_upload` |

## Custom actions

You can expand the actions in the **More Options** menu for files and folders in Content Explorer and Content Picker. Your custom options show when a user clicks the ellipsis button.

To customize the **More Options** menu, pass an array of custom actions to `itemActions`.

```js theme={null}
contentExplorer.show(configData.FOLDER_ID, configData.ACCESS_TOKEN, {
    container: ".container",
    itemActions: customActions,
});
```

The array can include multiple actions. The action object should include the `label` and `onAction` callback functions. You can filter the custom actions to appear only on a specific item `type`, by passing the `file` or `folder` value. The `filter` value is used for advanced filtering, for example by a specific file extension:

```js theme={null}
const customActions = [
    {
        label: "Preview in New Window",
        onAction: (item) => alert('action ' + item),
        type: 'file',
    },
    {
        label: "Open in Box.com",
        onAction: (item) => window.open("https://app.box.com"),
    },
    {
        label: "Export",
        onAction: (item) => console.log('action ' + item),
        filter: (item) => item.extension?.toLowerCase() === 'pdf',
    }
];
```

See the implemented examples in CodePen:

<iframe title="Box custom icons" />

[box-app]: /guides/applications/platform-apps/index

[token]: /guides/authentication/tokens/developer-tokens

[templates]: /guides/metadata/templates

[metadata-project]: https://github.com/box-community/content-explorer-metadata/tree/main

[apply-templates]: https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata

[metadata-query]: /guides/metadata/queries

[get-template]: /guides/metadata/templates/get/#get-a-metadata-template-by-name

[creating-templates-api]: /guides/metadata/templates/create

[appjs]: https://github.com/box-community/content-explorer-metadata/blob/main/src/App.js

[blogpost]: https://medium.com/box-developer-blog/metadata-view-in-box-content-explorer-4978e47e97e9

<RelatedLinks title="RELATED GUIDES" />


# Content Explorer - metadata view v1
Source: https://developer.box.com/guides/embed/ui-elements/explorer-metadata-v1



<RelatedLinks title="REQUIRED GUIDES" />

<Note>
  The `v1` of the metadata view Content Explorer has reached end of support. While `v1` remains available in the `24.0.0` package, it no longer receives bug fixes or new features. Follow the migration guide and switch to the `v2` metadata view of Content Explorer in order to receive the newest features.
</Note>

With Content Explorer you can display files and folders based on their metadata.
The metadata view uses <Link href="/reference/get-metadata-templates-id">metadata template</Link> and <Link href="/guides/metadata/queries">metadata query</Link> to find the data you want to display.

<Frame>
  <img alt="Metadata view" />
</Frame>

## Prerequisites

* Read the <Link href="/guides/embed/ui-elements/explorer">Content Explorer</Link> guide.
* Check the <Link href="/guides/metadata/#metadata-terminology">metadata terminology</Link>.
* Check the information on <Link href="/guides/metadata/queries">metadata queries</Link>.

## Create and configure an app

1. <Link href="/guides/applications/platform-apps/create">Create a Box app</Link>.
2. Add the local development address in the CORS Domains: <img alt="CORS Domains" />
3. Generate a <Link href="/guides/authentication/tokens/developer-tokens">developer token</Link>.

## Create a metadata template

The next step is to create a metadata template.

1. Use <Link href="/guides/metadata/templates/create">Metadata API</Link> or [Admin Console][creating-templates-ui] to create the template.
2. Apply an already created template to a Box folder. Make sure you enable the
   cascade policy. For detailed instructions, see
   [instructions on customizing and applying templates][apply-templates].

<Note>
  You can also apply a metadata template to a file.
</Note>

### Display name and key parameters

* The `displayName` parameter is the display name of the template visible
  in the Admin Console.
* The `templateKey` parameter is a unique identifier of the template. It needs
  to be unique across the enterprise for which you create the metadata template.
  If you don't provide the `templateKey` parameter, the API creates a unique one
  based on the value in `displayName`.
* The `[fields].displayName` parameter is the display name of the field as it
  is shown to the user in the web and mobile apps.
* The `[fields].key` parameter is a unique identifier for a specific field in
  the template. The identifier must be unique within the template to which it
  belongs.

## Display metadata view

Proceed to fill in the necessary properties passed to the Content Explorer.
To make things easier, you can use a [sample project][metadata-project] based on a basic React app to launch metadata view.

1. Clone the metadata sample project.

2. Update the placeholders in [`App.js`][appjs] with actual values:

   | Parameter | Description |
   | - | - |
   | `DEVELOPER_TOKEN` | <Link href="/guides/authentication/tokens/developer-tokens">Developer token</Link> generated in the Developer Console. |
   | `ENTERPRISE_ID` | Enterprise ID copied from the **General Settings** tab of your Box application. |
   | `METADATA_TEMPLATE_NAME` | `templateKey` of your already created metadata template. **Note**: To make sure you provided the proper name, use the <Link href="/guides/metadata/templates/get/#get-a-metadata-template-by-name">metadata API</Link> to retrieve the name, or copy it from the URL in the Admin Console. <img alt="Metadata name in Admin Console" /> If you decide to change the template name in the UI, you change the display name only. The name to use in the component is always the one you provided at the beginning. |
   | `METADATA_SOURCE` | Source of your <Link href="/guides/metadata/scopes">metadata</Link>. It's a string that combines the scope, enterprise ID, and metadata key. |
   | `ROOTFOLDER_ID` | ID of a Box folder to which you want to apply the metadata query and display filtered files. |

   The `defaultView`, `fieldsToShow`, and `metadataQuery` parameters are already
   defined in the sample project. Examples of these parameters are available in the sample project.

   | Parameter | Description |
   | - | - |
   | `defaultView` | A required prop to paint the metadata view. If it's not provided, you get the regular file view. |
   | `fieldsToShow` | Add or hide specific metadata columns to display in the Content Explorer. |
   | `metadataQuery` | Provides a way to find files and folders by searching for the metadata attached to them. For additional information on metadata queries, see <Link href="/guides/metadata/queries">this guide</Link>. |

3. Pass the required parameters to the Content Explorer component.

A sample code for a React component including the Content Explorer metadata view would look as follows:

```js theme={null}
function App() {
    const token = "<DEVELOPER_TOKEN>";
    const rootFolderID = "<ROOTFOLDER_ID>";
    const EID = "<ENTERPRISE_ID>";
    const templateName = "<METADATA_TEMPLATE_NAME>";
    const metadataSource = `enterprise_${EID}.${templateName}`;
    const metadataSourceFieldName = `metadata.${metadataSource}`;
    const metadataQuery = {
    	from: metadataSource,
    	query: "key = :arg1",
    	query_params: { arg1: "value" },
    	ancestor_folder_id: 0,
    	fields: [
        `${metadataSourceFieldName}.name`,
        `${metadataSourceFieldName}.last_contacted_at`,
        `${metadataSourceFieldName}.industry`,
        `${metadataSourceFieldName}.role`,
        ],
    };

    const fieldsToShow = [
    // canEdit propetry determines if the user can edit the metadata directly from Content Explorer component
    { key: `${metadataSourceFieldName}.name`, canEdit: false },
    // displayName alows to change the label on metadata column
    { key: `${metadataSourceFieldName}.industry`, canEdit: false, displayName: "alias" },
    { key: `${metadataSourceFieldName}.last_contacted_at`, canEdit: true },
    { key: `${metadataSourceFieldName}.role`, canEdit: true },
    ];

const defaultView = "metadata";
return (
    <IntlProvider locale="en">
        <div className="App">
            <header className="App-header">
                <h2>Metadata view in Content Explorer</h2>
            </header>
            <section>
                <div className="metadata-based-view">
                    <ContentExplorer
                        rootFolderId={rootFolderID}
                        token={token}
                        metadataQuery={metadataQuery}
                        fieldsToShow={fieldsToShow}
                        defaultView={defaultView}
                    />
                </div>
            </section>
        </div>
    </IntlProvider>
);
}

export default App;
```

## Metadata keys

To decide which fields to show, the Content Explorer uses metadata
<Link href="/reference/post-metadata-templates-schema/#param-fields-key">field keys</Link>, not the <Link href="/reference/post-metadata-templates-schema/#param-fields-displayName">display names</Link>. You can see the
display names in the Admin Console and user view, but you can obtain the field
keys through the API.

The field keys are not changing, even if you change the metadata display name.
This ensures that the functionality works properly, despite any changes to the
metadata in UI view.

### Metadata keys sanitization

<Link href="/reference/post-metadata-templates-schema/#param-fields-key">Keys</Link> are restricted to alphanumeric characters only:

* No hyphens `-` or underscores `_` are permitted.
* Only letters (`a-z, A-Z`) and numbers (`0-9`) are allowed.

**Non-Latin characters:**

If keys contain characters from non-Latin alphabets (such as Cyrillic, Arabic,
Chinese, etc.) they are automatically renamed to generic identifiers:

* `field` for the first occurrence
* `field1`, `field2`, and so on for subsequent occurrences

Keys are based on the display names.

<Note>
  **TIP**: For a detailed flow, see [Metadata view blog post][blogpost].
</Note>

[blogpost]: https://medium.com/box-developer-blog/metadata-view-in-box-content-explorer-4978e47e97e9

[creating-templates-ui]: https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates

[appjs]: https://github.com/box-community/content-explorer-metadata/blob/main/src/App.js

[apply-templates]: https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata

[metadata-project]: https://github.com/box-community/content-explorer-metadata/tree/main

[get-id]: /reference/get-metadata-templates-id-id-schema/

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# Content Explorer – metadata view v2
Source: https://developer.box.com/guides/embed/ui-elements/explorer-metadata-v2



<RelatedLinks title="REQUIRED GUIDES" />

The metadata view of <Link href="/guides/embed/ui-elements/explorer/">Content Explorer</Link> allows you to display files and folders based on their metadata.

## Overview

The metadata view `v2` is a ground-up redesign of the original metadata view of the Box Content Explorer UI element. It introduces a streamlined interface tailored for metadata-driven workflows. Key features include filtering and editing interfaces with dedicated UI for each metadata field type, flexible display options with list and grid views, pagination support, and more.

<Frame>
  <img alt="Metadata view" />
</Frame>

## Prerequisites

Before implementing the metadata view `v2` of Content Explorer, ensure you have:

* The `box-ui-elements` package `v24.0.0`+, React `v18.0.0`, and `Node.js` `v18.0.0`+
* The platform app with proper CORS settings
* A valid <Link href="/guides/authentication/tokens/developer-tokens/">developer token</Link>
* A configured metadata template applied to target folder or files. See <Link href="/guides/metadata/templates/create">creating templates with API</Link> or [with the Admin Console][creating-templates-ui].

<Tip>
  Make sure you enable the cascade policy. For detailed instructions, see
  [instructions on customizing and applying templates][apply-templates].
</Tip>

## Interface areas

The metadata view interface consists of the following areas:

* **Header** – Displays the current view title, navigation, and context-sensitive information like selection counts. The header value can be specified with a `title` prop. If it’s not defined, it defaults to the folder name specified in the `ancestor_folder_id`.
* **Action bar** – Contains filter chips for each metadata field, sort options, and the view mode toggle button (list or grid).
* **Pagination footer** – Provides the **Previous** and **Next** navigation buttons and page indicators.

## Display metadata view

To display the metadata view of Content Explorer, you need the following properties:

| Property | Description |
| - | - |
| `token` | Developer token generated in the Developer Console. |
| `title` | The title of the whole component, if not defined, defaults to the folder name specified in the `ancestor_folder_id`. |
| `defaultView` | Must be set to `metadata`. |
| `features.contentExplorer.metadataViewV2` | Must be set to true to enable the metadata view (v2). |
| `metadataQuery` | Metadata query request body matching the <Link href="/reference/post-metadata-queries-execute-read/">Metadata Query API</Link> schema. |
| `metadataViewProps` | Component configuration. For configuration details, see `metadataViewProps` object. |
| `columns` | Defines the structure and behavior of your metadata table columns. See Columns for details. |

Depending on your needs and setup, Box UI Elements can be used with Vanilla JavaScript or React. You can learn more about installation from the <Link href="/guides/embed/ui-elements/installation">Installation</Link> guide.

<Note>
  **Capitalized strings need to be replaced with your custom values.**
</Note>

### Vanilla JavaScript code snippet

```js theme={null}
const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
  container: ".container",
  defaultView: "metadata",
  // metadataQuery must match the query files/folders by metadata API body request:
  // </reference/post-metadata-queries-execute-read/>
  metadataQuery: {
    from: "METADATA_SCOPE.TEMPLATE_KEY", // For example from: "enterprise_123456789.templatename" where the number is the enterprise_123456789 is metadata template scope)
    ancestor_folder_id: "FOLDER_ID"
    // Metadata fields and values pulled to the component
    fields: [
        "metadata.TEMPLATE_SCOPE.TEMPLATE_KEY.FIELD_KEY1",
        "metadata.TEMPLATE_SCOPE.TEMPLATE_KEY.FIELD_KEY2",
        "metadata.TEMPLATE_SCOPE.TEMPLATE_KEY.FIELD_KEY3",  // For example "metadata.enterprise_123456789.templatename.date"
        ...
    ]
    // Optional for filtering data with specific metadata value
    query: "METADATA_FIELD_KEY = :arg1",
    query_params: { arg1: "METADATA_FIELD_VALUE" },
  },
  features: {
    contentExplorer: {
      metadataViewV2: true, // Required for enabling V2
    },
  },
 // NEW dynamic column configuration
  metadataViewProps: {
    columns // Required - for details see section below
    ...
  }
});
```

### React code snippet

```js theme={null}
import React from 'react';
import { IntlProvider } from 'react-intl';
import ContentExplorer from "box-ui-elements/es/elements/content-explorer"

// Fill with custom values of your metadata template
// You can use this endpoint to get all needed values: /reference/get-metadata-templates-id-id-schema/
const metadataScopeAndKey = `${METADATA_TEMPLATE_SCOPE}.${METADATA_TEMPLATE_KEY}`;
const metadataFieldNamePrefix = `metadata.${metadataScopeAndKey}`;
const folderID = "FOLDER_ID"

const metadataQuery = {
   // Check this endpoint for more details on query structure:
   // /reference/post-metadata-queries-execute-read/
   from: metadataScopeAndKey,
   ancestor_folder_id: folderID,
   fields: [
      "metadata.METADATA_SCOPE.TEMPLATE_KEY.METADATA_FIELD_KEY1",
      "metadata.METADATA_SCOPE.TEMPLATE_KEY.METADATA_FIELD_KEY2",  // For example "metadata.enterprise_123456789.templatename.date"
      ...
   ]
};

// Required - for details see section below
const columns = [
   {
      textValue: "METADATA_FIELD_DISPLAY_NAME1", // or our your custom value
      id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY1}`,
      type: field.type,
      allowsSorting: true,
      minWidth: 150,
      maxWidth: 150,
   },
   {
      textValue: "METADATA_FIELD_DISPLAY_NAME2", // or our your custom value
      id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY2}`,
      type: field.type,
      allowsSorting: true,
      minWidth: 150,
      maxWidth: 150,
   },
   ...
];

const componentProps = {
 features: {
   contentExplorer: {
       metadataViewV2: true,
   },
 },
 metadataQuery,
 metadataViewProps: {
   columns
 },
};

const ContentExplorerContainer = () => {
 const { features, metadataQuery, metadataViewProps } = componentProps;
 // Store token in a secure way
 return (
   <IntlProvider locale="en">
     <ContentExplorer
       token={TOKEN}
       defaultView="metadata"
       features={features}
       metadataQuery={metadataQuery}
       metadataViewProps={metadataViewProps}
     />
   </IntlProvider>
 );
};

export default ContentExplorerContainer;
```

## Columns

The columns prop defines the structure and behavior of your metadata table columns.

| Property | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | Metadata field identifier in the following format: `metadata.<scope>.<templateKey>.<field>` |
| `textValue` | string | Yes | Column header display name. |
| `type` | string | Yes | Box metadata field type (`string`, `number`, `date`, `singleSelect`, `multiSelect`). |
| `allowsSorting` | boolean | No | Enables column header sorting. |
| `minWidth` | number | No | Minimum column width in pixels. |
| `maxWidth` | number | No | Maximum column width in pixels. |

## Features

### Enabling row selection

You can enable selecting individual rows. When one or more rows are selected, the header updates to show a selection descriptor and a metadata edit button. This allows users to perform single or bulk actions. Row selection is scoped to the paginated content.

<Frame>
  <img alt="Row selection" />
</Frame>

To enable the selection feature, set the `isSelectionEnabled` property to `true` within the `metadataViewProps` object:

```js theme={null}
const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
 ...
 metadataViewProps: {
   columns,
   isSelectionEnabled: true
 },
});
```

### Editing metadata values

When one or more items are selected, the component header displays the selected count and the **Metadata** button becomes active. Clicking the **Metadata** button opens a sidebar that lets users view and edit metadata for the selected items.

<Frame>
  <img alt="Editing metadata" />
</Frame>

This behavior is enabled by default; no additional properties are required to activate it.

### Filtering metadata

Filter items by the file type, filter folders, or filter by metadata field values specified in the Box <Link href="/guides/metadata/templates/">metadata templates</Link>.

Filter chips are enabled by default. To disable the **All Filters** chip, set the `isAllFiltersDisabled` to `true` in the `actionBarProps` object:

```js theme={null}
const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
 ...
metadataViewProps: {
    columns,
    isSelectionEnabled: true,
    actionBarProps: { 
        isAllFiltersDisabled: true,
    }
  },
});
```

### Toggling list and grid view

Grid view is available by default through the view mode toggle button in the action bar. When the grid view is active, a zoom control becomes available. Other functionalities like selecting, filtering, and editing are also available within this view.

<Frame>
  <img alt="Grid view" />
</Frame>

To disable grid view, set `actionBarProps.isViewModeButtonDisabled` to `true` within the `metadataViewProps` object:

```js theme={null}
const contentExplorer = new Box.ContentExplorer();

contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
 ...
 metadataViewProps: {
   columns,
   actionBarProps: {
     isViewModeButtonDisabled: true,
   }
 },
});
```

### Pagination

The UI Element uses marker-based pagination only, with the footer always visible. You cannot set an offset or page number. Users can navigate using only **Previous** and **Next**. Infinite scrolling is not supported.

## Migrating from v1 to v2

### Npm package

<Note>
  The `v1` of the metadata view Content Explorer has reached end of support. While `v1` remains available in the `24.0.0` package, it will no longer receive bug fixes or new features. Follow the migration guide and switch to the `v2` metadata view of Content Explorer in order to receive the newest features.
</Note>

To migrate from `v1` to v2 in projects using `box-ui-elements` package:

1. Upgrade the `box-ui-elements` package version to version `24.0.0` or higher.
2. Ensure `box-ui-elements` peer dependencies are added as dependencies in your `package.json` file. Install them with your package manager.
3. Add the `features` flag to enable the enhanced metadata view.

```js theme={null}
features: {
   contentExplorer: {
       metadataViewV2: true
   }
}
```

4. Convert your metadata `fieldToShow` configuration to the new column object. Add field types that correspond with the values in the Box metadata template. Pass the columns array to the new `metadataViewProps` object.

```js theme={null}
const columns = [
    {
       textValue: "METADATA_FIELD_DISPLAY_NAME", // Altenratively pass a custom value
       id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY}`,
       type: field.type,
       allowsSorting: true, // Optional
       minWidth: 150, // Optional; the default value is 220
       maxWidth: 150, // Optional; the default value is 220
    },
    ...
];
```

5. Optionally, configure additional features described in this guide.

### CDN

To migrate from `v1` to v2 in projects using CDN imports:

1. Ensure that CDN link includes package version with version `24.0.0` or higher.
2. Add the `features` flag to enable the enhanced metadata view.

```js theme={null}
features: {
   contentExplorer: {
       metadataViewV2: true
   }
}
```

3. Convert your metadata `fieldToShow` configuration to the new column object. Add field types that correspond with the values in the Box metadata template. Pass the columns array to the new `metadataViewProps` object.

```js theme={null}
const columns = [
    {
       textValue: "METADATA_FIELD_DISPLAY_NAME", // Altenratively pass a custom value
       id: `${metadataFieldNamePrefix}.${METADATA_FIELD_KEY}`,
       type: field.type,
       allowsSorting: true, // Optional
       minWidth: 150, // Optional; the default value is 220
       maxWidth: 150, // Optional; the default value is 220
    },
    ...
];
```

4. Optionally, configure additional features described in this guide.

[terminology]: /guides/metadata/#metadata-terminology

[creating-templates-ui]: https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates

[apply-templates]: https://support.box.com/hc/en-us/articles/360044196173-Using-Metadata

<RelatedLinks title="RELATED APIS" />

<RelatedLinks title="RELATED GUIDES" />


# UI Elements
Source: https://developer.box.com/guides/embed/ui-elements/index



Box UI Elements are pre-built UI components that allow developers to add
elements of the main Box web application into their own applications. They can
be used to navigate through, upload, preview, and select content stored on Box
and are available both as React components and framework-agnostic JavaScript
libraries.

## Available Elements

Box offers several UI Elements to create common user experiences with files and
folders in an application.

The available UI Elements are:

* <Link href="/guides/embed/ui-elements/explorer">Content Explorer</Link> - Allow users to search and browse through files and folders. It also has a metadata query based view <Link href="/guides/embed/ui-elements/explorer-metadata-v2">variant</Link> that supports items sorting, filtering, custom columns, and more.
* <Link href="/guides/embed/ui-elements/open-with">Content Open With</Link> - Allow users to open content stored in Box with a partner application using an embedded dropdown.

<Warning>
  We no longer support the `OpenWith` UI element for any new customers as of December 21, 2021.
</Warning>

* <Link href="/guides/embed/ui-elements/picker">Content Picker</Link> - Allow users to select files or folders from their Box account.
* <Link href="/guides/embed/ui-elements/preview">Content Preview</Link> - Display interactive viewers for documents, images, audio, video, and more.
* <Link href="/guides/embed/ui-elements/sidebar">Content Sidebar</Link> - Display a sidebar for file metadata and activity feed information.
* <Link href="/guides/embed/ui-elements/uploader">Content Uploader</Link> - Allow users to upload files by selecting or using drag-and-drop.

UI Elements can be used in isolation or joined together to construct common user
flows with content, such as uploading and then viewing a file.


# Installation
Source: https://developer.box.com/guides/embed/ui-elements/installation



UI Elements can be used either by downloading the Javascript libraries
directly from the Box CDN or by installing our [NPM package][npm]. All UI
Elements require their corresponding CSS stylesheet to render properly.

## Prerequisites

To use Box UI Elements, you need the following Node and React versions:

* Node version: `>=18.18.2 <22.11.0`
* React version `>=18.0.0 <=19.0.0`

The available versions of UI elements are listed in the [manual installation][manual-installation] section.

### Migration to React 19

For existing projects based on React 18 or below, check the [React 19 migration guide][react-migration].

<Warning>
  Update `react-tether` in your `package.json` to `>= v3.0.3` to avoid compatibility issues.
</Warning>

Once you upgrade React in your project, update the `box-ui-elements` package with `npm` or `yarn`:

```shell theme={null}
npm install box-ui-elements --legacy-peer-deps

yarn add box-ui-elements
```

This should result in an updated version in the `package.json` file:

```json theme={null}
"box-ui-elements": "^26.3.0"
```

No additional changes related to Box UI elements are required in your code.

For more information, check the blog post about React 19 upgrade for UI elements.

## NPM installation

Use this when you are building a React based app and would like to import the
components directly into your app at build time.

> **Note** The `--legacy-peer-deps` flag is necessary when installing UI elements with `npm` due to library dependencies.

```sh theme={null}
npm install box-ui-elements --legacy-peer-deps
yarn add box-ui-elements
```

<Card href="https://www.npmjs.com/package/box-ui-elements" title="Learn more on the NPM website" />

<Warning>
  ## Content Preview

  Use the Content Preview SDK if you need a specific
  version of the preview library. Otherwise,
  use Content Preview UI Element wrapper.
</Warning>

## Manual installation

All the UI elements are also available directly from the Box CDN.

| Element | Version | File |
| - | - | - |
| <Link href="/guides/embed/ui-elements/explorer">Content Explorer</Link> | `26.3.0` | CSS <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.css">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.css`</Link> |
| | | JS with React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.js`</Link> |
| | | JS without React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.no.react.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.no.react.js`</Link> |
| <Link href="/guides/embed/ui-elements/open-with">Content Open With</Link> | `26.3.0` | CSS <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/openwith.css">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/openwith.css`</Link> |
| | | JS with React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/openwith.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/openwith.js`</Link> |
| | | JS without React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/openwith.no.react.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/openwith.no.react.js`</Link> |
| <Link href="/guides/embed/ui-elements/picker">Content Picker</Link> | `26.3.0` | CSS <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/picker.css">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/picker.css`</Link> |
| | | JS with React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/picker.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/picker.js`</Link> |
| | | JS without React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/picker.no.react.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/picker.no.react.js`</Link> |
| <Link href="/guides/embed/ui-elements/sidebar">Content Sidebar</Link> | `26.3.0` | CSS <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/sidebar.css">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/sidebar.css`</Link> |
| | | JS with React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/sidebar.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/sidebar.js`</Link> |
| | | JS without React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/sidebar.no.react.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/sidebar.no.react.js`</Link> |
| <Link href="/guides/embed/ui-elements/uploader">Content Uploader</Link> | `26.3.0` | CSS <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/uploader.css">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/uploader.css`</Link> |
| | | JS with React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/uploader.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/uploader.js`</Link> |
| | | JS without React <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/uploader.no.react.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/uploader.no.react.js`</Link> |
| <Link href="https://github.com/box/box-content-preview">Content Preview UI Element</Link> | `26.3.0` | CSS <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/preview.css">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/preview.css`</Link> |
| | `26.3.0` | JS <Link href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/preview.js">`https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/preview.js`</Link> |
| <Link href="/guides/embed/ui-elements/preview">Content Preview SDK</Link> | `3.55.0` | CSS <Link href="https://cdn01.boxcdn.net/platform/preview/3.55.0/en-US/preview.css">`https://cdn01.boxcdn.net/platform/preview/3.55.0/en-US/preview.css`</Link> |
| | | JS <Link href="https://cdn01.boxcdn.net/platform/preview/3.55.0/en-US/preview.js">`https://cdn01.boxcdn.net/platform/preview/3.55.0/en-US/preview.js`</Link> |

Use these links to either download the elements code to your application's
code, or embed them straight into your page from the CDN.

```html theme={null}
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <!-- Latest version of the explorer css for your locale -->
    <link
      rel="stylesheet"
      href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.css"
    />
  </head>
  <body>
    <!-- Latest version of the explorer js for your locale -->
    <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/explorer.js"></script>
    ...
  </body>
</html>
```

For Box Preview, the sample would look slightly different.

```html theme={null}
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>Box Content Preview Demo</title>

    <!-- Latest version of Box Content Preview for en-US locale -->
    <script src="https://cdn01.boxcdn.net/platform/preview/{VERSION}/en-US/preview.js"></script>
    <link
      rel="stylesheet"
      href="https://cdn01.boxcdn.net/platform/preview/{VERSION}/en-US/preview.css"
    />
  </head>
  <body>
    <div class="preview-container" style="height:400px; width:100%;"></div>
    <script>
      var preview = new Box.Preview();
      preview.show("93392244621", "EqFyi1Yq1tD9mxY8F38sxDfp73pFd7FP", {
        container: ".preview-container",
        showDownload: true,
      });
    </script>
  </body>
</html>
```

### Versions

Most of the UI elements have 2 distinct versions.

* A standard `*.js` file (e.g. `explore.js`) that includes React and ReactDOM in the bundle.
  * Use this when you are not building a React based app or you don't want to include the components as part of your app's build process.
  * It includes React and ReactDOM libraries.
  * The file size of this asset will be larger than the one below.
* A smaller `*.no.react.js` file (e.g. `explore.no.react.js`) that does not get bundled with React and ReactDOM.
  * Use this when both React and ReactDOM libraries are already loaded on the application.
  * These libraries expect a React and ReactDOM `>= 16.6` and `< 18`.

<message>
  Only one of the two `js` files and the additional `css` file need to be added
  to a project.
</message>

### Supported Locales

The above asset URLs use `en-US`. If you want to use another locale, then
replace `en-US` in the URLs above with any of the following:

`en-AU`, `en-CA`, `en-GB`, `da-DK`, `de-DE`, `es-ES`, `fi-FI`, `fr-CA`, `fr-FR`,
`it-IT`, `ja-JP`, `ko-KR`, `nb-NO`, `nl-NL`, `pl-PL`, `pt-BR`, `ru-RU`,
`sv-SE`, `tr-TR`, `zh-CN`, `zh-TW`

## Self-hosting Content Preview

To serve the Box Content Preview library from your own server, follow these
steps.

### 1. Download release

Either fork the repository and check out the version you want to serve or
download the specific version as a zip.

* Check out a specific version with `git checkout v3.0.0`.
* Download a specific version as a zip from the [releases][preview-releases] page.

### 2. Install dependencies

Install the dependencies and build the library with the following command.

```sh theme={null}
yarn install && yarn build:i18n && yarn build:prod
```

### 3. Serve files

Self-serve everything except for the `dev` folder from the `/dist` folder. You
must not alter the folder structure and `third-party` needs to be in the same
folder as `3.0.0`.

For example, if you self-host using a `box-assets` directory, these URLs must
be accessible:

* `https://cdn.YOUR_SITE.com/box-assets/3.0.0/en-US/preview.js`
* `https://cdn.YOUR_SITE.com/box-assets/third-party/text/2.65.0/papaparse.min.js`
* `https://cdn.YOUR_SITE.com/box-assets/third-party/model3d/1.12.0/three.min.js`

## Authentication

In order to initialize any of the UI Elements, an application will need to
provide a valid Access Token.

<Card href={localizeLink("/guides/authentication")} title="Learn how to authenticate an application" />

It is also recommended to <Link href="/guides/authentication/tokens/downscope">downscope</Link> an Access Token before passing
it into an insecure environment (the user's web browser).

UI Elements only expect any Access Token to be passed in for authentication, and
can therefore be used for any type of authentication available from Box
Platform.

For testing purposes, a <Link href="/guides/authentication/tokens/developer-tokens">Developer Token</Link> can be used.

## CORS

To use UI Elements, an application needs to allow the domain the widget is
used on for Cross Origin Resource sharing. See the <Link href="/guides/security/cors">CORS guide</Link> for more
details.

## Source Code & Releases

Source code for Box UI Elements is [hosted on GitHub][gh]. The repository
contains detailed documentation for usage and development. Please file any bugs
you encounter under the "Issues" tab with clear steps to reproduce. This
repository also holds a list of [releases][releases].

[npm]: https://www.npmjs.com/package/box-ui-elements

[gh]: https://github.com/box/box-ui-elements

[releases]: https://github.com/box/box-ui-elements/releases

[scopes]: /guides/api-calls/permissions-and-errors/scopes

[preview-releases]: https://github.com/box/box-content-preview/releases

[manual-installation]: #manual-installation

[react-migration]: https://react.dev/blog/2024/04/25/react-19-upgrade-guide

<RelatedLinks title="RELATED GUIDES" />


# Customize Logo
Source: https://developer.box.com/guides/embed/ui-elements/logo



<RelatedLinks title="REQUIRED GUIDES" />

Each of the Box UI Elements allow for specifying a custom logo to place in the
top-left corner of the embedded container.

<Frame>
  <img alt="Custom logo" />
</Frame>

By default, each of the UI Elements uses a generic placeholder as a logo. This
is meant to be replaced by either a Box logo or a custom logo, such as a
company's logo.

To add a logo to a UI Element, supply a URL for a logo as an option in the
Javascript setup code. The following is an example of how to do this with the
Content Preview UI Element.

```js theme={null}
var preview = new Box.Preview();
preview.show(fileId, accessToken, {
    container: '.preview-container',
    sharedLink: 'https://app.box.com/v/foo',
    sharedLinkPassword: 'bar',
    collection: [FILE_ID, '123', '234', ...],
    header: 'light',
    logoUrl: 'https://developer.box.com/images/guides/embed/ui-elements/elements-logo.png',
    showAnnotations: true,
    showDownload: true
});
```

<Info>
  **Box Logo**

  To present the Box logo in a UI Element, specify the string `box` as the
  `logoURL` option.
</Info>

## Image size

Image files will be fitted to a maximum height of 32 pixels and a maximum width
of 80 pixels. Larger images will be shrunk to fit these dimensions.

<RelatedLinks title="RELATED GUIDES" />


# Content Open With
Source: https://developer.box.com/guides/embed/ui-elements/open-with



<RelatedLinks title="REQUIRED GUIDES" />

<Warning>
  We no longer support the `OpenWith` UI element for any new customers
  as of December 21, 2021.
</Warning>

The Box Content Open With UI Element allows developers to embed a dropdown to
open content stored in Box with a partner application, or locally on the
desktop.

The Element fetches information about enabled integrations using the
Box API, and calls out to partner services. Users can then take action in these
services, and the edited content will be automatically saved back to Box.

The integrations included in the Open With Element are Google Suite,
and Box Edit. Additional information on the Google Suite integration can be
found on the [Box Community site][community].

Currently, the element only supports <Link href="/guides/getting-started/users">App Users</Link>
for authentication.

## Installation

<Link href="/guides/embed/ui-elements/installation">Learn how to install</Link> Box UI elements
either through NPM or the Box CDN.

## Box Edit

Box Edit requires additional setup in order to be integrated into a platform
application. Box Edit uses the desktop application [Box Tools][tools] in order
to open content locally.

* Requests must use a secure connection (from an `https` domain)
* The application's domain must be allowed by Box Tools. Instructions can be found <Link href="/guides/embed/ui-elements/custom-domains">here</Link>. The ideal workflow is to bundle these steps within an installer that also installs Box Tools.
* Safari requires a browser extension to connect to box tools. More details can be found [here][safari].

## G Suite

A valid G Suite account is required in order to use the Box for G Suite
integration. To connect a user's G Suite and Box account, the
`external_app_user_id` of the app user must be updated to be the email address
associated with the user's G Suite account.

The `external_app_user_id` of an app user can be updated via the
<Link href="/reference/put-users-id">`PUT /users/:id`</Link> endpoint.

## Setup

The Open With UI Element is intended to be used after allowing your
application and enabling integrations for app users using Box API endpoints.

### Activate application

The 'Open With' UI Element is available to any developer building with the Box
Platform. To activate it for your instance, add the "Enable integrations" scope
to your application in the developer console.

<Frame>
  <img alt="Enable Integrations" />
</Frame>

Once your application has been activated for API calls it will need to be
reauthorized in your enterprise. The steps for performing these actions are
available <Link href="/guides/authorization/platform-app-approval">here</Link>.

## List available integrations

The first step to assigning an app integration to a user is to get the list of
integrations that are available. This `GET` request can be made with the following
`cURL` request.

```sh theme={null}
curl -X GET https://api.box.com/2.0/app_integrations \
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
```

```json theme={null}
{
  "next_marker": null,
  "entries": [
    { "type": "app_integration", "id": "10897" },
    { "type": "app_integration", "id": "1338" },
    { "type": "app_integration", "id": "13418" },
    { "type": "app_integration", "id": "3282" }
  ],
  "limit": 100
}
```

The app integration IDs are used to assign an integration to a given user.

## Get a specific integration

To obtain additional information about a specific integration, based on ID, the
following GET request may be made.

```sh theme={null}
curl -X GET \
    https://api.box.com/2.0/app_integrations/[APP_INTEGRATION_ID] \
    -H 'Authorization: Bearer [ACCESS_TOKEN]'
```

```json theme={null}
{
  "type": "app_integration",
  "id": "10897",
  "app": {
    "type": "app",
    "id": "336417"
  },
  "name": "Edit with G Suite",
  "description": "Securely manage your Google Docs, Sheets and Slides in Box",
  "executable_item_types": [
    "file"
  ],
  "restricted_extensions": [
    "docx",
    "gdoc",
    "xlsx",
    "gsheet",
    "pptx",
    "gslides",
    "gslide"
  ],
  "scoped_to": "parent"
}
```

## Add integration to user

To add an app integration to a valid app user, three pieces of information are
required:

* A valid <Link href="/guides/getting-started/users#service-account">Service Account</Link> Access Token.
* The ID of the app user to be assigned the integration
* The ID of the app integration to assign to the user

<Warning>
  While the two previous requests to get app integration information can be done
  with any valid token including a valid developer token, adding and removing
  app integrations requires a valid service account's access token. Using a
  developer token will produce a `404 Not Found` error.
</Warning>

The following `POST` request can be made to assign an app integration to an app
user:

```sh theme={null}
curl -X POST https://api.box.com/2.0/app_integration_assignments \
    -H 'Authorization: Bearer [SERVICE_ACCOUNT_TOKEN]' \
    -d '{
      "assignee": {
        "type": "user",
        "id": "[APP_USER_ID]"
      },
      "app_integration": {
        "type": "app_integration",
        "id": "[APP_INTEGRATION_ID]"
      }
    }'
```

```json theme={null}
{
  "type": "app_integration_assignment",
  "id": "72048301",
  "assignee": {
    "type": "user",
    "id": "6084519920"
  },
  "app_integration": {
    "type": "app_integration",
    "id": "3282"
  }
}
```

The ID in the JSON response can be used to manage app integrations after
assignment, and should be stored by the application.

## Remove integration from user

To remove an app integration from an app user, the following request may be made
with a valid service access token and the app integration assignment ID from the
previous step.

```sh theme={null}
curl -X DELETE https://api.box.com/2.0/app_integration_assignments/[APP_INTEGRATION_ASSIGNMENT_ID] \
    -H 'Authorization: Bearer [SERVICE_ACCOUNT_TOKEN]'
```

```sh theme={null}
204 No Content
```

## Sample HTML

```html theme={null}
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>Box Content Open With Demo</title>

    <!-- Latest version of the open with css for your locale -->
    <link
      rel="stylesheet"
      href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/openwith.css"
    />
  </head>
  <body>
    <div class="container" style="height:600px"></div>
    <!-- Latest version of the open with js for your locale -->
    <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/openwith.js"></script>
    <script>
      var fileId = "123";
      var accessToken = "abc";
      var contentOpenWith = new Box.ContentOpenWith();
      contentOpenWith.show(fileId, accessToken, {
        container: ".container"
      });
    </script>
  </body>
</html>
```

## Demo

### Open With Example

<iframe title="Box Open With Example" />

### Content Explorer + Open With Example

<iframe title="Box Content Explorer Example + Open With" />

<Info>
  **Access Token**

  These demos may not fully function until you provide a valid access token under
  the JS tab of the demo. For the Open With element, you must provide a valid
  <Link href="/guides/getting-started/users#service-account">Service Account</Link> Access Token.
</Info>

## Authentication

The UI Elements are designed in an authentication agnostic way so whether
you are using UI Elements for users who have Box accounts (Managed Users) or
non-Box accounts (App Users), UI Elements should work out of the box. The
reason for this is that UI Elements only expect a "token" to be passed in for
authentication, and Box provides two different ways to generate tokens - OAuth
and JWT.

<Card href={localizeLink("/guides/authentication")} title="Compare authentication methods" />

## Scopes

To run integrations with downscoped tokens, you must include the
`item_execute_integration` scope as well as the scope required by the specific
integration you would like to use.

* **Google**: `item_readwrite` on the parent folder
* **Adobe**: `root_readwrite`
* **Box Edit**: `item_readwrite` on the parent folder.
* **Box Edit Single File Collaboration**: `item_readwrite` on the file.

More information on scopes can be found <Link href="/guides/api-calls/permissions-and-errors/scopes">here</Link>.

## API

```js theme={null}
const { ContentOpenWith } = Box;
const contentOpenWith = new ContentOpenWith();

/**
 * Shows the content open with element.
 *
 * @param {string} fileId - The root file id
 * @param {string} accessToken - Box API access token
 * @param {Object} [options] - Options
 * @return {void}
 */
contentOpenWith.show(fileId, accessToken, options);

/**
 * Hides the content open with element, removes all event listeners,
 * and clears out the
 * HTML.
 *
 * @return {void}
 */
openWith.hide();

/**
 * Adds an event listener to the content open with element. Listeners should be added
 * before calling show() so no events are missed.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentOpenWith.addListener(eventName, listener);

/**
 * Removes an event listener from the content open with element.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
contentOpenWith.removeListener(eventName, listener);

/**
 * Removes all event listeners from the content open with element.
 *
 * @return {void}
 */
contentOpenWith.removeAllListeners();
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `fileId` | String | Box File ID. This will be the ID of the file for which you would like to execute integrations. |
| `accessToken` | String | Box API access token to use. This should have read/write access to the folder above. The value passed in for the token is assumed to never expire while the explorer is visible. |
| `options` | Object | Optional options. See below for details. For example: `contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})` would be used to hide the delete option. |

### Options

| Parameter | Type | Description |
| - | - | - |
| `dropdownAlignment` | `left \| right` | Determines the dropdown's alignment to the open with button. The default is `right`. |
| `boxToolsName` | `String` | This string will replace the name of Box Tools in the "Install Box Tools to open this file on your desktop" message. |
| `boxToolsInstallUrl` | `String` | This URL will be used instead of the default Box installation instructions which are linked in the "Install Box Tools to open this file on your desktop" message. |
| `onExecute` | `Function` | A callback that executes when an integration invocation is attempted. |
| `onError` | `Function` | A callback that executes when an error occurs. |
| `requestInterceptor` | `Function` | Function to intercept requests. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |
| `responseInterceptor` | `Function` | Function to intercept responses. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |

<Warning>
  Currently the `onError` and `onExecute` events are subject to a known bug. We recommend
  using `openWith.addListener('execute', callback)` and
  `openWith.addListener('error', callback)` as a temporary workaround.
</Warning>

### Events

| Event Name | Event Data | Description |
| - | - | - |
| `execute` | Integration ID | Will be fired when an integration invocation is executed. |
| `error` | Error | Will be fired when an error occurs. |

[community]: https://support.box.com/hc/en-us/articles/360043696994-Introducing-Box-for-G-Suite

[tools]: https://support.box.com/hc/en-us/categories/360003188014-Box-Tools

[safari]: https://support.box.com/hc/en-us/articles/360043697334-Installing-Box-Tools

<RelatedLinks title="RELATED GUIDES" />


# Content Picker
Source: https://developer.box.com/guides/embed/ui-elements/picker



<RelatedLinks title="REQUIRED GUIDES" />

The Box Content Picker UI Element allows developers to add support for selecting
files and folders from Box in their desktop or mobile web application. The
library fetches information about a specified folder through the Box API and
renders the content in a folder view. Users can select files or folders and this
content information is then passed to another part of the application.

## Installation

<Link href="/guides/embed/ui-elements/installation">Learn how to install</Link> Box UI elements
either through NPM or the Box CDN.

## Authentication

The UI Elements are designed in an authentication agnostic way so whether
you are using UI Elements for users who have Box accounts (Managed Users) or
non-Box accounts (App Users), UI Elements should work out of the box. The
reason for this is that UI Elements only expect a "token" to be passed in for
authentication, and Box provides two different ways to generate tokens - OAuth
and JWT.

<Card href={localizeLink("/guides/authentication")} title="Compare authentication methods" />

## Sample HTML

```html theme={null}
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>Box File Selection</title>

    <!-- Latest version of the picker css for your locale -->
    <link
      rel="stylesheet"
      href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.css"
    />
  </head>
  <body>
    <div class="container" style="height:600px"></div>
    <!-- Latest version of the picker js for your locale -->
    <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/picker.js"></script>
    <script>
      var folderId = "123";
      var accessToken = "abc";
      var filePicker = new Box.FilePicker();
      filePicker.show(folderId, accessToken, {
        container: ".container"
      });
    </script>
  </body>
</html>
```

## Demo

### File Selection Demo

<iframe title="Box File Picker" />

### Folder Selection Demo

<iframe title="Box Folder Picker" />

### File Selection + Preview Demo

<iframe title="Box File Picker + Box Preview" />

### File Selection as a popup

<iframe title="Box File Picker and Uploader as popups" />

<Info>
  **Access Token**

  These demos may not fully function until you provide a valid access token. For
  testing purposes, you can use your temporary developer token. This will need
  to be updated under the JS tab in the demo.
</Info>

## API

```js theme={null}
const { FilePicker } = Box;
const filePicker = new FilePicker();

/**
 * Shows the file selection.
 *
 * @public
 * @param {String} folderId - The root folder id.
 * @param {String} accessToken - The API access token.
 * @param {Object|void} [options] - Optional options.
 * @return {void}
 */
filePicker.show(folderId, accessToken, options);

/**
 * Hides the file picker, removes all event listeners, and clears out the HTML.
 *
 * @public
 * @return {void}
 */
filePicker.hide();

/**
 * Clears out the internal in-memory cache for the file picker. This forces
 * items to be reloaded from the API.
 *
 * @public
 * @return {void}
 */
filePicker.clearCache();

/**
 * Adds an event listener to the file picker. Listeners should be added before
 * calling show() so no events are missed.
 *
 * @public
 * @param {String} eventName - Name of the event.
 * @param {Function} listener - Callback function.
 * @return {void}
 */
filePicker.addListener(eventName, listener);

/**
 * Removes an event listener from the file picker.
 *
 * @public
 * @param {String} eventName - Name of the event.
 * @param {Function} listener - Callback function.
 * @return {void}
 */
filePicker.removeListener(eventName, listener);

/**
 * Removes all event listeners from the file picker.
 *
 * @public
 * @return {void}
 */
filePicker.removeAllListeners();
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `folderId` | String | Box Folder ID. This will be the ID of the folder from which you want the content to be picked. If you want to use the Box All Files folder, then use `0` as the `folderId`. |
| `accessToken` | String | Box API access token to use. This should have read/write access to the folder above. The value passed in for the token is assumed to never expire while the explorer is visible. |
| `options` | Object | Optional options. See below for details. For example: `contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})` would be used to hide the delete option. |

### Options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `container` | `String` | `document.body` | CSS selector of the container in which the content picker should be placed. Calling hide() will clear out this container. |
| `sortBy` | `String` | `name` | The initial sort by option for the content list. Value should be either name or `date`. |
| `sortDirection` | `String` | `ASC` | The initial sort direction option for the content list. Value should be either `ASC` or `DESC`. |
| `logoUrl` | `String` | | URL of custom logo to show in header. If this value is the string box then the box logo will show. |
| `extensions` | `Array<string>` | `[]` | Array of file extensions to be allowed for selection. For example `['doc', 'ppt']`. Applicable only to the File Picker and not the Folder Picker. If any extensions are provided, only those will have the ability to be selected. An empty array signifies all the file extensions are allowed for selection. |
| `maxSelectable` | `Number` | `Infinity` | Number of files or folders that can be selected. Specify 1 if you want only 1 file or folder selected. |
| `canUpload` | `Boolean` | `true` | Visually hides the upload option if this is set to `false`. Hiding the option alone will not prevent uploading unless the current folder permissions also set `can_upload` to `false`. This option has no effect when the folder permission `can_upload` is set to `false`. |
| `canSetShareAccess` | `Boolean` | `true` | Visually hides the sharing drop down select if set to `false`. Hiding the select drop down alone will not prevent changing the share access unless the folder item permissions also set `can_set_share_access` to `false`. This option has no effect when the folder item permission `can_set_share_access` is set to `false`. |
| `canCreateNewFolder` | `Boolean` | `true` | Visually hides the create new folder option. Hiding the option alone will not prevent creating a new folder unless the folder item permissions also set `can_upload` to `false`. This option has no effect when the folder item permission `can_upload` is set to false. |
| `sharedLink` | `String` | | Shared link URL, required if folder is shared and the access token doesn't belong to an owner or collaborator of the file. |
| `sharedLinkPassword` | `String` | | Shared link password, required if shared link has a password. |
| `modal` | `Object` | | When the modal attribute is specified, then the content pickers will not be created in-place. Instead a button will be created in the container and clicking this button will launch the content picker in a modal popup. |
| `size` | `String` | `undefined` | Indicates to the content picker to fit within a `small` or `large` width container. Value can be absent or one of `small` or `large`. If absent the UI Element will adapt to its container and automatically switch between small width or large width mode. |
| `isTouch` | Boolean | Defaults to the browser and device's default touch support | Indicates to the content explorer that it is being rendered on a touch enabled device. |
| `autoFocus` | `Boolean` | `false` | When set to `true`, the item grid will get focus on initial load. |
| `defaultView` | String | `files` | Value should either be `files` or `recents`. When set to `recents`, by default you will see recent items instead of the regular file/folder structure. |
| `chooseButtonLabel` | `String` | | String to re-label the Choose button |
| `cancelButtonLabel` | `String` | | String to re-label the Cancel button |
| `requestInterceptor` | `Function` | | Function to intercept requests. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |
| `responseInterceptor` | `Function` | | Function to intercept responses. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |

### Modal Options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `buttonLabel` | `String` | | Label for the button |
| `buttonClassName` | `String` | Box Blue Button | CSS class to decorate the button |
| `modalClassName` | `String` | | CSS class to decorate the modal popup content |
| `overlayClassName` | `String` | | CSS class to decorate the modal popup overlay |

### Events

| Event Name | Event Data | Description |
| - | - | - |
| `choose` | `Array<File \| Web Link \| Folder>` | Will be fired when the Choose button is pressed. Event data will be an array of Folder Object or File Object or Web Link object depending upon whether it was a file selection or folder selection. |
| `cancel` | | Will be fired when the Cancel button is pressed |

## Keyboard Shortcuts

When the item grid has focus, either manually by clicking on it or
programmatically via javascript or via the above mentioned `autoFocus` prop, the
following keyboard shortcuts will work if their corresponding operations are
applicable and allowed.

| Key | Action |
| - | - |
| `Arrow Up` | Previous item row |
| `Arrow Down` | Next item row |
| `Ctrl/Cmd + Arrow Up` | First item row |
| `Ctrl/Cmd + Arrow Down` | Last item row |
| `/` | Search |
| `Shift + X` | Select an item row |
| `Enter` | Open the selected item |
| `g then f` | Navigates to the root folder |
| `g then u` | Upload to the current folder |
| `g then b` | Focuses the root folder breadcrumb |
| `g then s` | Shows the selected items |
| `g then x` | Cancel |
| `g then c` | Choose |
| `g then r` | Recent items |

## Scopes

If your application requires the end user to only be able to access a subset of
the Content Picker functionality, you can use <Link href="/guides/authentication/tokens/downscope">Downscoping</Link> to
appropriately downscope the Access Token to a resulting token that has the
desired set of permissions, and can thus, be securely passed to the end user
client initializing the Content Picker.

Below are a set of UI Element-specific scopes to go alongside Downscoping. These
allow developers to enable/disable UI controls on the Content Picker by
configuring the appropriate scopes on the downscoped token. To learn
more, see <Link href="/guides/api-calls/permissions-and-errors/scopes">Dedicated Scopes for Box UI Elements</Link>.

| Scope Name | Permissions granted |
| - | - |
| `base_picker` | Allows access to content in the folder tree based on user/file/token permissions |

### Feature Scopes

| Scope Name | Permissions granted |
| - | - |
| `item_share` | Allows sharing of resource specified under "resource" of the Token Exchange request. |
| `item_upload` | Allows upload in the content picker |

### Sample Scenarios

| Scenario | Scopes |
| - | - |
| User wants to only navigate a folder structure and pick a file / folder | `base_picker` |
| User wants to navigate a folder structure, pick a file / folder and also set access level | `base_picker` + `item_share` |
| User wants to navigate a folder structure, pick a file / folder and also upload a file / folder | `base_picker` + `item_upload` |
| User should be able to navigate a folder structure and pick a file / folder, upload a file / folder, and also set access level for a file/folder | `base_picker` + `item_share` + `item_upload` |

## Custom actions

You can expand the actions in the **More Options** menu for files and folders in Content Explorer and Content Picker. Your custom options show when a user clicks the ellipsis button.

To customize the **More Options** menu, pass an array of custom actions to `itemActions`.

```js theme={null}
contentExplorer.show(configData.FOLDER_ID, configData.ACCESS_TOKEN, {
    container: ".container",
    itemActions: customActions,
});
```

The array can include multiple actions. The action object should include the `label`, and the `onAction` callback function. You can filter the custom actions to appear only on a specific item `type`, by passing the `file` or `folder` value. The `filter` value is used for advanced filtering, for example by a specific file extension:

```js theme={null}
const customActions = [
    {
        label: "Preview in New Window",
        onAction: (item) => alert('action ' + item),
        type: 'file',
    },
    {
        label: "Open in Box.com",
        onAction: (item) => window.open("https://app.box.com"),
    },
    {
        label: "Export",
        onAction: (item) => console.log('action ' + item),
        filter: (item) => item.extension?.toLowerCase() === 'pdf',
    },
];
```

See the implemented examples in CodePen:

<iframe title="Box custom icons" />

<RelatedLinks title="RELATED GUIDES" />


# Content Preview
Source: https://developer.box.com/guides/embed/ui-elements/preview



<RelatedLinks title="REQUIRED GUIDES" />

The Box Content Preview UI Element allows developers to embed high
quality and interactive previews of Box files in their desktop or mobile web
application.

## Content Preview Element vs Content Preview Library

The Content Preview UI Element works differently from the other UI Elements, as the React component is a wrapper for the [Box Content Preview library][previewlib]. It also requires passing a language (defaults to `en-US`) since the preview library bundles are localized.

```js theme={null}
var ContentPreview = require("./ContentPreview").default;

<IntlProvider locale="en">
  <ContentPreview
    contentSidebarProps={{
      detailsSidebarProps: {
        hasAccessStats: true,
        hasClassification: true,
        hasNotices: true,
        hasProperties: true,
        hasRetentionPolicy: true,
        hasVersions: true,
      },
      features: FEATURES,
      hasActivityFeed: true,
      hasMetadata: true,
      hasSkills: true,
      hasVersions: true,
    }}
    hasHeader={true}
    features={FEATURES}
    fileId={FILE_ID}
    token={TOKEN}
    {...PROPS}
  />
</IntlProvider>;
```

The Content Preview Library fetches information
about the file and its converted representations
through the Box API, chooses the appropriate
viewer for the file type, dynamically loads
the necessary static assets and file representations,
and finally renders the file.

This UI Element also allows loading previews of
multiple files in the same container and exposes
arrows to navigate between those files.
It powers Preview in the main Box web application
as well as the <Link href="/reference/resources/file--full/#param-expiring_embed_link">expiring embed link object</Link>.

## Installation

<Link href="/guides/embed/ui-elements/installation">Learn how to install</Link> Box UI elements
either through NPM or the Box CDN.

## Authentication

UI Elements are designed in an authentication-agnostic way so
they will work for Managed Box Users and non-Box users (App Users). The
reason for this is that UI Elements only expect a <Link href="/guides/authentication/tokens/developer-tokens">token</Link> for authentication, and Box provides two different ways to generate tokens - OAuth and JWT.

<Card href={localizeLink("/guides/authentication")} title="Compare authentication methods" />

## Supported File Types

Box Content Preview supports 120+ file types, including most document and image
formats, HD video, 3D models, 360-degree images, and 360-degree videos. You can
find the full list of supported file types [here][filetypes].

<Warning>
  Note that where supported file types contain references to other
  objects, for example `DWG` files, those references are not supported in the
  Box preview. A notice will be displayed to all end users viewing a DWG file
  that contains unsupported references letting them know to take alternate steps
  to complete their workflow.
</Warning>

## Demo

Use the navigation arrows to preview different file types.

<iframe title="Box Content Preview Demo" />

## API

```js theme={null}
const { Preview } = Box;
const preview = new Preview();

/**
 * Shows a preview.
 *
 * @public
 * @param {string} fileId - File ID to preview
 * @param {string} accessToken - Box API access token
 * @param {Object} [options] - Options
 * @return {void}
 */
preview.show(fileId, accessToken, options);

/**
 * Hides the preview.
 *
 * @return {void}
 */
preview.hide();

/**
 * Prints the current file, if printable.
 *
 * @return {void}
 */
preview.print();

/**
 * Downloads the current file.
 *
 * @return {void}
 */
preview.download();

/**
 * Resizes the current preview, if applicable. This function only needs to
 * be called when preview's viewport has changed while the window has not.
 * If the window is resizing, then preview will automatically resize itself.
 *
 * @return {void}
 */
preview.resize();

/**
 * Adds an event listener to the preview. Listeners should be added
 * before calling show() so no events are missed.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
preview.addListener();

/**
 * Removes an event listener from the preview.
 *
 * @param {string} eventName - Name of the event
 * @param {Function} listener - Callback function
 * @return {void}
 */
preview.removeListener(eventName, listener);

/**
 * Removes all event listeners from the preview.
 *
 * @return {void}
 */
preview.removeAllListeners();
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `fileId` | String | Box File ID. |
| `accessToken` | String | Box API access token to use. This should have read/write access to the folder above. The value passed in for the token is assumed to never expire while the explorer is visible. |
| `options` | Object | Optional options. See below for details. For example: `contentExplorer.show(FOLDER_ID, TOKEN, {canDelete: false})` would be used to hide the delete option. |

### Options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `container` | String | `document.body` | CSS selector of the container in which Preview should be placed |
| `sharedLink` | String | | Shared link URL, required if file is shared and the access token doesn't belong to an owner or collaborator of the file |
| `sharedLinkPassword` | String | | Shared link password, required if shared link has a password |
| `collection` | Array | | List of file IDs to preview over. When used, this will show previews of multiple files within the same container and expose arrows to navigate between those files. Note that `FILE_ID` needs to be included in this list and that the SDK doesn't support collections with files that require a shared link or password. |
| `header` | String | `light` | Values that control header visibility and background color. Use `none` for no header, `light` for a light header and background, and `dark` for a dark header and background |
| `logoUrl` | String | | URL of custom logo to show in header. If this value is the string box then the box logo will show |
| `showAnnotations` | Boolean | `false` | Whether annotation button in header and annotations on content are shown |
| `showDownload` | Boolean | `false` | Whether download button is shown in header. Will also control print button visibility in viewers that support print. Note that this option will not override download permissions on the access token. |

## Token Generator Function

The Preview library optionally takes a token generator function instead of a
string token. Using a token generator function allows you to dynamically
determine what tokens Preview should use. For example, you can pass in different
access tokens for each file or make sure your token is refreshed and valid
before showing a preview. The token generator function should return a promise
that resolves in either a single string token that applies to all of the files
being previewed or a map of typed file IDs to access token for those files.

```js theme={null}
// Example token generator function that resolves to a single access token
var singleTokenGenerator = function () {
  return someApi.getToken().then(function (data) {
    return data.token;
  });
};

// Example token generator function that resolves to a map of tokens
var mapTokenGenerator = function () {
  return Promise.resolve({
    file_1234: "some_token_abcd",
    file_2345: "some_token_bcde",
  });
};
```

## Events

The preview object exposes `addListener` and `removeListener` for binding to
events. Event listeners should be bound before `show()` is called, otherwise
events can be missed.

```js theme={null}
const listener = (value) => {
    // Do something with value
};

// Attach listener before calling show otherwise events can be missed
var preview = new Box.Preview();
preview.addListener(EVENTNAME, listener);

// Show a preview
preview.show(...);

// Remove listener when needed
preview.removeListener(EVENTNAME, listener);
```

`EVENTNAME` can be one of the following:

* `viewer` event will be triggered when we have the viewer instance first available. This will be the same object that is also a property included in the `load` event. Preview triggers this event before `load` so that clients can attach their listeners before the `load` event is triggered.

* `load` event will be triggered on every preview load when `show()` is called or if inter-preview navigation occurs. The event data will contain:

  ```js theme={null}
  error: 'message', // Error message if any error occurred while loading
  viewer: {...},    // Instance of the current viewer object if no error occurred
  metrics: {...},   // Performance metrics
  file: {...}       // Box file object with properties defined in file.js
  ```

* `navigate` event will be triggered when navigation happens. The event includes the file ID of the file being navigated to, and this event will trigger before `load`.

* `notification` event will be triggered when either the preview wrapper or one of the viewers wants to notify something like a warning or non-fatal error. The event data will contain:

  ```js theme={null}
  message: 'message', // Message to show
  type: 'warning'    // 'warning', 'notice', or 'error'
  ```

* `viewerevent` Each viewer will trigger its own sets of events. For example, the Image viewer will trigger `rotate` or `resize`, etc. while other viewers may trigger another set of events. The preview wrapper will also re-emit events at the preview level, with event data containing:

  ```js theme={null}
  event: EVENTNAME,         // Event name
  data: DATA,               // Event data object
  viewerName: VIEWERNAME,   // Name of the viewer. See VIEWERNAME above
  fileId: fileId            // The file ID
  ```

### Example event usage

```js theme={null}
var preview = new Box.Preview();
preview.addListener("viewer", (viewer) => {
  viewer.addListener("rotate", () => {
    // Do something when a viewer rotates a preview
  });
});

preview.addListener("load", (data) => {
  const viewer = data.viewer;
  viewer.addListener("rotate", () => {
    // Do something when a viewer rotates a preview
  });
});

preview.addListener("viewerevent", (data) => {
  if (data.viewerName === "Image") {
    if (data.event === "rotate") {
      // Do something when an image preview is rotated
    }
  } else if (data.viewerName === "Image360") {
    if (data.event === "rotate") {
      // Do something different when a 360-degree image is rotated
    }
  } else {
  }
});

preview.addListener("rotate", (data) => {
  if (data.viewerName === "Image") {
    // Do something when an image preview is rotated
  } else if (data.viewerName === "Image360") {
    // Do something different when a 360-degree image is rotated
  } else {
  }
});
```

## Annotations

You can enable V4 <Link href="/guides/embed/ui-elements/annotations">annotations</Link> in content preview. New
annotations will sync in real time.

To add V4 annotations to preview:

1. Run `npm i box-annotations@latest` to install [box annotations][annotations].

<Warning>
  Box annotations version should be at least major version 4 and up.
</Warning>

2. Run `npm i box-ui-elements@16.0.0` to install [BUIE][buie] version with annotation related change.

<Warning>
  Box UI elements should be the lowest working version that contains
  fully working V4 annotations.
</Warning>

3. Import content preview and box annotations into your application:

   ```js theme={null}
   import boxAnnotations from "https://cdn.skypack.dev/box-annotations@latest";

   var file_id = "YOUR FILE ID";
   var accessToken = "YOUR ACCESS TOKEN";

   /* Enable annotations in sidebar */
   var contentSidebarProps = {
     hasActivityFeed: true,
     features: {
       activityFeed: {
         annotations: {
           enabled: true,
         },
       },
     },
   };

   var options = {
     container: ".previewer",
     contentSidebarProps: contentSidebarProps,

     /* Enable annotations in preview */
     enableAnnotationsDiscoverability: true,
     enableAnnotationsImageDiscoverability: true,
     showAnnotations: true,
     showAnnotationsControls: true,
     showAnnotationsDrawingCreate: true,
   };

   /* BoxAnnotations */
   var annotations = new BoxAnnotations();

   /* Box Preview */
   var contentPreviewer = new Box.ContentPreview();

   /* Set annotation into previewer */
   options["boxAnnotations"] = annotations;

   /* Show previewer */
   contentPreviewer.show(file_id, accessToken, options);
   ```

<Warning>
  The property `features: { activityFeed: { annotations: { enabled: true  } } } }
    ` is subject to change in the future.
</Warning>

```html theme={null}
<link href="https://cdn01.boxcdn.net/platform/elements/16.0.0/en-US/preview.css" rel="stylesheet" type="text/css"></link>
<script src="https://cdn01.boxcdn.net/platform/elements/16.0.0/en-US/preview.js"></script>

<style>
  .previewer {
    border: 1px solid #eee;
    height: 500px;
    width: 100%;
  }
</style>

<div class="previewer"></div>

<script type="module" src="./script.js"></script>
```

## Box AI for UI Elements

Box AI for UI Elements enhances the Content Preview UI Element
with additional features, allowing the developers
to add the Box Q\&A AI functionality to their platform app.
Enriched with Box AI features, the Preview UI element brings the following functionality:

* Q\&A and document summaries.
* A **clear conversation** button that resets the conversation with Box AI.
* Citations that appear below the answer if included in the answer.
* Formatting support that allows requesting Markdown-formatted response, including bullet points or tables.
* Question history that allows referencing previous context to achieve the best response possible. The question history is kept only during the current session.
* Suggested questions that appear at the top of the chat by default to assist with the conversation.

<Frame>
  <img alt="Box UI Element with Box AI options enabled" />
</Frame>

### Enable Box AI for UI Elements

To enable the Box AI modal in content preview header, follow these steps:

1. Make sure your Node and React versions are `18.x` or higher.
2. Download the [npm package that contains Box AI for UI Elements][aipackage] or directly from <Link href="/guides/embed/ui-elements/installation">Box CDN</Link>.
3. Install the peer dependencies:

   * [`box-ai-content-answers`][box-ai-content-answers]
   * [`blueprint-web`][blueprint-web]
   * [`blueprint-web-assets`][blueprint-web-assets]

   To do so, run the following command:

   ```sh theme={null}
   npx install-peerdeps box-ui-elements@^22.0.0
   ```

### Using JavaScript

To enable Box AI features, pass the following:

* `hasHeader` prop set to `true`,
* `contentAnswersProps` prop. The fields `show`, `isCitationsEnabled`, `isMarkdownEnabled`, `isResetChatEnabled` and `suggestedQuestions` are included by default.

```js theme={null}
const preview = new Box.Preview();
const suggestedQuestions = [
 {
   label: 'What are the key takeaways?',
   prompt: 'What are the key takeaways?',
   id: '1234',
 },
 {
   label: 'Summarize this document',
   prompt: 'Summarize this document',
   id: '5678',
 },
];

preview.show(<FILE_ID>, <TOKEN>, {
    container: '.preview-container',
    contentAnswersProps={
      show: true,
      isCitationsEnabled: true,
      isMarkdownEnabled: true,
      isResetChatEnabled: true,
      suggestedQuestions
    }
    hasHeader: true,
});
```

### Using React component

You can also add Box AI element to a header in a React component.
To do so, add:

* `hasHeader` prop set to `true`,
* `contentAnswersProps` prop. The fields `show`, `isCitationsEnabled`, `isMarkdownEnabled`, `isResetChatEnabled` and `suggestedQuestions` are included by default.

<Note>
  To localize the `suggestedQuestions` properly, make sure that the prompts are translated. The optional `label` property is for screen readers, while the `prompt` property is the text displayed to the user in the AI modal.
</Note>

```js theme={null}
import ContentPreview from 'box-ui-elements/es/elements/content-preview';
import { IntlProvider } from "react-intl";

const suggestedQuestions = [
  {
    label: 'Key takeaways',
    prompt: 'What are the key takeaways from this document?',
    id: '1234',
  },
  {
    label: 'Summarize',
    prompt: 'Summarize this document',
    id: '5678',
  },
];

export default () => {
    // Storing variables in the front end is not secure.
    // You will want to grab this value from a database for production
    const TOKEN = process.env.REACT_APP_BOX_DEVELOPER_TOKEN
    const FILE_ID = process.env.REACT_APP_BOX_PREVIEW_FILE_ID
    return (
      <IntlProvider locale="en">
         <ContentPreview 
            contentAnswersProps={{
              show: true,
              isCitationsEnabled: true,
              isMarkdownEnabled: true,
              isResetChatEnabled: true,
              suggestedQuestions
            }}
            fileId={FILE_ID}
            token={TOKEN}
            hasHeader=true
         />
      </IntlProvider>
  );
};
```

You can further customize your apps using the following event listeners for Content Preview available with this release: `onAsk`, `onClearConversations`, and `onRequestClose`.

## Scopes

If your application requires the end user to only be able to access a subset of
the Content Preview functionality, you can use <Link href="/guides/authentication/tokens/downscope">Downscoping</Link> to
appropriately downscope the Access Token to a resulting token that has the
desired set of permissions, and can thus, be securely passed to the end user
client initializing the Content Preview.

Below is a set of UI Element-specific scopes to go alongside Downscoping. These
allow developers to enable/disable UI controls on the Content Preview by
configuring the appropriate scopes on the downscoped token. To learn
more, see <Link href="/guides/api-calls/permissions-and-errors/scopes">Dedicated Scopes for Box UI Elements</Link>.

### Base Scope

| Scope Name | Permissions granted |
| - | - |
| `base_preview` | Allows the user to preview the file, nothing else |

### Feature Scopes

| Scope Name | Permissions granted |
| - | - |
| `item_download` | Allows downloading/printing the content from the generated preview |
| `annotation_edit` | Allows users to edit annotations (delete). Note: For highlight annotations to work, the text layer on the document needs to be enabled for the user. Text layer is disabled for all users that don't have download permissions on the file. To enable highlight annotations for a user, please ensure they have download permissions on the file. |
| `annotation_view_all` | Allows users to view all users' annotations. |
| `annotation_view_self` | Allows users to view their own annotations only. |

<Info>
  **Enable highlight annotations with scopes** The highlight scope is not included
  with `annotation_edit` and `annotation_view_all` scopes. The downscoped access
  token will need to include the `item_download` scope to enable highlighting.
</Info>

### Sample Scenarios

| Scenario | Scopes |
| - | - |
| User should only be able to preview (not download/print, annotate) | `base_preview` |
| User should be able to preview, download and print | `base_preview` + `item_download` |
| User should be able to preview and view all annotations (not download, print or create annotations) | `base_preview` + `annotation_view_all` |
| User should be able to preview, and create annotations but only view their own. | `base_preview` + `annotation_view_self` + `annotation_edit` |
| User should be able to preview, edit annotations and view all annotations | `base_preview` + `annotation_view_all` + `annotation_edit` |
| User should be able to preview and only view their own annotations but not add/delete (ex: after review period has expired, all documents need to be stored in read only mode) | `base_preview` + `annotation_view_self` |

[filetypes]: https://support.box.com/hc/en-us/articles/360043695794-Viewing-Different-File-Types-Supported-in-Box-Content-Preview

[annotations]: https://github.com/box/box-annotations

[buie]: https://github.com/box/box-ui-elements/releases/tag/v16.0.0

[previewlib]: https://github.com/box/box-content-preview

[aipackage]: https://www.npmjs.com/package/box-ui-elements/v/22.0.0

[blueprint-web]: https://www.npmjs.com/package/@box/blueprint-web

[box-ai-content-answers]: https://www.npmjs.com/package/@box/box-ai-content-answers

[blueprint-web-assets]: https://www.npmjs.com/package/@box/blueprint-web-assets

<RelatedLinks title="RELATED GUIDES" />


# Dedicated Scopes
Source: https://developer.box.com/guides/embed/ui-elements/scopes



<RelatedLinks title="REQUIRED GUIDES" />

When working with Box UI Elements many developers have shown interest in being
able to implement their own permission model, different from [Access
Levels][acl] defined by Box.

<Link href="/guides/authentication/tokens/downscope">Downscoping</Link>, also known as Token Exchange, is our mechanism by
which developers can restrict the permissions on the Access Token to a more
granular level, allowing them to build out their own permissions model on Box
Platform.

## Scopes & UI Elements

To facilitate this process we've created a new set of API scopes that allow
developers to control which UI controls are available to end
users in applications leveraging UI Element.

The Box UI Element has been designed to respect the permission enforced via
these scopes, so UI controls are turned on or off automatically depending on
whether or not the token allows the corresponding functionality.

Another advantage of these new scopes is that since the tokens are scoped to the
precise set of operations that the application wants the end user to have access
to, a savvy end user won't have any more access directly through the API using
the token. This allows you to make your application more secure.

## Scope principles

The new scopes have been designed keeping the following fundamentals in mind:

* **All scopes should be modular and strictly additive:** So a developer can combine multiple scopes in a token exchange request to generate a token with the desired set of functionality. Also to avoid confusion, two scopes should never have the same permission.
* **Scopes should directly map to a specific action in the UI Element:** So adding this scope to the token enables the specific action. Since some actions can only be performed by specific UI Elements, some scopes may only be meaningfully applicable to those UI Elements.
* **Scope should contain the minimum set of permissions required to perform the corresponding action:** So even if some end-user of your application uses the token directly against the API, they can't gain access beyond what you intended them to provide through the UI Element.
* **Every UI Element should have a "base scope" that encapsulates all required permissions for the UI Element to functionally work:** Any fewer permissions on the token and the basic set of operations on the UI Element won't work. This scope should always be included in the Token Exchange request.

With that said, for every UI Element, we are adding two types of scopes:

### Base Scope

Every UI Element has a "base scope", which provides the least
set of permissions that are necessary for the UI Element to functionally work.
For this reason, this "base scope" must always be present in the token exchange
request. Since the base set of permissions for every UI Element to functionally
work may not be the same (Content Uploader UI Element doesn't require preview
permissions, for example), UI Elements may have their own respective base
scopes.

### Feature Scopes

In addition to the base scope, we also introduced
feature-level scopes. Upon pairing with base scopes, feature scopes enable
additional capabilities within your UI Element, and provide the user with
permissions to perform the actions prescribed by the feature scope(s) added to
their down-scoped token. As with base scopes, feature scopes too are mostly
different for every UI Element. Since feature scopes are strictly additive, you
can assume (unless noted otherwise in the documentation) that providing a user
with access to a scope only gives them permission to perform the corresponding
action and nothing else.

Now that you understand what Base Scopes and Feature Scopes are, refer to the
documentation for each of the UI Elements to learn more about their dedicated
scopes.

[acl]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels

<RelatedLinks title="RELATED GUIDES" />


# Content Sidebar
Source: https://developer.box.com/guides/embed/ui-elements/sidebar



<RelatedLinks title="REQUIRED GUIDES" />

The Box Content Sidebar UI Element allows developers to add support for viewing
file related metadata and Activity Feed (incl. versions,
comments and tasks) in their desktop or mobile web application.

## Installation

<Link href="/guides/embed/ui-elements/installation">Learn how to install</Link> Box UI elements
either through NPM or the Box CDN.

## Authentication

The UI Elements are designed in an authentication agnostic way so whether
you are using UI Elements for users who have Box accounts (Managed Users) or
non-Box accounts (App Users), UI Elements should work out of the box. The
reason for this is that UI Elements only expect a "token" to be passed in for
authentication, and Box provides two different ways to generate tokens - OAuth
and JWT.

<Card href={localizeLink("/guides/authentication")} title="Compare authentication methods" />

## Sample HTML

```html theme={null}
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>Box Content Sidebar</title>

    <!-- Latest version of the sidebar css for your locale -->
    <link
      rel="stylesheet"
      href="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/sidebar.css"
    />
  </head>
  <body>
    <div class="container" style="height:600px"></div>
    <!-- Latest version of the sidebar js for your locale -->
    <script src="https://cdn01.boxcdn.net/platform/elements/{VERSION}/en-US/sidebar.js"></script>
    <script>
      var fileId = "123";
      var accessToken = "abc";

      // At least one of the sub-sidebars (details, activity feed, skills, metadata) need to be turned on for something to render. Details is itself further divided into notices, properties, access stats and versions, one of which need to be enabled for the details sidebar to render.
      var sidebar = new Box.ContentSidebar();
      sidebar.show(fileId, accessToken, {
        container: ".container",
        detailsSidebarProps: {
          hasNotices: true,
          hasProperties: true,
          hasAccessStats: true,
          hasVersions: true
        },
        hasActivityFeed: true,
        hasSkills: true,
        hasMetadata: true
      });
    </script>
  </body>
</html>
```

## Demo

### Stand-alone Sidebar

<iframe title="Box Content Sidebar" />

### Sidebar with Content Preview

<iframe title="Box Content Preview with Sidebar" />

### Sidebar with Content Explorer

<iframe title="Box Content Explorer with Sidebar" />

## API

```js theme={null}
const { ContentSidebar } = Box;
const sidebar = new ContentSidebar();

/**
 * Shows the file selection.
 *
 * @public
 * @param {String} fileId - The file id.
 * @param {String} token - The API access token.
 * @param {Object|void} [options] - Optional options.
 * @return {void}
 */
sidebar.show(fileId, token, options);

/**
 * Hides the sidebar, removes all event listeners, and clears out the HTML.
 *
 * @public
 * @return {void}
 */
sidebar.hide();

/**
 * Clears out the internal in-memory cache for the sidebar. This forces
 * items to be reloaded from the API.
 *
 * @public
 * @return {void}
 */
sidebar.clearCache();

/**
 * Adds an event listener to the sidebar. Listeners should be added before
 * calling show() so no events are missed.
 *
 * @public
 * @param {String} eventName - Name of the event.
 * @param {Function} listener - Callback function.
 * @return {void}
 */
sidebar.addListener(eventName, listener);

/**
 * Removes an event listener from the sidebar.
 *
 * @public
 * @param {String} eventName - Name of the event.
 * @param {Function} listener - Callback function.
 * @return {void}
 */
sidebar.removeListener(eventName, listener);

/**
 * Removes all event listeners from the sidebar.
 *
 * @public
 * @return {void}
 */
sidebar.removeAllListeners();
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `fileId` | String | Box File ID. This will be the ID of the file for which you want the sidebar. |
| `token` | String | Box API access token to use. It can have read/write access to the file above. The value passed in for the token is assumed to never expire while the sidebar is visible. |
| `options` | Object | Additional options. For example, `sidebar.show(FILE_ID, TOKEN, {hasProperties: true})` would be used to show file properties in the sidebar. |

### Options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `container` | String | `document.body` | CSS selector of the container in which the content sidebar should be placed. Calling `hide()` will clear out this container. |
| `hasActivityFeed` | Boolean | `false` | Set to true to show the activity feed that includes versions, comments and tasks. |
| `hasMetadata` | Boolean | `false` | Set to true to show box metadata for the file. |
| `hasSkills` | Boolean | `false` | Set to true to show the file skills data. |
| `detailsSidebarProps` | Object | `{}` | See section below. |
| `requestInterceptor` | Function | | Function to intercept requests. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |
| `responseInterceptor` | Function | | Function to intercept responses. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |

### `detailsSidebarProps`

| Parameter | Type | Default | Description |
| - | - | - | - |
| `hasProperties` | Boolean | `false` | Set to true to show file properties in the details sidebar. |
| `hasAccessStats` | Boolean | `false` | Set to true to show file access stats in the details sidebar. |
| `hasVersions` | Boolean | `false` | Set to true to show file versions in the details sidebar. |
| `hasNotices` | Boolean | `false` | Set to true to show file related notices in the details sidebar. |

## Scopes

If your application requires the end user to only be able to access a subset of
the Content Sidebar's functionality, you can use <Link href="/guides/authentication/tokens/downscope">Downscoping</Link> to
appropriately downscope the Access Token to a resulting token that has the
desired set of permissions, and can thus, be securely passed to the end user
client initializing the Content Sidebar.

Below are a set of UI Element-specific scopes to go alongside Downscoping. These
allow developers to enable/disable UI controls on the Content Sidebar by
configuring the appropriate scopes on the downscoped token. To learn
more, see <Link href="/guides/api-calls/permissions-and-errors/scopes">Dedicated Scopes for Box UI Elements</Link>.

### Base Scope

| Scope Name | Permissions granted |
| - | - |
| `base_sidebar` | Allows the user to get basic file info needed for the sidebar. |

### Feature Scopes

| Scope Name | Permissions granted |
| - | - |
| `item_comment` | Allows adding and editing comments. |
| `item_rename` | Allows editing of file description. |
| `item_upload` | Allows editing of file metadata. |
| `item_task` | Allows creating and resolving of tasks. |

<RelatedLinks title="RELATED GUIDES" />


# Theming & styling for Box UI Elements
Source: https://developer.box.com/guides/embed/ui-elements/theming-styling



<RelatedLinks title="REQUIRED GUIDES" />

With theming & styling for Box UI Elements you can customize the look
of the embedded Box component to your enterprise's requirements.

<Note>
  As of now, [theming & styling][blog] is available for Content
  Explorer and Content Uploader.
</Note>

## How to start

Add the selected Box component to your application. The default Box theme is applied.

## Customization

Box uses <Link href="/guides/embed/ui-elements/ui-elements-design-tokens">design tokens</Link> for the customization purposes.

<Note>
  Design tokens are named entities that store specific visual attributes, such
  as colors, spacing, typography, scale, and many more.
  They are used instead of hard-coded values to simplify sharing design
  properties across platforms, tools, and components.
</Note>

You can change the following elements in your embedded Box component.

### Colors

Customize:

* global color palette - select the primary, secondary, and accent colors
* state colors - select color for states such as hover, focus, active, disabled
* component-specific colors - for example, you can select different colors for your buttons depending on their type

- gradients - choose and adjust a gradient as your background or other components
- opacity - adjust the opacity of the overlay effects for Box Modals and side panels

### Typography

Customize:

* text decoration - underline, strikethrough, letter spacing
* line heights and paragraph spacing

### Border, radius

Choose:

* border styling - width, styles, and colors
* border radius

### Spacing

Choose:

* global spacing
* component-specific spacing
* component-specific alignment and distribution, for example justify-content

### Shadows and elevation

Define:

* shadow presets
* custom shadows

### Interactive states

Customize:

* hover, active, focus, disabled, and error states - visual effect such as changed background color
* transitions and animations

### Component-level overrides

Customize text input, drop down, and checkboxes with individual color

### Icons

Style interactive icons such as buttons or drop downs.

<Note>
  To replace non-interactive icons such as file or folder icons with your custom ones, use inline SVGs in CSS.
  To change non-interactive icons color, height, and width, use CSS.
</Note>

See the implemented examples of custom icons in CodePen:

<iframe title="Box custom icons" />

### Miscellaneous

Style:

* help text and labels
* tool tips

## Demo

<iframe title="Box theming branding" />

[explorer]: /guides/embed/ui-elements/explorer

[uploader]: /guides/embed/ui-elements/uploader

[blog]: https://medium.com/@stefaniuk.olga/b4a86518d5ca

<RelatedLinks title="RELATED GUIDES" />


# UI Elements design tokens
Source: https://developer.box.com/guides/embed/ui-elements/ui-elements-design-tokens



<RelatedLinks title="REQUIRED GUIDES" />

This table shows all the design tokens you can use for <Link href="/guides/embed/ui-elements/theming-styling">theming and styling</Link> purposes. Provided default values and descriptions give clarity and guidance for implementation.

## Token structure

There are two ways to provide tokens to the theme object in Content Explorer:
flatten structure using full token names and nested structure using shortened
names.
The latter allows you to group tokens, which might improve the readability of your customization, but both produce the same results.

### Example

Flatten structure:

```js theme={null}
const theme = {
    tokens: {
        "body-default-font-size": "14px",
        "body-default-font-weight": "400"
        "body-default-text-decoration": "none",
        "body-default-bold-line-height": "20px",
    }
};
```

Nested structure:

```js theme={null}
const theme = {
    tokens: {
        Body: {
            Default: {
                "font-size": "14px",
                "font-weight": "400",
                "text-decoration": "none",
            }
            "Default Bold": {
                "line-height": "20px",
            }
        }
    }
};
```

## Border colors

<Note>
  You can pass any CSS color value, like hexadecimal colors, RGB, cross-browser color names, and so on.
</Note>

| Token | Default value | Description |
| - | - | - |
| `border-checkbox-border` | `#6f6f6f` | Default border color for checkboxes. |
| `border-checkbox-border-hover` | `#4e4e4e` | Border color when hovering over checkboxes. |
| `border-checkbox-border-selected` | `#0061d5` | Border color for selected checkboxes. |
| `border-checkbox-border-selected-hover` | `#2079e3` | Border color when hovering over selected checkboxes. |
| `border-cta-border-outline` | `#000000` | Border for secondary buttons with transparent background. |
| `border-cta-border-outline-disabled` | `#646464` | Border for disabled outline buttons. |
| `border-cta-border-outline-hover` | `#000000` | Border for outline buttons on hover. |
| `border-cta-border-outline-pressed` | `#000000` | Border for outline buttons when pressed. |
| `border-cta-border-secondary` | `#bcbcbc` | Border for secondary buttons. |
| `border-cta-border-secondary-disabled` | `#e8e8e8` | Border for disabled secondary buttons. |
| `border-cta-border-secondary-hover` | `#bcbcbc` | Border for secondary buttons on hover. |
| `border-cta-border-secondary-pressed` | `#bcbcbc` | Border for secondary buttons when pressed. |
| `border-divider-border` | `#e8e8e8` | Horizontal line separators. |
| `border-dropdown-border` | `#bcbcbc` | Border for dropdown menus. |
| `border-gridthumbnail-border` | `#e8e8e8` | Border for item (file/folder) thumbnails in grid view. |
| `border-input-border` | `#909090` | Border for text inputs. |
| `border-input-border-error` | `#ed3757` | Border for text inputs with errors. |
| `border-input-border-focus` | `#2486fc` | Border for focused text inputs. |
| `border-input-border-hover` | `#6f6f6f` | Border for text inputs on hover. |
| `border-search-border` | `#f4f4f4` | Border for search inputs. |
| `border-search-border-hover` | `#6f6f6f` | Border for search inputs on hover. |
| `border-switch-border` | `#bcbcbc` | Border for toggle switches. |
| `border-switch-border-hover` | `#bcbcbc` | Border for toggle switches on hover. |
| `border-tooltip-border-error` | `#f69bab` | Border for error tool tips. |

## Icon colors

<Note>
  You can only style interactive icons such as buttons or drop down.
</Note>

| Token | Default value | Description |
| - | - | - |
| `icon-cta-icon` | `#6f6f6f` | Default color for icons in buttons. |
| `icon-cta-icon-hover` | `#222222` | Color for icons in buttons on hover. |
| `icon-cta-icon-pressed` | `#222222` | Color for icons in buttons when pressed. |

## Outline colors

| Token | Default value | Description |
| - | - | - |
| `outline-focus-on-dark` | `#ffffff` | Focus outline color on dark backgrounds. |
| `outline-focus-on-light` | `#2486fc` | Focus outline color on light backgrounds. |

## Surface colors

| Token | Default value | Description |
| - | - | - |
| `surface-checkbox-surface` | `#ffffff` | Background color for checkboxes. |
| `surface-checkbox-surface-hover` | `#ffffff` | Background color for checkboxes on hover. |
| `surface-checkbox-surface-selected` | `#0061d5` | Background color for selected checkboxes. |
| `surface-checkbox-surface-selected-hover` | `#2079e3` | Background color for selected checkboxes on hover. |
| `surface-cta-surface-icon` | `rgba(0, 0, 0, 0)` | Background for icon buttons. |
| `surface-cta-surface-icon-disabled` | `rgba(0, 0, 0, 0)` | Background for disabled icon buttons. |
| `surface-cta-surface-icon-hover` | `rgba(0, 0, 0, 0.04)` | Background for icon buttons on hover. |
| `surface-cta-surface-icon-pressed` | `rgba(0, 0, 0, 0.08)` | Background for icon buttons when pressed. |
| `surface-cta-surface-outline` | `rgba(0, 0, 0, 0)` | Background for secondary buttons with transparent background. |
| `surface-cta-surface-outline-hover` | `rgba(0, 0, 0, 0.04)` | Background for outline buttons on hover. |
| `surface-cta-surface-outline-pressed` | `rgba(0, 0, 0, 0.08)` | Background for outline buttons when pressed. |
| `surface-cta-surface-secondary` | `#ffffff` | Background for secondary buttons. |
| `surface-cta-surface-secondary-hover` | `#f4f4f4` | Background for secondary buttons on hover. |
| `surface-cta-surface-secondary-pressed` | `#e8e8e8` | Background for secondary buttons when pressed. |
| `surface-cta-surface-tertiary` | `#ffffff` | Background for link styled buttons. |
| `surface-cta-surface-tertiary-hover` | `#f4f4f4` | Background for link styled buttons on hover. |
| `surface-cta-surface-tertiary-pressed` | `#e8e8e8` | Background for link styled buttons when pressed. |
| `surface-dropdown-surface` | `#ffffff` | Background for dropdown menus. |
| `surface-dropdown-surface-error` | `#ffffff` | Background for dropdown menus with errors. |
| `surface-dropdown-surface-focus` | `#ffffff` | Background for focused dropdown menus. |
| `surface-dropdown-surface-hover` | `#ffffff` | Background for dropdown menus on hover. |
| `surface-illustration-surface-box-neutral` | `#0061d5` | Color for illustrations (detailed icons). |
| `surface-input-surface` | `#ffffff` | Background for text inputs. |
| `surface-input-surface-error` | `#ffffff` | Background for text inputs with errors. |
| `surface-input-surface-focus` | `#ffffff` | Background for focused text inputs. |
| `surface-input-surface-hover` | `#ffffff` | Background for text inputs on hover. |
| `surface-menu-surface` | `#ffffff` | Background for dropdown menu options. |
| `surface-menu-surface-focus` | `#f4f4f4` | Background for focused menu items. |
| `surface-menu-surface-hover` | `#f4f4f4` | Background for menu items on hover. |
| `surface-search-surface` | `#f4f4f4` | Background for search inputs. |
| `surface-search-surface-focused` | `#ffffff` | Background for focused search inputs. |
| `surface-search-surface-hover` | `#fbfbfb` | Background for search inputs on hover. |
| `surface-sliderthumb-surface` | `#0061d5` | Color for range slider thumbs. |
| `surface-sliderthumb-surface-hover` | `#2486fc` | Color for range slider thumbs on hover. |
| `slidertrack-surface` | `#6f6f6f` | Color for range slider tracks. |
| `surface-surface` | `#ffffff` | General background color. |
| `surface-surface-brand` | `#0061d5` | Background for primary buttons. |
| `surface-surface-brand-disabled` | `#0061d5` | Background for disabled primary buttons. |
| `surface-surface-brand-hover` | `#006ae9` | Background for primary buttons on hover. |
| `surface-surface-brand-pressed` | `#004eac` | Background for primary buttons when pressed. |
| `surface-switch-surface` | `#ffffff` | Background for toggle switches. |
| `surface-switch-surface-off` | `#d3d3d3` | Background for toggle switches in off state. |
| `surface-switch-surface-on` | `#0061d5` | Background for toggle switches in on state. |
| `surface-tooltip-surface` | `#4e4e4e` | Background for tool tips. |
| `surface-tooltip-surface-error` | `#fdebee` | Background for error tool tips. |

## Text colors

| Token | Default value | Description |
| - | - | - |
| `text-cta-link` | `#0061d5` | Color for hyperlinks. |
| `text-cta-link-disabled` | `#b2cff2` | Color for disabled hyperlinks. |
| `text-cta-link-hover` | `#1d6bca` | Color for hyperlinks on hover. |
| `text-cta-link-pressed` | `#2486fc` | Color for hyperlinks when pressed. |
| `text-text-error-on-light` | `#d5324e` | Error text color on light backgrounds. |
| `text-text-on-dark` | `#ffffff` | Text color on dark backgrounds. |
| `text-text-on-light` | `#222222` | Primary text color on light backgrounds. |
| `text-text-on-light-secondary` | `#6f6f6f` | Secondary text color on light backgrounds. |
| `text-text-on-light-secondary-hover` | `#4e4e4e` | Secondary text color on hover. |

## Typography tokens

<Note>
  The comment in the table refers to pixels in calculation based on a root font-size of 16 px.
</Note>

| Token | Default value | Description |
| - | - | - |
| `body-default-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for body text. |
| `body-default-font-size` | `0.875rem` | Font size for body text. |
| `body-default-font-weight` | `400` | Font weight for body text. |
| `body-default-letter-spacing` | `0.01875rem` | Letter spacing for body text. |
| `body-default-line-height` | `1.25rem` | Line height for body text. |
| `body-default-text-decoration` | `none` | Text decoration for body text. |
| `body-default-bold-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for bold body text. |
| `body-default-bold-font-size` | `0.875rem` | Font size for bold body text. |
| `body-default-bold-font-weight` | `700` | Font weight for bold body text. |
| `body-default-bold-letter-spacing` | `0.01875rem` | Letter spacing for bold body text. |
| `body-default-bold-line-height` | `1.25rem` | Line height for bold body text. |
| `body-default-bold-text-decoration` | `none` | Text decoration for bold body text. |
| `body-default-semibold-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for semi-bold body text. |
| `body-default-semibold-font-size` | `0.875rem` | Font size for semi-bold body text. |
| `body-default-semibold-font-weight` | `600` | Font weight for semi-bold body text. |
| `body-default-semibold-letter-spacing` | `0.01875rem` | Letter spacing for semi-bold body text. |
| `body-default-semibold-line-height` | `1.25rem` | Line height for semi-bold body text. |
| `body-default-semibold-text-decoration` | `none` | Text decoration for semi-bold body text. |
| `body-large-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for large body text. |
| `body-large-font-size` | `1rem` | Font size for large body text. |
| `body-large-font-weight` | `400` | Font weight for large body text. |
| `body-large-letter-spacing` | `0.01875rem` | Letter spacing for large body text. |
| `body-large-line-height` | `1.5rem` | Line height for large body text. |
| `body-large-text-decoration` | `none` | Text decoration for large body text. |
| `body-large-bold-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for large bold body text. |
| `body-large-bold-font-size` | `1rem` | Font size for large bold body text. |
| `body-large-bold-font-weight` | `700` | Font weight for large bold body text. |
| `body-large-bold-letter-spacing` | `0.01875rem` | Letter spacing for large bold body text. |
| `body-large-bold-line-height` | `1.5rem` | Line height for large bold body text. |
| `body-large-bold-text-decoration` | `none` | Text decoration for large bold body text. |
| `caption-bold-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for bold captions. |
| `caption-bold-font-size` | `0.75rem` | Font size for bold captions. |
| `caption-bold-font-weight` | `700` | Font weight for bold captions. |
| `caption-bold-letter-spacing` | `0.01875rem` | Letter spacing for bold captions. |
| `caption-bold-line-height` | `0.875rem` | Line height for bold captions. |
| `caption-bold-text-decoration` | `none` | Text decoration for bold captions. |
| `caption-default-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for captions. |
| `caption-default-font-size` | `0.75rem` | Font size for captions. |
| `caption-default-font-weight` | `400` | Font weight for captions. |
| `caption-default-letter-spacing` | `0.01875rem` | Letter spacing for captions. |
| `caption-default-line-height` | `0.875rem` | Line height for captions. |
| `caption-default-text-decoration` | `none` | Text decoration for captions. |
| `label-bold-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for bold labels. |
| `label-bold-font-size` | `0.625rem` | Font size for bold labels. |
| `label-bold-font-weight` | `700` | Font weight for bold labels. |
| `label-bold-letter-spacing` | `0.0375rem` | Letter spacing for bold labels. |
| `label-bold-line-height` | `1rem` | Line height for bold labels. |
| `label-bold-text-decoration` | `none` | Text decoration for bold labels. |
| `label-default-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for labels. |
| `label-default-font-size` | `0.625rem` | Font size for labels. |
| `label-default-font-weight` | `400` | Font weight for labels. |
| `label-default-letter-spacing` | `0.0375rem` | Letter spacing for labels. |
| `label-default-line-height` | `1rem` | Line height for labels. |
| `label-default-text-decoration` | `none` | Text decoration for labels. |
| `link-default-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for hyperlinks. |
| `link-default-font-size` | `0.875rem` | Font size for hyperlinks. |
| `link-default-font-weight` | `400` | Font weight for hyperlinks. |
| `link-default-letter-spacing` | `0.01875rem` | Letter spacing for hyperlinks. |
| `link-default-line-height` | `1.25rem` | Line height for hyperlinks. |
| `link-default-text-decoration` | `underline` | Text decoration for hyperlinks. |
| `notification-default-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for notifications. |
| `notification-default-font-size` | `0.5625rem` | Font size for notifications. |
| `notification-default-font-weight` | `700` | Font weight for notifications. |
| `notification-default-letter-spacing` | `0.01875rem` | Letter spacing for notifications. |
| `notification-default-line-height` | `0.75rem` | Line height for notifications. |
| `notification-default-text-decoration` | `none` | Text decoration for notifications. |
| `title-large-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for large titles. |
| `title-large-font-size` | `1.125rem` | Font size for large titles. |
| `title-large-font-weight` | `700` | Font weight for large titles. |
| `title-large-letter-spacing` | `0.01875rem` | Letter spacing for large titles. |
| `title-large-line-height` | `1.5rem` | Line height for large titles. |
| `title-large-text-decoration` | `none` | Text decoration for large titles. |
| `title-medium-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for medium titles. |
| `title-medium-font-size` | `1rem` | Font size for medium titles. |
| `title-medium-font-weight` | `700` | Font weight for medium titles. |
| `title-medium-letter-spacing` | `0.01875rem` | Letter spacing for medium titles. |
| `title-medium-line-height` | `1.5rem` | Line height for medium titles. |
| `title-medium-text-decoration` | `none` | Text decoration for medium titles. |
| `title-small-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for small titles. |
| `title-small-font-size` | `0.9375rem` | Font size for small titles. |
| `title-small-font-weight` | `700` | Font weight for small titles. |
| `title-small-letter-spacing` | `0.01875rem` | Letter spacing for small titles. |
| `title-small-line-height` | `1.25rem` | Line height for small titles. |
| `title-small-text-decoration` | `none` | Text decoration for small titles. |
| `title-subtitle-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for subtitles. |
| `title-subtitle-font-size` | `0.875rem` | Font size for subtitles. |
| `title-subtitle-font-weight` | `700` | Font weight for subtitles. |
| `title-subtitle-letter-spacing` | `0.01875rem` | Letter spacing for subtitles. |
| `title-subtitle-line-height` | `1.25rem` | Line height for subtitles. |
| `title-subtitle-text-decoration` | `none` | Text decoration for subtitles. |
| `title-x-large-font-family` | `Lato, "Helvetica Neue", sans-serif` | Font family for extra-large titles. |
| `title-x-large-font-size` | `1.3125rem` | Font size for extra-large titles. |
| `title-x-large-font-weight` | `700` | Font weight for extra-large titles. |
| `title-x-large-letter-spacing` | `0.01875rem` | Letter spacing for extra-large titles. |
| `title-x-large-line-height` | `2rem` | Line height for extra-large titles. |
| `title-x-large-text-decoration` | `none` | Text decoration for extra-large titles. |

## Spacing, sizing, and shape tokens

<Note>
  The comment in the table refers to pixels in calculation based on a root font-size of 16 px.
</Note>

| Token | Default value | Description |
| - | - | - |
| `border-1` | `0.0625rem` | Border width (1 px equivalent). |
| `border-2` | `0.125rem` | Border width (2 px equivalent). |
| `border-3` | `0.1875rem` | Border width (3 px equivalent). |
| `border-4` | `0.25rem` | Border width (4 px equivalent). |
| `border-6` | `0.375rem` | Border width (6 px equivalent). |
| `border-8` | `0.5rem` | Border width (8 px equivalent). |
| `dropshadow-1` | `0 0 0.5rem 0 rgba(0, 0, 0, 0.05)` | Subtle shadow effect. |
| `dropshadow-2` | `0 0.0625rem 0.25rem 0 rgba(0, 0, 0, 0.1)` | Medium shadow effect. |
| `dropshadow-3` | `0 0.25rem 0.75rem 0 rgba(0, 0, 0, 0.1)` | Pronounced shadow effect. |
| `radius-05` | `0.125rem` | Border radius (2 px equivalent). |
| `radius-1` | `0.25rem` | Border radius (4 px equivalent). |
| `radius-2` | `0.375rem` | Border radius (6 px equivalent). |
| `radius-3` | `0.5rem` | Border radius (8 px equivalent). |
| `radius-4` | `0.75rem` | Border radius (12 px equivalent). |
| `radius-5` | `1rem` | Border radius (16 px equivalent). |
| `radius-6` | `1.25rem` | Border radius (20 px equivalent). |
| `radius-7` | `1.5rem` | Border radius (24 px equivalent). |
| `radius-8` | `1.75rem` | Border radius (28 px equivalent). |
| `radius-half` | `2rem` | Border radius (32 px equivalent). |
| `size-05` | `0.125rem` | Size measurement (2 px equivalent). |
| `size-1` | `0.25rem` | Size measurement (4 px equivalent). |
| `size-2` | `0.5rem` | Size measurement (8 px equivalent). |
| `size-3` | `0.75rem` | Size measurement (12 px equivalent). |
| `size-4` | `1rem` | Size measurement (16 px equivalent). |
| `size-5` | `1.25rem` | Size measurement (20 px equivalent). |
| `size-6` | `1.5rem` | Size measurement (24 px equivalent). |
| `size-7` | `1.75rem` | Size measurement (28 px equivalent). |
| `size-8` | `2rem` | Size measurement (32 px equivalent). |
| `size-9` | `2.25rem` | Size measurement (36 px equivalent). |
| `size-10` | `2.5rem` | Size measurement (40 px equivalent). |
| `size-11` | `2.75rem` | Size measurement (44 px equivalent). |
| `size-12` | `3rem` | Size measurement (48 px equivalent). |
| `size-14` | `3.5rem` | Size measurement (56 px equivalent). |
| `size-15` | `3.75rem` | Size measurement (60 px equivalent). |
| `size-16` | `4rem` | Size measurement (64 px equivalent). |
| `size-18` | `4.5rem` | Size measurement (72 px equivalent). |
| `size-20` | `5rem` | Size measurement (80 px equivalent). |
| `space-05` | `0.125rem` | Spacing measurement (2 px equivalent). |
| `space-1` | `0.25rem` | Spacing measurement (4 px equivalent). |
| `space-2` | `0.5rem` | Spacing measurement (8 px equivalent). |
| `space-3` | `0.75rem` | Spacing measurement (12 px equivalent). |
| `space-4` | `1rem` | Spacing measurement (16 px equivalent). |
| `space-5` | `1.25rem` | Spacing measurement (20 px equivalent). |
| `space-6` | `1.5rem` | Spacing measurement (24 px equivalent). |
| `space-7` | `1.75rem` | Spacing measurement (28 px equivalent). |
| `space-8` | `2rem` | Spacing measurement (32 px equivalent). |
| `space-9` | `2.25rem` | Spacing measurement (36 px equivalent). |
| `space-10` | `2.5rem` | Spacing measurement (40 px equivalent). |
| `space-11` | `2.75rem` | Spacing measurement (44 px equivalent). |
| `space-12` | `3rem` | Spacing measurement (48 px equivalent). |
| `space-14` | `3.5rem` | Spacing measurement (56 px equivalent). |
| `space-15` | `3.75rem` | Spacing measurement (60 px equivalent). |
| `space-16` | `4rem` | Spacing measurement (64 px equivalent). |
| `space-18` | `4.5rem` | Spacing measurement (72 px equivalent). |
| `space-20` | `5rem` | Spacing measurement (80 px equivalent). |

<RelatedLinks title="RELATED GUIDES" />


# Content Uploader
Source: https://developer.box.com/guides/embed/ui-elements/uploader



<RelatedLinks title="REQUIRED GUIDES" />

The Box Content Uploader UI Element allows developers to embed an upload widget
in their desktop or mobile web application. Users can select files or use drag
and drop to upload. Large files will be uploaded with the <Link href="/reference/post-files-upload-sessions">Chunked
Upload</Link> API.

## Installation

<Link href="/guides/embed/ui-elements/installation">Learn how to install</Link> Box UI elements
either through NPM or the Box CDN.

## Authentication

The UI Elements are designed in an authentication agnostic way so whether
you are using UI Elements for users who have Box accounts (Managed Users) or
non-Box accounts (App Users), UI Elements should work out of the box. The
reason for this is that UI Elements only expect a "token" to be passed in for
authentication, and Box provides two different ways to generate tokens - OAuth
and JWT.

<Card href={localizeLink("/guides/authentication")} title="Compare authentication methods" />

## Demo

### Uploader

<iframe title="Box Content Uploader" />

### Uploader as popup

<iframe title="Box File Picker and Uploader as popups" />

<Info>
  **Access Token**

  These demos may not fully function until you provide a valid access token. For
  testing purposes, you can use your temporary developer token. This will need
  to be updated under the JS tab in the demo.
</Info>

## API

```js theme={null}
const { ContentUploader } = Box;
const uploader = new ContentUploader();

/**
 * Shows the content uploader.
 *
 * @public
 * @param {String} folderId - Folder ID to upload to.
 * @param {String} accessToken - Box API access token.
 * @param {Object|void} [options] - Optional options.
 * @return {void}
 */
uploader.show(folderId, accessToken, options);

/**
 * Hides and clears HTML for the uploader.
 *
 * @public
 * @return {void}
 */
uploader.hide();

/**
 * Adds an event listener to the content uploader.
 * Listeners should be added before calling show()
 * so no events are missed.
 *
 * @public
 * @param {String} eventName Name of the event.
 * @param {Function} listener Callback function.
 * @return {void}
 */
uploader.addListener(eventName, listener);

/**
 * Removes an event listener from the content uploader.
 *
 * @public
 * @param {String} eventName Name of the event.
 * @param {Function} listener Callback function.
 * @return {void}
 */
uploader.removeListener(eventName, listener);

/**
 * Removes all event listeners from the content uploader.
 *
 * @public
 * @return {void}
 */
uploader.removeAllListeners();
```

### Parameters

| Parameter | Type | Description |
| - | - | - |
| `folderId` | String | Box Folder ID. This will be the ID of the folder from which you want files to be uploaded to. If you want to use the Box All Files folder, then use `0` as the `folderId`. |
| `accessToken` | String | Box API access token to use. This should have upload access to the folder above. |
| `options` | Object | Optional options. See below for details. |

### Options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `container` | String | `document.body` | CSS selector of the container in which the content uploader should be placed. Calling `hide()` will clear out this container. |
| `sharedLink` | String | | Shared link URL, required if folder is shared and the access token doesn't belong to an owner or collaborator of the file. |
| `sharedLinkPassword` | String | | Shared link password, required if shared link has a password. |
| `onClose` | Function | | Callback function for 'Close' button, which will appear when there are no files to upload or when all uploads are complete. If this option is set to `null` the button will not appear. |
| `modal` | Object | | When the modal attribute is specified, then the content uploader will not be created in-place. Instead a button will be created in the container and clicking this button will launch the content uploader in a modal popup. See below for the modal options. |
| `size` | String | `undefined` | Indicates to the content uploader to fit within a small or large width container. Value can be absent or one of `small` or `large`. If absent the UI Element will adapt to its container and automatically switch between small width or large width mode. |
| `isTouch` | Boolean | Defaults to the browser and device's default touch support | Indicates to the content explorer that it is being rendered on a touch enabled device. |
| `fileLimit` | Number | 100 | The maximum number of files that can be uploaded at once. If more than `fileLimit` files are selected for upload, any beyond the first `fileLimit` files will not be included for upload. A warning message will be shown in the footer when this happens. |
| `requestInterceptor` | Function | | Function to intercept requests. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |
| `responseInterceptor` | Function | | Function to intercept responses. For an example see <Link href="https://codepen.io/box-platform/pen/jLdxEv">this CodePen</Link>. Our underlying XHR library is `axios.js` and we follow a <Link href="https://github.com/axios/axios#interceptors">similar approach for interceptors</Link>. |

### Modal Options

| Parameter | Type | Default | Description |
| - | - | - | - |
| `buttonLabel` | `String` | | Label for the button |
| `buttonClassName` | `String` | Box Blue Button | CSS class to decorate the button |
| `modalClassName` | `String` | | CSS class to decorate the modal popup content |
| `overlayClassName` | `String` | | CSS class to decorate the modal popup overlay |

### Events

| Event Name | Event Data | Description |
| - | - | - |
| `close` | | Will be fired when 'Close' button is clicked. |
| `complete` | `Array<File>` | Will be fired when all uploads in the current view are complete. Event data will be an array of File Object. |
| `upload` | File | Fired when a single file is successfully uploaded. Event data will be a File Object. |
| `error` | Object | Fired when a single file has an upload error. Event data will be an object with properties file from the File Web API and the error object error. |

## Scopes

If your application requires the end user to only be able to access a subset of
the Content Uploader functionality, you can use <Link href="/guides/authentication/tokens/downscope">Downscoping</Link> to
appropriately downscope the Access Token to a resulting token that has the
desired set of permissions, and can thus, be securely passed to the end user
client initializing the Content Uploader.

Below are a set of UI Element-specific scopes to go alongside Downscoping. These
allow developers to enable/disable UI controls on the Content Uploader by
configuring the appropriate scopes on the downscoped token. To learn
more, see <Link href="/guides/api-calls/permissions-and-errors/scopes">Dedicated Scopes for Box UI Elements</Link>.

### Base Scope

| Scope Name | Permissions granted |
| - | - |
| `base_upload` | Allows upload into the folder specified under "resource" of the Token Exchange request. |

### Sample Scenarios

| Scenario | Scopes |
| - | - |
| User wants to upload files to a Box folder | `base_upload` |

<RelatedLinks title="RELATED GUIDES" />


# Preview - Viewers & Events
Source: https://developer.box.com/guides/embed/ui-elements/viewers-and-events



<RelatedLinks title="REQUIRED GUIDES" />

This page describes the preview experience for each file type. It also lists the
events you can listen for by viewer type.

## Text Viewer

The text viewer renders previews of text files. For code files like `py` or
`rb`, it uses [`highlight.js`](https://github.com/isagalaev/highlight.js) to add
syntax highlighting.

### Behavior

The text viewer displays the first 192 KB of text in the file. Additional text is
truncated and a notification and download button are appended to the bottom of
the preview.

Re-sizing the viewer window will reflow the text to fit the available space and
the zoom in and out buttons will increase and decrease font size respectively.

This viewer supports printing and will attempt to print with appropriate syntax
highlighting when either `print()` is invoked or the print button is pressed.
Note that printing large files may cause some browsers to freeze for a few
seconds.

### Controls

* Zoom In
* Zoom Out
* Fullscreen: can be exited with the escape key

### Supported File Extensions

`as`, `as3as`, `asmas`, `batas`, `cas`, `ccas`, `cmakeas`, `cppas`, `csas`,
`cssas`, `cxxas`, `diffas`, `erbas`, `groovyas`, `has`, `hamlas`, `hhas`,
`htmas`, `htmlas`, `javaas`, `jsas`, `lessas`, `mas`, `makeas`, `mdas`, `mlas`,
`mmas`, `phpas`, `plas`, `plistas`, `propertiesas`, `pyas`, `rbas`, `rstas`,
`sassas`, `scalaas`, `scriptas`, `scmas`, `smlas`, `sqlas`, `shas`, `vias`,
`vimas`, `webdocas`, `xhtmlas`, `yaml`,

### Events

The text viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |
| `zoom` | The preview zooms in or out | 1. `{number}` **`zoom`**: new zoom value |
| | | 2. `{boolean}` **`canZoomIn`**: true if the viewer can zoom in more |
| | | 3. `{boolean}` **`canZoomOut`**: true if the viewer can zoom out more |
| `printsuccess` | An attempt to print triggered successfully | |

## 360 Video Viewer

The 360 video viewer renders a preview of a video stored as an equirectangular
projection (often recorded with a 360 camera).

### Behavior

This viewer gives you an interactive view of the 360 degree video.

### Controls

* Change the view direction with the left mouse button (single touch on touch-enabled device).

### VR button

When using a browser that supports WebVR and a suitable VR device is attached to
your computer, a VR button will be available to allow toggling in and out of VR
mode.

### Limitations

Currently, this previewer requires that the file be named with a `.360`
preceding the file extension. This is so that Preview SDK knows to run this
viewer rather than the standard video preview.

### Supported File Extensions

`360.3g2`, `360.3gp`, `360.avi`, `360.m2v`, `360.m2ts`, `360.m4v`, `360.mkv`,
`360.mov`, `360.mp4`, `360.mpeg`, `360.mpg`, `360.mts`, `360.qt`, `360.wmv`

### Events

The 360 video viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |

## SWF Viewer

The SWF viewer uses [`SWFObject`](https://github.com/swfobject/swfobject) to embed
SWF files.

### Behavior

If the user has the Adobe Flash Player plugin, `SWFObject` will embed the SWF file
and allow the plugin to render relevant content.

Note that all network requests made by the flash content will be blocked due to
security constraints, so any content that requires network connectivity will not
be rendered.

### Supported File Extensions

* `swf`

### Events

The SWF viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |

## Presentation viewer

The presentation viewer renders previews of PowerPoint files.

### Behavior

The presentation viewer remembers which slide you were viewing upon closing the
preview. The next time that file is opened, you will immediately be brought to
that slide. Scrolling the mouse up and down, or swiping up and down on mobile
will transition between slides. Zooming in or out will increase or decrease the
size of the slide respectively. If the zoom level causes the content to
overflow, scrolling the mouse will allow you to scroll around the slide. To
return to normal scrolling behavior, the user must zoom out until the overflow
is removed.

### Controls

* Zoom In
* Zoom Out
* Set Page: either with the up and down arrows, or by clicking the page number and entering text
* Fullscreen: can be exited with the escape key

### Supported File Extensions

`ppt`, `pptx`, `odp`

### Options

| Option | Type | Description |
| - | - | - |
| `annotations` | boolean | Optional. Whether annotations on content are shown. Defaults to `false` |

### Events

The presentation viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `string` **`error`** (optional): error message |
| | | 2. `object` **`file`**: current file |
| | | 3. `object` **`metrics`**: information from the logger |
| | | 4. `object` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `object` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `number` **`height`**: window height |
| | | 2. `number` **`width`**: window width |
| `zoom` | The preview zooms in or out | 1. `number` **`zoom`**: new zoom value |
| | | 2. `boolean` **`canZoomIn`**: true if the viewer can zoom in more |
| | | 3. `boolean` **`canZoomOut`**: true if the viewer can zoom out more |
| `pagerender` | A page renders | `number` page number of rendered page |
| `pagefocus` | A page is visible | `number` page number of focused page |
| `scrollstart` | The viewer starts to scroll | 1. `number` **`scrollTop`**: number of pixels scrolled from top of viewport |
| | | 2. `number` **`scrollLeft`**: number of pixels scrolled from left of viewport |
| `scrollend` | The viewer stops scrolling | 1. `number` **`scrollTop`**: number of pixels scrolled from top of viewport |
| | | 2. `number` **`scrollLeft`**: number of pixels scrolled from left of viewport |

## MP4 Viewer

The MP4 viewer renders previews for video files.

### Behavior

The MP4 viewer uses a black background to create a better viewing experience.
Volume can be muted or unmuted by clicking the volume icon, or changed by
dragging the volume scrubber. The position of the video can be changed by
clicking or dragging the playback scrubber.

### Controls

* Play/Pause
* Volume
* Settings
* Fullscreen (can be exited with the escape key)

### Settings

Settings are available through the cog icon in the preview toolbar.

* Video speed values: `0.25`, `0.5`, normal (`1`), `1.25`, `1.5`, `2.0`

### Supported File Extensions

`3g2`, `3gp`, `avi`, `m2v`, `m2ts`, `m4v`, `mkv`, `mov`, `mp4`, `mpeg`, `mpg`,
`ogg`, `mts`, `qt`, `wmv`

### Events

The MP4 viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `string` **`error`** (optional): error message |
| | | 2. `object` **`file`**: current file |
| | | 3. `object` **`metrics`**: information from the logger |
| | | 4. `object` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `object` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `number` **`height`**: window height |
| | | 2. `number` **`width`**: window width |
| `speedchange` | Media speed changes | `string` playback speed |
| `play` | The video plays | |
| `pause` | The video pauses | |
| `seek` | The video skips to a time | `number` time |

## MP3 Viewer

The MP3 viewer displays previews for audio files.

### Behavior

Volume can be muted or unmuted by clicking the volume icon, or changed by
dragging the volume scrubber. The position of the audio can be changed by
clicking or dragging the playback scrubber.

### Controls

* Play/Pause
* Volume
* Settings

### Settings

Settings are available through the cog icon in the preview toolbar.

* Audio Speed: `0.25`, `0.5`, normal (`1`), `1.25`, `1.5`, `2.0`

### Supported File Extensions

`aac`, `aif`, `aifc`, `aiff`, `amr`, `au`, `flac`, `m4a`, `mp3`, `ra`, `wav`, `wma`

### Events

The MP3 viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `string` **`error`** (optional): error message |
| | | 2. `object` **`file`**: current file |
| | | 3. `object` **`metrics`**: information from the logger |
| | | 4. `object` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `object` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `number` **`height`**: window height |
| | | 2. `number` **`width`**: window width |
| `speedchange` | Media speed changes | `string` playback speed |
| `play` | The video plays | |
| `pause` | The video pauses | |
| `seek` | The video skips to a time | `number` time |

## Office Viewer

The Office viewer renders previews of Microsoft Office documents by embedding an
`<iframe>` of Microsoft's Office Online viewer.

### Behavior

The Office viewer currently supports previews of Excel files using Microsoft
Office Online from within the Box Web Application. Support for platform use
cases and other Office file formats is in progress.

There are several limitations at the moment:

* File must be downloadable
* File size cannot be greater than 5MB
* File cannot be shared via a Box shared link with a password (shared links without passwords are okay)

### Supported File Extensions

`xlsx`

### Events

The Office viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |

## Markdown Viewer

The Markdown viewer uses
[`Remarkable`](https://github.com/jonschlinkert/remarkable) to parse markdown
files and [`highlight.js`](https://github.com/isagalaev/highlight.js) to add
syntax highlighting to code blocks contained within.

### Behavior

The Markdown viewer parses the first 192KB of raw markdown in the file and
renders it using GitHub's Markdown style. Additional content is truncated and a
notification along with a download button are appended to the bottom of the
preview.

The viewer supports
[GitHub Flavored
Markdown](https://guides.github.com/features/mastering-markdown/) including
tables, syntax highlighting, and automatic URL linking.

Re-sizing the viewer window will reflow the markdown to fit the available space.
Also, this viewer supports printing and will attempt to print the parsed
markdown and with syntax highlighting on code when either `print()` is invoked
or the print button is pressed. Note that printing large files may cause some
browsers to freeze for a few seconds.

### Controls

* Fullscreen (can be exited with the escape key)

### Supported File Extensions

`md`

### Events

The Markdown viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |
| `printsuccess` | An attempt to print triggered successfully | |

## `Model3D` viewer

The `Model3D` viewer renders previews of 3D model files and allows you to enable
different rendering modes to inspect various aspects of the model, for example
wireframe, texture coordinates, and more. Animation data is also supported for
files that contain it (for example `box3d`, `fbx`, `dae`).

### Behavior

The `Model3D` viewer gives you an interactive view of the model. The left mouse
button allows you to orbit about the model (single touch on touch-enabled
device). Double-clicking somewhere on the model allows you to change orbit
focus.

### Controls

* Zoom (change distance to the model) with the mouse wheel (or two-finger scroll on a touch-enabled device).
* Pan (lateral movement) with the right mouse button (or three-finger swipe on a touch-enabled device).
* Animation Selection: If the model that is being viewed contains animations, two animation buttons will be visible in the toolbar. The first allows you to play and pause the animation and the second allows the selection of the current animation.
* VR button: If using a browser that supports WebVR and a suitable VR device is attached to your computer, the VR button will allow toggling in and out of VR mode.

### Settings

Settings are available through the cog icon in the preview toolbar.

* Render Mode: Lit, Unlit, Normal, Shape, UV Overlay
* Toggle Wireframe
* Toggle Skeleton
* Camera Projection: Perspective, Orthographic
* Render Quality: Auto, Full
* Rotate Model: X, Y, Z

## `Box3D` Packages

Preview gives users the ability to view a single file within Box so, by default,
you can't view textures on your model. However, the Box web application gives
users the ability to create a Box3D package that combines all dependent files
into a single file that can be shared and previewed. To do this, right-click the
model file within Box and choose "Create 3D Package". All referenced files found
within Box will be included in the resulting package.

### Supported File Extensions

`box3d`, `fbx`, `dae`, `3ds`, `obj`, `stl`, `ply`

### Events

The `Model3D` viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |

## 360 Image viewer

The 360 image viewer renders a preview of an image stored as an equirectangular
projection (often taken with a 360 camera).

### Behavior

This viewer gives you an interactive view of a 360 degree image. First, a low
resolution version of the image is loaded to give a quick view before the full
resolution image is finished loading. Clicking and dragging with the left mouse
button will change the view direction (single touch and drag on touch-enabled
device).

### Controls

* Fullscreen (can be exited with the escape key)
* VR Button: When using a browser that supports WebVR and a suitable VR device is attached to your computer, a VR button will be available to allow toggling in and out of VR mode.

### Limitations

Currently, this previewer requires that the file be named with a '.360'
preceding the file extension. This is so that Preview SDK knows to run this
viewer rather than the standard image viewer.

### Supported File Extensions

`360.jpg`, `360.jpeg`, `360.png`, `360.ai`, `360.bmp`, `360.dcm`, `360.eps`,
`360.gif`, `360.ps`, `360.psd`, `360.svg`, `360.svs`, `360.tga`, `360.tif`,
`360.tiff`

### Events

The 360 image viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |

## Image viewer

The image viewer renders previews of image files.

### Behavior

Rotating the viewer will rotate the image 90 degrees clockwise. At the default
zoom level, clicking on the image will zoom in once. When zoomed in, clicking on
the document will return to the default zoom level. When zoomed out, clicking on
the document will zoom in until the original zoom level is reached.

### Controls

* Zoom In
* Zoom Out
* Rotate
* Fullscreen: can be exited with the escape key

### Supported File Extensions

`ai`, `bmp`, `dcm`, `eps`, `idml`, `indt`, `indd`, `inx`, `gif`, `png`, `ps`,
`psd`, `svs`, `tga`

### Options

| Option | Type | Description |
| - | - | - |
| `annotations` | boolean | Optional. Whether annotations on content are shown. Defaults to `false` |

### Events

The image viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |
| `zoom` | The preview zooms in or out | 1. `{number}` **`zoom`**: new zoom value |
| | | 2. `{boolean}` **`canZoomIn`**: true if the viewer can zoom in more |
| | | 3. `{boolean}` **`canZoomOut`**: true if the viewer can zoom out more |
| `pan` | The preview is panning | |
| `panstart` | Panning starts | |
| `panend` | Panning ends | |
| `rotate` | The image rotates | |
| `printsuccess` | An attempt to print triggered successfully | |

## Multi-image viewer

The multi-image viewer renders previews of multi-image files (`tiff`, `tif`).

### Behavior

At the default zoom level, clicking on the image will zoom in once. When zoomed
in, clicking on the document will return to the default zoom level. When zoomed
out, clicking on the document will zoom in until the original zoom level is
reached.

### Controls

* Zoom In
* Zoom Out
* Fullscreen: can be exited with the escape key
* Set Page: either with the up and down arrows, or by clicking the page number and entering text

### Supported File Extensions

`tif`, `tiff`

### Options

| Option | Type | Description |
| - | - | - |
| `annotations` | boolean | Optional. Whether annotations on content are shown. Defaults to `false` |

### Events

The image viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |
| `zoom` | The preview zooms in or out | 1. `{number}` **`zoom`**: new zoom value |
| | | 2. `{boolean}` **`canZoomIn`**: true if the viewer can zoom in more |
| | | 3. `{boolean}` **`canZoomOut`**: true if the viewer can zoom out more |
| `pagefocus` | A page is visible | `{number}` page number of focused page |
| `pan` | The preview is panning | |
| `panstart` | Panning starts | |
| `panend` | Panning ends | |

### Methods

The following methods are available for the multi-page image viewer.

| Method Name | Explanation | Method Parameters |
| - | - | - |
| `zoom` | Zooms the image | `{string}` 'in', 'out', or 'reset' |
| `previousPage` | Navigates to the previous page | |
| `nextPage` | Navigates to the next page | |
| `setPage` | Navigates to a given page | `{number}` page number |
| `toggleFullscreen` | Toggles full screen mode | |

## Document viewer

The document viewer renders previews for a variety of document types.

### Behavior

The document viewer remembers which page you were viewing upon closing the
preview. The next time that file is opened, you will immediately be brought to
that page. Resizing the viewer window will cause the document to resize.

### Controls

* Zoom In
* Zoom Out
* Set Page: either with the up and down arrows, or by clicking the page number and entering text
* Fullscreen (can be exited with the escape key)

### Supported File Extensions

`as`, `as3`, `asm`, `bat`, `c`, `cc`, `cmake`, `cpp`, `cs`, `css`, `csv`, `cxx`,
`diff`, `doc`, `docx`, `erb`, `gdoc`, `groovy`, `gsheet`, `h`, `haml`, `hh`,
`htm`, `html`, `java`, `js`, `less`, `log`, `m`, `make`, `md`, `ml`, `mm`,
`msg`, `odp`, `ods`, `odt`, `pdf`, `php`, `pl`, `plist`, `ppt`, `pptx`,
`properties`, `py`, `rb`, `rst`, `rtf`, `sass`, `scala`, `scm`, `script`, `sh`,
`sml`, `sql`, `tsv`, `txt`, `vi`, `vim`, `webdoc`, `wpd`, `xhtml`, `xls`,
`xlsm`, `xlsx`, `xml`, `xsd`, `xsl`, `yaml`

### Options

| Option | Type | Description |
| - | - | - |
| `annotations` | boolean | Optional. Whether annotations on content are shown. Defaults to `false` |

### Events

The document viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |
| `zoom` | The preview zooms in or out | 1. `{number}` **`newScale`**: new zoom value |
| | | 2. `{boolean}` **`canZoomIn`**: true if the viewer can zoom in more |
| | | 3. `{boolean}` **`canZoomOut`**: true if the viewer can zoom out more |
| `pagerender` | A page is rendered | `{number}` page number of rendered page |
| `pagefocus` | A page is visible | `{number}` page number of focused page |
| `scrollstart` | The viewer starts to scroll | 1. `{number}` **`scrollTop`**: number of pixels scrolled from top of viewport |
| | | 2. `{number}` **`scrollLeft`**: number of pixels scrolled from left of viewport |
| `scrollend` | The viewer stops scrolling | 1. `{number}` **`scrollTop`**: number of pixels scrolled from top of viewport |
| | | 2. `{number}` **`scrollLeft`**: number of pixels scrolled from left of viewport |
| `printsuccess` | An attempt to print triggered successfully | |
| `printsuccess` | An attempt to print failed | |

### Annotations

| Event Name | Explanation | Event Data |
| - | - | - |
| `annotationdraw` | Text is highlighted | |
| `annotationcommentpending` | User hovers back into a dialog that has a pending comment | |
| `annotationcreate` | Annotation is created | |
| `annotationcancel` | An annotation was started but then abandoned before it was created | |
| `annotationdelete` | Annotation with provided `AnnotationID` is deleted. If no ID is provided, deletes the first (and only remaining) annotation in the thread. | |

## `<iframe>` viewer

The `<iframe>` viewer embeds a frame to show content rendered from an external
source.

### Behavior

The `<iframe>` viewer is used for previews of Box Notes.

Box Notes has full-featured viewers within the main Box Web
Application, but these full viewers are not initialized when users navigate from
previews of other files that may be in the same directory as the Notes
files. In this situation, the `<iframe>` viewer embeds a view-only render of
the Box Note file.

### Supported File Extensions

`boxnote`

### Events

The `<iframe>` viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |

## DASH viewer

The DASH viewer renders previews for video files using [`Shaka Player`][shaka].

### Behavior

The DASH viewer uses a black background to create a more native viewing
experience. Video is streamed in chunks of bytes at an initial quality
determined automatically. Volume can be muted or unmuted by clicking the volume
icon, or changed by dragging the volume scrubber. The position of the video can
be changed by clicking or dragging the playback scrubber.

### Controls

* Play/Pause
* Volume
* Settings
* Fullscreen (can be exited with the escape key)

### Settings

Settings are available through the cog icon in the preview toolbar.

* Video Speed: `0.25`, `0.5`, normal (`1`), `1.25`, `1.5`, `2.0`
* Video Quality: `480p`, `1080p`, `auto`

### Supported File Extensions

`3g2`, `3gp`, `avi`, `m2v`, `m2ts`, `m4v`, `mkv`, `mov`, `mp4`, `mpeg`, `mpg`,
`ogg`, `mts`, `qt`, `wmv`

### Events

The DASH viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |
| `speedchange` | The media speed changes | `{string}` playback speed |
| `qualitychange` | The video quality changes | `{string}` media quality |
| `bandwidthhistory` | Gives bandwidth history when the preview is destroyed | `{array}` bandwidth information |
| `switchhistory` | Gives quality switching history when the preview is destroyed | `{array}` quality switch objects |
| `adaptation` | Quality adapts to a change in bandwidth | `{number}` bandwidth |
| `play` | The video plays | |
| `pause` | The video pauses | |
| `seek` | The video skips to a time | `{number}` time |

## CSV viewer

The CSV viewer uses [`PapaParse`](https://github.com/mholt/PapaParse) to parse
CSV and TSV files and [`React Virtualized`][reactv] to display the parsed data
in a table.

### Behavior

Resizing the viewer window will cause the table to resize, and the zoom in and
out buttons will increase and decrease font size respectively. Currently, column
and row sizes are fixed and overflowing text will be truncated.

This viewer does not support printing.

### Controls

* Zoom In
* Zoom Out
* Fullscreen (can be exited with the escape key)

### Supported File Extensions

`csv`, `tsv`

### Events

The CSV viewer triggers the following events.

| Event Name | Explanation | Event Data |
| - | - | - |
| `destroy` | The preview is intentionally destroyed | |
| `load` | The preview loads | 1. `{string}` **`error`** (optional): error message |
| | | 2. `{object}` **`file`**: current file |
| | | 3. `{object}` **`metrics`**: information from the logger |
| | | 4. `{object}` **`viewer`**: current viewer |
| `notification` | A notification is displayed | |
| `navigate` | The preview is shown for a given index | `{object}` file |
| `reload` | The preview reloads | |
| `resize` | The preview resizes | 1. `{number}` **`height`**: window height |
| | | 2. `{number}` **`width`**: window width |
| `zoom` | The preview zooms in or out | 1. `{number}` **`zoom`**: new zoom value |
| | | 2. `{boolean}` **`canZoomIn`**: true if the viewer can zoom in more |
| | | 3. `{boolean}` **`canZoomOut`**: true if the viewer can zoom out more |

[reactv]: https://github.com/bvaughn/react-virtualized

[shaka]: https://github.com/google/shaka-player

<RelatedLinks title="RELATED GUIDES" />


# Android
Source: https://developer.box.com/guides/mobile/android/index



The [Box Android SDK][android-sdk] provides native access to the Box API from
within your Android project.

<Warning>
  As of May 31, 2023 Android SDK is no
  longer supported.
  You can still use your
  existing Android SDK applications with no impact,
  but you won't receive new features,
  updates, or bug fixes.

  If you would like to continue getting
  the latest and greatest Android features,
  we recommend using Java SDK to build apps on Android.
  Refer to [this][android-docs] documentation for more details.
</Warning>

[android-sdk]: https://github.com/box/box-android-sdk

[android-docs]: https://github.com/box/box-java-sdk/blob/legacy/doc/android.md


# Android SDK Installation
Source: https://developer.box.com/guides/mobile/android/install



<Warning>
  As of May 31, 2023 Android SDK is
  no longer supported. You can still
  use your existing Android SDK applications
  with no impact, but you won't receive new features,
  updates, or bug fixes.

  If you would like to continue
  getting the latest and greatest Android
  features, we recommend using Java SDK to build apps
  on Android. Refer to [this][android-docs] documentation for more details.
</Warning>

The Android SDK may be obtained through several methods:

* Adding as a Maven or Gradle dependency
* Cloning the source into your project
* Downloading one of the precompiled JARs

## Add as a Maven dependency

Add the following to your Maven dependencies.

```xml theme={null}
<dependency>
    <groupId>com.box</groupId>
    <artifactId>box-android-sdk</artifactId>
</dependency>
```

## Add as a Gradle dependency

Add the following to your `build.gradle` file.

```js theme={null}
dependencies {
    implementation 'com.box:box-android-sdk:4.2.3'
}
```

## Clone the source

The Box Android SDK source code may be obtained by cloning or downloading the
[project from Github][android-sdk-github].

## Download precompiled JARs

Precompiled JARs for the Android SDK may be obtained from the Github project
[releases page][android-sdk-github-releases].

<Warning>
  If one of the precompiled JARs is being used, the Android SDK will also
  require the following dependency: `minimal-json v0.9.1` (for Maven:
  `com.eclipsesource.minimal-json:minimal-json:0.9.1`)
</Warning>

[android-sdk-github]: https://github.com/box/box-android-sdk/tree/master/box-content-sdk

[android-sdk-github-releases]: https://github.com/box/box-android-sdk/releases

[android-docs]: https://github.com/box/box-java-sdk/blob/legacy/doc/android.md


# iOS
Source: https://developer.box.com/guides/mobile/ios/index



The [Box iOS SDK][ios-sdk] provides native access to the Box API from
within your iOS project.

[ios-sdk]: https://github.com/box/box-ios-sdk


# Configure a platform app
Source: https://developer.box.com/guides/mobile/ios/quick-start/configure-box-app



<ProgressBar />

To start making authenticated API calls to the Box API with the **Box iOS SDK**, an **Access Token** will be needed. The simplest way to generate a valid
token is to generate a new **platform app** and manually generate a short lived developer token.

The developer token is generated through the developer console UI and will be
valid for one hour before having to be manually refreshed.

## Set up a Box app

<Grid>
  <Choose>
    # Create a new Box app

    Create and configure a new Box JWT application from which a developer
    token may be generated.
  </Choose>

  <Choose>
    # Use an existing app

    Use one of your existing Box JWT applications from the Box developer
    console.
  </Choose>
</Grid>

<Choice>
  # Create a new Box app

  To create a new Box application that may be used to generate a developer
  token, use the following steps.

  1. Go to the [Developer Console][devconsole] > **My Platform Apps**.
  2. Select **Create Platform App**.
  3. Select **Platform App** as the type of application to create, and click **Next**.
  4. Enter the **App Name**, an optional **Description** and **Purpose** of the App. Confirm with **Next**.
  5. Select **User Authentication (OAuth 2.0)** as the authentication method, and click **Create App**.
  6. Optionally, scroll to the **Application Scopes** section of the same screen and select any additional permissions you want to enable for this application.
  7. At the top of the page click the button to **Save Changes**.
</Choice>

<Choice>
  # Use an Existing JWT Box application

  If you have an existing JWT based Box application in your
  [developer console][devconsole] that you
  would like to use, skip to the next step.
</Choice>

## Generate a developer token

Now that an application is available, we need to create a developer token that
may be used to authenticate the Box iOS SDK to start making calls to the Box
APIs.

1. Go to the [Developer Console][devconsole]
2. Load the application that you would like to use
3. In the left navigation menu, click on **Configuration**
4. Under **Developer Token**, click the **Generate Developer Token** button
5. Copy the token for the next step to make an API call

## Summary

* You created a new, or are using an existing, Box app
* You have generated and copied the developer token

<Observe>
  <Next>I have a developer token</Next>
</Observe>

[devconsole]: https://cloud.app.box.com/developers/console


# Create an iOS App
Source: https://developer.box.com/guides/mobile/ios/quick-start/create-ios-app



<ProgressBar />

Before installing the Box iOS SDK you'll need to have an iOS application
available to add the dependencies into. We'll create a new blank application
now.

## Setup an iOS App

Xcode will be the tool that we use to create and edit our iOS application
during this quick-start guide. If you don't have Xcode, download it now from the
[Apple developer site](https://developer.apple.com/xcode/).

If this is the first application you're creating in Xcode or you already have
application development experience in it, we'll start our integration of the
Box iOS SDK with a new blank application.

1. Start Xcode
2. From the top menu, select **File** -> **New** -> **Project...**
3. Select the option for **Single View App**
   <Frame>
     <img alt="Select iOS application type" />
   </Frame>
4. Enter your application configuration information, including the `Product Name`, `Organization Identifier`, and `Organization Name`.
   <Frame>
     <img alt="Configure iOS application" />
   </Frame>
5. Select a local storage location for the application and click **Create**

## Summary

* You created a new blank iOS application in Xcode

<Next>I created a blank iOS application</Next>


# Learn to use the iOS SDK
Source: https://developer.box.com/guides/mobile/ios/quick-start/index



<Frame>
  <img alt="iOS emulator" />
</Frame>

The Box iOS SDK is a [Swift language](https://developer.apple.com/swift/)
wrapper for adding the Box API into your iOS project.

## Requirements

To begin working with the Box iOS SDK and this quick start, the following are
required:

* iOS 11.0+ / Mac OS X 10.13+
* Xcode 10.0+

## Overview

This guide will take you through the following steps.

1. <Link href="/guides/mobile/ios/quick-start/create-ios-app">Create a new iOS app</Link> in Xcode.
2. <Link href="/guides/mobile/ios/quick-start/install-ios-sdk">Install the iOS SDK</Link> into your project.
3. <Link href="/guides/mobile/ios/quick-start/configure-box-app">Configure a Box App</Link> so that the iOS SDK can access the Box API.
4. <Link href="/guides/mobile/ios/quick-start/make-api-call">Make an API call</Link> to the Box API with the iOS SDK.


# Install the iOS SDK
Source: https://developer.box.com/guides/mobile/ios/quick-start/install-ios-sdk



<ProgressBar />

With an iOS application in place, you will need to import the required **Box
iOS SDK** dependencies into your project using one of the available package
manager options.

## Select a package manager to use

<Grid>
  <Choose>
    # Carthage

    Carthage is a decentralized dependency manager for Swift
    and Objective-C Cocoa projects. It is open-source and built
    with Swift.
  </Choose>

  <Choose>
    # CocoaPods

    CocoaPods is a centralized dependency manager for Swift and
    Objective-C Cocoa projects. It is open-source and was built
    with Ruby.
  </Choose>

  <Choose>
    # Swift Package Manager

    The Swift Package Manager is a tool for managing the distribution
    of source code, making it easy to share your code and reuse
    others’ code.
  </Choose>
</Grid>

<Choice>
  # Install the iOS SDK using Carthage

  1. From a terminal window, install Carthage: `brew install carthage`. Visit the [Carthage documentation][carthage-docs] for other installation methods.
  2. At the root of your iOS application folder, where the `{APPNAME}.xcodeproj` is located, create a new file named `Cartfile`, without an extension.
  3. Open the `Cartfile` and add the **Box iOS SDK** dependency with `git "https://github.com/box/box-ios-sdk.git" ~> 3.0`, then save and close the file.
  4. From the terminal, in the folder where the `Cartfile` is present, update all dependencies: `carthage update --platform iOS`. A `Cartfile.resolved` file and a `Carthage` directory will be created in the directory.
  5. Within a Finder or File Explorer window load the **Carthage** -> **Build** -> **iOS** directory. This should have a framework file named `BoxSDK.framework`. Keep this window open as we'll use it to add the framework to our project in the next step.
  6. In your Xcode project, click on the name of your application at the top of the project navigator on the left. In the content that displays, click on the name of your project under the **TARGETS** option. Scroll down to **Frameworks, Libraries, and Embedded Content**.
  7. Drag `BoxSDK.framework` from our Finder window over to the frameworks section.

  <Frame>
    <img alt="Add framework to project" />
  </Frame>
</Choice>

<Choice>
  # Install the iOS SDK using CocoaPods

  1. From a terminal window, install CocoaPods: `sudo gem install cocoapods`.
  2. At the root of your iOS application folder, where the `APPNAME.xcodeproj` is located, run `pod init` to create a new `Podfile` with smart defaults.
  3. Load `Podfile`, add the **Box iOS SDK** dependency under `# Pods for {APPNAME}` with `pod 'BoxSDK', '~> 3.0'`, then save and close.
  4. From the terminal, in the folder where the `Podfile` is present, download all dependencies: `pod install`.
  5. Open `.xcworkspace` in Xcode: `open {APPNAME}.xcworkspace` and build the project.
</Choice>

<Choice>
  # Install the iOS SDK using the Swift Package Manager

  1. In your Xcode project, click on the name of your application at the top of the project navigator on the left. In the content that displays, click on the name of your project under the **PROJECT** option.
  2. Click on **Swift Packages** and click on the `+` to add a package.
  3. Enter the following repository URL `https://github.com/box/box-ios-sdk.git` and click next.
  4. Leave the default settings and click next to finish importing.

  <Frame>
    <img alt="Add framework to project" />
  </Frame>
</Choice>

## Summary

* You either selected to install the iOS dependencies using Carthage
  * You installed Carthage
  * You created a `Cartfile` with the Box iOS SDK dependency
  * You installed the iOS SDK dependencies
  * You manually imported the built dependencies into the Xcode project framework list.
* Or selected to use **CocoaPods** and
  * You installed CocoaPods
  * You created a new `Podfile` with the Box iOS SDK dependency
  * You installed the iOS SDK dependencies
  * You built the project in Xcode
* Or selected to use the **Swift Package Manager** and
  * You imported the iOS SDK `.git` repository into the Swift packages

<Observe>
  <Next>I've installed the Box iOS SDK dependencies</Next>
</Observe>

[carthage-docs]: https://github.com/Carthage/Carthage#installing-carthage


# Make an API call
Source: https://developer.box.com/guides/mobile/ios/quick-start/make-api-call



<ProgressBar />

With our Box and iOS applications created and configured with the **Box iOS
SDK** we can now make our first call to Box APIs.

Using our blank iOS application, we will create a button to trigger
a request to Box to fetch the name of the currently authenticated user.

<Warning>
  Using blocking actions as we use in these examples is slow. In a production
  app these blocking actions would need to be replaced with proper task
  delegation and non-blocking actions.
</Warning>

## Create a button

Within your Swift application in Xcode, load `ContentView.swift`. At the top of
the file you will see a `struct` for `ContentView`, within which is a basic
string that will be output to your iOS application if you run the app in an
emulator.

```swift theme={null}
import SwiftUI

struct ContentView: View {
  var body: some View {
    Text("Hello, World!")
  }
}
```

We'll first replace the `Text` output line with a button to be able to trigger
off the call to get the current user. Replace that line with the below button.

```swift theme={null}
Button(action: {
  // Perform some action
}) {
  Text("Click to get current user")
}
.padding(10)
.cornerRadius(20)
.foregroundColor(.white)
.background(Color.blue)
```

Our next step is to add an action for the button which will fetch a user's
details from Box.

## Add an API call button action

When a user clicks the button, we want to fetch the user's details. To achieve
this we need to do two things, add the import for the **Box iOS SDK** and add
the button action to make the call.

At the top of the `ContentView.swift` file, add `import BoxSDK` with the other
import statement.

Next, within the button action, where we currently have a comment placeholder,
add a call to the iOS SDK to fetch the current user. When the API call
completes it will print an authentication message to the developer console. For
ease of implementation, we have a blocking `sleep(5)` call in place in order to
test that the iOS SDK can make calls from our iOS SDK by providing enough time
for the request to complete.

Replace `{{YOUR DEVELOPER TOKEN}}` with your developer token.

```swift theme={null}
let client = BoxSDK.getClient(token: "{{YOUR DEVELOPER TOKEN}}")

client.users.getCurrent(fields:["name", "login"]) { (result: Result<User,
  BoxSDKError>) in
  guard case let .success(user) = result else {
      print("Error getting user information")
      return
  }
  print("Authenticated as \(user.name)")
}

sleep(5)
```

Build and run your sample application in the iOS emulator.

<Warning>
  If you run this code an hour or more after you created the developer
  token in the last step, you will need to revoke and generate a new developer
  token using the same method in the
  <Link href="/guides/mobile/ios/quick-start/configure-box-app">previous step</Link> as the
  developer token will only persist for 60 minutes.
</Warning>

Once the application loads in the emulator you should see the button we
created. Click it to start the API request.

Within the Xcode developer console you should see the API request and response,
with the last line showing the user print statement that we specified.

```bash theme={null}
◁ Status code: 200: no error
◁ Headers:
    ◁ Cache-Control, Value: no-cache, no-store
    ◁ BOX-REQUEST-ID, Value: 1c55151238444132eca16b4c2346d005
    ◁ Transfer-Encoding, Value: Identity
    ◁ content-type, Value: application/json
    ◁ Connection, Value: keep-alive
    ◁ Strict-Transport-Security, Value: max-age=31536000
◁ Body: {"type":"user","id":"123456789","name":"Test
          User","login":"testuser@test.com"}

Authenticated as Optional("Test User")
```

<Note>
  If you don't see the Xcode developer console, from the menu click **View** ->
  **Debug Area** -> **Activate Console**
</Note>

Congratulations, you've now configured the **Box iOS SDK** and have made your
first call to the Box API.

## Summary

* You added a button to your blank iOS application
* You added a request to fetch the current user using the iOS SDK

<Next>I made an API call</Next>


# iOS quick start: next steps
Source: https://developer.box.com/guides/mobile/ios/quick-start/next-steps



<ProgressBar />

You've reached the end of this Quick Start guide. By now you should have taken
the following steps.

1. <Link href="/guides/mobile/ios/quick-start/create-ios-app">Created a new iOS app</Link> in Xcode.
2. <Link href="/guides/mobile/ios/quick-start/install-ios-sdk">Installed the iOS SDK</Link> into your project.
3. <Link href="/guides/mobile/ios/quick-start/configure-box-app">Configured a Box App</Link> so that the iOS SDK can access the Box API.
4. <Link href="/guides/mobile/ios/quick-start/make-api-call">Made your first API call</Link> to the Box API with the iOS SDK.

## Next things to do

To take the next step with your application, the following resources are
recommended.

* <Link href="/guides/authentication/tokens/downscope">Token Downscoping</Link>: In this quick start guide you used a developer token to make your first call. To implement a scalable solution you should have a server-side solution to generate downscoped tokens to replace that implementation.
* [Official JWT sample application][sample-jwt]: Bundled with the iOS SDK, this sample application will get you started quickly with a properly structured Box JWT application, which doesn't require user login.
* [Official OAuth 2 sample application][sample-oauth]: Bundled with the iOS SDK, this sample application will get you started quickly with a properly structured Box OAuth 2 application, which requires user login.

[sample-jwt]: /guides/authentication/jwt/jwt-setup

[sample-oauth]: /guides/authentication/oauth2/oauth2-setup


# Deep Linking
Source: https://developer.box.com/guides/mobile/mobile-deep-linking



Box’s mobile applications support deep linking into folder and file objects.
From a web page or native app it is possible to deep link to open an object
directly in Box.

The following URLs are supported in Box’s mobile applications:

| Application | Object Type | Deep Link URL | iOS & Android |
| - | - | - | - |
| **Box** | Folder | `boxapp://folder?id=[folderid]` | Version 3.7+ |
| | File | `boxapp://file?id=[fileid]` | |
| | Shared Link | `boxapp://sharedlink?url=[sharedlink]` | |
| | | | |
| **Box for EMM** | Folder | `boxemm://folder?id=[folderid]` | Version 3.7+ |
| | File | `boxemm://file?id=[fileid]` | |
| | Shared Link | `boxemm://sharedlink?url=[sharedlink]` | |


# Postman Collection
Source: https://developer.box.com/guides/tooling/postman/index



<Link href="https://postman.com">Postman</Link> is a tool that lets you build and test HTTP requests in an
easy-to-use interface without configuring a full development environment.

The **Box Postman Collection** is a set of preconfigured requests that make it
possible to get started with the Box API without having to manually configure
the requests.

## Quickstart

### Step 1: Install Postman

<Link href="https://www.postman.com/downloads/">Download</Link> and install the Postman app for your operating system
(Windows, Mac, or Linux). Optionally,
<Link href="https://identity.getpostman.com/signup">create a Postman account and sign in</Link>.

### Step 2: Configure a Box App

To use the Postman Collection, you need a **Box App** to authenticate
with the Box API. The following examples use OAuth 2.0, but other
authentication methods are available.

1. Go to the <Link href="https://cloud.app.box.com/developers/console">Developer Console</Link>.
2. Either:
   * Select your application and make sure it uses **Standard OAuth 2.0** as the authentication method, or
   * Select **New App**, then enter an **App Name** and select **OAuth 2.0** as the **App Type**.
3. In the **Configuration** tab, scroll to the **OAuth 2.0 Redirect URIs**
   section and set the **Redirect URI** to
   `https://oauth.pstmn.io/v1/callback`.

   <Info>
     If you are using the Postman web app rather than the desktop app, use
     `https://oauth.pstmn.io/v1/browser-callback` for all relevant instructions.
   </Info>
4. Scroll to the **Application Scopes** section to select your desired
   <Link href="/guides/api-calls/permissions-and-errors/scopes">scopes</Link>.
   Your application must have at least one of the following scopes:
   * `Manage users`
   * `Read all files and folders stored in Box`
   * `Read and write all files and folders in Box`
5. At the top of the page, click **Save Changes**.
6. From the **OAuth 2.0 Credentials** section, copy the **Client ID** and
   **Client Secret**.

### Step 3: Log in to Box

Use the **Client ID** and **Client Secret** from the previous step to
authenticate with Box through Postman's OAuth 2.0 flow.

1. In Postman, create a <Link href="https://learning.postman.com/docs/sending-requests/create-requests/request-basics/">new request</Link> or open an existing one.
2. Go to the **Authorization** tab.
3. Set the **Type** to **OAuth 2.0**.
4. If you are using the Postman desktop app, select **Authorize using
   browser**.
5. Fill in the **Configure New Token** fields:

| Field | Value |
| - | - |
| **Token Name** | Any name, for example `Box Access Token` |
| **Grant Type** | `Authorization Code` |
| **Callback URL** | `https://oauth.pstmn.io/v1/callback` (auto-filled when **Authorize using browser** is selected). |
| **Auth URL** | `https://account.box.com/api/oauth2/authorize` |
| **Access Token URL** | `https://api.box.com/oauth2/token` |
| **Client ID** | Your app's Client ID from the Developer Console |
| **Client Secret** | Your app's Client Secret from the Developer Console |
| **Scope** | Leave empty |
| **State** | Leave empty |
| **Client Authentication** | `Send client credentials in body` |

6. Click **Get New Access Token**.
7. A browser window opens where you log in to your Box account and grant the
   app access.
8. Once approved, Postman receives your access token. Select
   **Use Token**.

### Step 4: Fork the Box Postman Collection

Click the button below to fork the **Box Postman Collection** into your
Postman workspace.

<Postman />

It is recommended to fork (rather than copy) the collection so you receive
updates when Box makes changes to it. Once imported, the collection appears
in Postman's left-hand sidebar. You can explore over 170 API endpoints
organized by resource type.

### Step 5: Configure the Box environment

The Box Postman Collection uses environment variables to authenticate API
requests. Before making calls, you need to populate these variables in the
**Box** environment that was imported with the collection.

1. In the lefthand sidebar of Postman, select **Box** from the **Environments** dropdown.
2. Complete the fields as follows:

| Variable | Value |
| - | - |
| `client_id` | Your app's Client ID from the Developer Console |
| `client_secret` | Your app's Client Secret from the Developer Console |
| `grant_type` | `authorization_code` |

3. Click **Save**.

4. Next, you need to obtain an authorization `code` and exchange it for an
   access token. To get the code, visit the following URL in your browser,
   replacing `[CLIENT_ID]` with your Client ID:

`https://account.box.com/api/oauth2/authorize?response_type=code&client_id=[CLIENT_ID]&redirect_uri=https://oauth.pstmn.io/v1/callback
`

5. Log in and grant access. After the redirect, copy the `code` parameter from
   the end of the URL in your browser's address bar. The code expires after
   **30 seconds**, so complete the next steps quickly.
6. Back in Postman, in the Box environment, enter `code` as the **Variable** and paste the code into the **Value** field.
7. Open the **Authorization** folder, select **Refresh access token**, and click **Send**.
8. When successful, the response returns an `access_token` and `refresh_token`. Enter these into your Box environment.

### Step 6: Test your Box environment

1. In the Box Postman Collection, expand the **Folders** folder and select
   **List items in folder**.
2. The `folder_id` defaults to `0` (the root folder). Leave it as-is or
   change it to a specific folder ID.
3. Click **Send**.

The response **Body** tab displays the items in the folder.

<Warning>
  If Postman returns an authentication error, your access token may have
  expired. See <Link href="/guides/tooling/postman/refresh">Refresh an Access
  Token</Link> for details.
</Warning>

## Additional information

* Review the <Link href="https://learning.postman.com/docs/getting-started/overview/">official Postman documentation</Link> from the Postman
  team.
* Learn how to <Link href="/guides/tooling/postman/refresh">refresh an access
  token</Link> to handle token expiration, including automatic refresh.

<RelatedLinks title="RELATED GUIDES" />


# Refresh an Access Token
Source: https://developer.box.com/guides/tooling/postman/refresh



The Box Postman Collection uses an **Access Token** to authenticate API
requests on your behalf. Access tokens expire after 1 hour and must be
refreshed.

## Using a refresh token

If you configured a **Box App** in
<Link href="/guides/tooling/postman#step-2-configure-a-box-app">step 2</Link> of the Postman
quickstart, your Box environment should contain a valid `client_id` and
`client_secret`. Together with the `refresh_token`, these can be used to
obtain a new `access_token`.

<Frame>
  <img alt="A valid client ID and secret in the Postman environment" />
</Frame>

To refresh the access token, open the **Authorization** folder in the Box
Postman Collection and select **Refresh access token**.

<Frame>
  <img alt="The refresh access token API call in Postman" />
</Frame>

Click **Send**.

<Frame>
  <img alt="Postman Send button" />
</Frame>

When successful, your environment is updated with a new `access_token` and
`refresh_token`, and you can resume making API calls.

<Warning>
  Refresh tokens are single-use and expire after 60 days of inactivity. Each
  time you use a refresh token, a new one is issued and the 60-day window
  resets.

  If a refresh token expires, you need to obtain a new token pair by going
  through the <Link href="/guides/tooling/postman">quickstart</Link> again.
</Warning>

## Automatic token refresh

The Box Postman Collection can automatically detect an expired `access_token`
and refresh it before sending your request. This feature is enabled by
default.

To toggle it, edit your Box Postman environment and set the
`enable_auto_refresh_access_token` variable to `true` or `false`.

<Frame>
  <img alt="Box Postman environment variables" />
</Frame>

When enabled, the collection checks whether your `access_token` has expired
before each API call and refreshes it automatically if needed.

## Re-authenticating

If your `refresh_token` has expired, typically because the collection hasn't
been used in over 60 days, you need to re-authenticate by repeating the
<Link href="/guides/tooling/postman">quickstart</Link>.

Before restarting, delete your existing **Box** Postman environment. Click
the **gear** icon in the top right, select your environment, and click
**Delete**.

<Frame>
  <img alt="Delete the Box Postman environment" />
</Frame>

Then follow the <Link href="/guides/tooling/postman">quickstart</Link> from the beginning.

<Warning>
  When re-importing the Box Postman Collection, Postman may ask whether to
  import it as a copy or replace the existing one. Importing as a copy
  preserves any custom changes you have made to API requests.
</Warning>


# Box for Agentforce Extension package
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/box-agentforce-package



The [Box for Agentforce Extension package][agentforce] is an extension of the Box for Salesforce managed
package. This extension provides reusable Agentforce <Link href="/guides/tooling/salesforce-toolkit/flow-actions">actions</Link> that
help automate workflows and enhance intelligent agent-based processes within
Salesforce.
It builds on the core features of the Box for Salesforce package and uses
global, invocable Apex methods to improve functionality. The Box for Agentforce
Extension package references the methods by using the Box namespace in
Agentforce Actions.

## Methods in Agentforce Flows

The list below contains example <Link href="/guides/tooling/salesforce-toolkit/methods">methods</Link> that can be invoked in
Agentforce.

### Folder & File Management

* Create Folder
* Create Folder Association
* Create Folder for Record ID
* Create Folder for Record ID from Template
* Get Folder Contents by Folder ID
* Get Folder ID by Record ID
* Get Folder URL
* Move Folder
* Get Object Folder by Record ID
* Get Record ID by Folder ID
* Get URL for Folder

### Metadata Management

* Create Box Metadata by File ID
* Create Box Metadata by Folder ID
* Delete Box Metadata by File ID
* Delete Box Metadata by Folder ID
* Update Box Metadata by Folder ID
* Get Box Metadata by File ID
* Get Box Metadata by Folder ID

### Collaboration

* Create Collaboration
* Create Collaboration on Record
* Edit Collaboration
* Delete Collaboration

### Box Hubs

* Get Hubs
* Get Hub Collaborations
* Copy Hub
* Create Hub
* Get Hub by ID

### Additional Actions

* Create File from Attachment
* Get DocGen Batch
* Get Folder Associations by Salesforce Record ID
* Get Metadata Cascade Policies by Folder ID
* Get Metadata Cascade Policy by ID
* Create Metadata Cascade Policy
* Delete Metadata Cascade Policy
* Create Slack Channel Mapping
* Set Slack Channel Access Management Disabled

[agentforce]: https://support.box.com/hc/en-us/articles/40370228349331-Installing-Box-for-Agentforce

<RelatedLinks title="RELATED GUIDES" />


# Box Doc Gen Toolkit
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/doc-gen-toolkit



The `DocGenToolkit` class provides a comprehensive interface for Box Document Generation operations within the Salesforce managed package. This class handles document generation requests, template management, and batch processing for creating documents from templates.

## Class signature

```
Global with sharing class DocGenToolkit
```

## Constructor

### `DocGenToolkit()`

Default constructor for creating a new instance of the `DocGenToolkit`.

```
DocGenToolkit toolkit = new DocGenToolkit();
```

## Document generation methods

### `submitDocGenBatch`

Submits a document generation batch request to Box.

| Parameter | Type | Description |
| - | - | - |
| `docGenRequest` | `DocGenRequest` | The request object containing all necessary parameters for doc generation. |

Returns:

* `DocGenResponse` - The response containing batch information and status.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
DocGenRequest request = new DocGenRequest();
request.file.Id = '123456789';
request.destination_Folder.Id = '987654321';
request.output_type = 'pdf';
DocGenResponse response = toolkit.submitDocGenBatch(request);
System.debug('Batch ID: ' + response.id);
```

### `GenerateDocGenForRecords` with template code

Generates documents for multiple records using a template by ID and template code.

| Parameter | Type | Description |
| - | - | - |
| `recordIds` | `List<String>` | List of Salesforce record IDs to generate docs for. |
| `templateId` | `String` | The ID of the `DocGen_Template__c` record. |
| `templateCode` | `String` | The code identifier for the template. |

Returns:

* `List<DocGenResponse>` - List of responses for each document generation request.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
List<String> recordIds = new List<String>{'001XXXXXXXXXXXXXXX', '001YYYYYYYYYYYYYYY'};
String templateId = 'a0XXXXXXXXXXXXXXX';
String templateCode = 'INVOICE_TEMPLATE';
List<DocGenResponse> responses = toolkit.GenerateDocGenForRecords(recordIds, templateId, templateCode);
for (DocGenResponse response : responses) {
    System.debug('Generated document: ' + response.id);
}
```

### `GenerateDocGenForRecords`

Generates documents for multiple records using a template by ID only.

| Parameter | Type | Description |
| - | - | - |
| `recordIds` | `List<String>` | List of Salesforce record IDs to generate docs for. |
| `templateId` | `String` | The ID of the `DocGen_Template__c` record. |

Returns:

* `List<DocGenResponse>` - List of responses for each document generation request.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
List<String> recordIds = new List<String>{'001XXXXXXXXXXXXXXX'};
String templateId = 'a0XXXXXXXXXXXXXXX';
List<DocGenResponse> responses = toolkit.GenerateDocGenForRecords(recordIds, templateId);
System.debug('Generated ' + responses.size() + ' documents');
```

### `GenerateDocGenForRecords` with folder override

Generates documents for multiple records with an optional folder override.

| Parameter | Type | Description |
| - | - | - |
| `recordIds` | `List<String>` | List of Salesforce record IDs to generate docs for. |
| `templateId` | `String` | The ID of the `DocGen_Template__c` record. Can be `null` if `templateCode` is provided. |
| `templateCode` | `String` | The code identifier for the template. Can be `null` if `templateId` is provided. |
| `folderIdOverride` | `String` | Optional folder ID to override the default destination folder. |

Returns:

* `List<DocGenResponse>` - List of responses for each document generation request.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
List<String> recordIds = new List<String>{'001XXXXXXXXXXXXXXX', '001YYYYYYYYYYYYYYY'};
String templateId = 'a0XXXXXXXXXXXXXXX';
String folderOverride = '123456789';
List<DocGenResponse> responses = toolkit.GenerateDocGenForRecords(recordIds, templateId, null, folderOverride);
for (DocGenResponse response : responses) {
    System.debug('Document generated in folder: ' + response.id);
}
```

## Utility methods

### `generateFileName`

Generates a file name by replacing template variables with actual data values.

| Parameter | Type | Description |
| - | - | - |
| `fileName` | `String` | The template file name containing variables in `{{field.subfield}}` format. |
| `data` | `Map<String, Object>` | Map containing the data to substitute into the file name. |

Returns:

* `String` - The generated file name with variables replaced.

Template variable format:

* Use `{{Object.Field}}` syntax to reference Salesforce object fields.
* Supports nested object references like `{{Account.Name}}`.

Example:

```
String templateFileName = 'Invoice_{{Account.Name}}_{{Opportunity.StageName}}.pdf';
Map<String, Object> data = new Map<String, Object>{
    'Account' => new Map<String, Object>{'Name' => 'Acme Corp'},
    'Opportunity' => new Map<String, Object>{'StageName' => 'Closed Won'}
};
String generatedFileName = DocGenToolkit.generateFileName(templateFileName, data);
// Result: 'Invoice_Acme Corp_Closed Won.pdf'
```

## Batch management methods

### `getDocGenBatch`

Retrieves information about a document generation batch by its ID.

| Parameter | Type | Description |
| - | - | - |
| `batchId` | `String` | The ID of the batch to retrieve info for. |

Returns:

* `DocGenResponse` - The response containing batch status and details.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
String batchId = 'batch_123456789';
DocGenResponse batchInfo = toolkit.getDocGenBatch(batchId);
System.debug('Batch status: ' + batchInfo.status);
System.debug('Total documents: ' + batchInfo.total_count);
```

### `getDocGenBatchByURL`

Retrieves document generation batch information by URL endpoint.

| Parameter | Type | Description |
| - | - | - |
| `endpoint` | `String` | The URL endpoint to retrieve batch information from. |

Returns:

* `DocGenResponse` - The response containing batch information.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
String endpoint = 'https://api.box.com/2.0/document_generation_batches/batch_123456789';
DocGenResponse batchInfo = toolkit.getDocGenBatchByURL(endpoint);
System.debug('Batch status: ' + batchInfo.status);
```

## Template management methods

### `createTemplate` from file ID

Creates a template from a Box file by its ID.

| Parameter | Type | Description |
| - | - | - |
| `fileId` | `String` | The Box file ID to mark as a template. |

Returns:

* `DocGenTemplateResponse` - The response containing template information.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
String fileId = '123456789';
DocGenTemplateResponse templateResponse = toolkit.createTemplate(fileId);
System.debug('Template created with ID: ' + templateResponse.id);
```

### `createTemplate` from request object

Creates a template from a Box file using a custom template request.

| Parameter | Type | Description |
| - | - | - |
| `templateRequest` | `DocGenTemplateRequest` | The request object containing template configuration. |

Returns:

* `DocGenTemplateResponse` - The response containing template information.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
DocGenTemplateRequest request = new DocGenTemplateRequest('123456789');
request.name = 'Invoice Template';
request.description = 'Template for generating invoices';
DocGenTemplateResponse response = toolkit.createTemplate(request);
System.debug('Template created: ' + response.id);
```

### `deleteTemplate`

Deletes a template from Box by its file ID.

| Parameter | Type | Description |
| - | - | - |
| `fileId` | `String` | The Box file ID of the template to delete. |

Returns:

* `DocGenTemplateResponse` - The response confirming the deletion.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
String fileId = '123456789';
DocGenTemplateResponse response = toolkit.deleteTemplate(fileId);
System.debug('Template deleted successfully');
```

### `getJobsForTemplate`

Retrieves all jobs associated with a template record.

| Parameter | Type | Description |
| - | - | - |
| `templateRecordId` | `Id` | The Salesforce ID of the `DocGen_Template__c` record. |

Returns:

* `DocGenResponse` - The response containing job information for the template.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
Id templateRecordId = 'a0XXXXXXXXXXXXXXX';
DocGenResponse jobsResponse = toolkit.getJobsForTemplate(templateRecordId);
System.debug('Found ' + jobsResponse.total_count + ' jobs for template');
```

## Tag management methods

### `getTags`

Retrieves available tags for a template by its ID.

| Parameter | Type | Description |
| - | - | - |
| `templateId` | `String` | The Box template ID to get tags for. |

Returns:

* `DocGenTagsResponse` - The response containing available tags.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
String templateId = 'template_123456789';
DocGenTagsResponse tagsResponse = toolkit.getTags(templateId);
System.debug('Available tags: ' + tagsResponse.tags);
```

### `getTagsByURL`

Retrieves available tags for a template by URL endpoint.

| Parameter | Type | Description |
| - | - | - |
| `endpoint` | `String` | The URL endpoint to retrieve tags from. |

Returns:

* `DocGenTagsResponse` - The response containing available tags.

Example:

```
DocGenToolkit toolkit = new DocGenToolkit();
String endpoint = 'https://api.box.com/2.0/document_generation_templates/template_123456789/tags';
DocGenTagsResponse tagsResponse = toolkit.getTagsByURL(endpoint);
System.debug('Available tags: ' + tagsResponse.tags);
```

## Common usage patterns

### Basic document generation

```
// Initialize the toolkit
DocGenToolkit toolkit = new DocGenToolkit();

// Generate documents for multiple records
List<String> recordIds = new List<String>{'001XXXXXXXXXXXXXXX', '001YYYYYYYYYYYYYYY'};
String templateId = 'a0XXXXXXXXXXXXXXX';
List<DocGenResponse> responses = toolkit.GenerateDocGenForRecords(recordIds, templateId);

// Process the responses
for (DocGenResponse response : responses) {
    if (response.status == 'success') {
        System.debug('Document generated successfully: ' + response.id);
    } else {
        System.debug('Document generation failed: ' + response.error);
    }
}
```

### Template creation and management

```
DocGenToolkit toolkit = new DocGenToolkit();

// Create a template
String fileId = '123456789';
DocGenTemplateResponse templateResponse = toolkit.createTemplate(fileId);

// Get jobs for the template
Id templateRecordId = 'a0XXXXXXXXXXXXXXX';
DocGenResponse jobsResponse = toolkit.getJobsForTemplate(templateRecordId);

// Delete the template when no longer needed
DocGenTemplateResponse deleteResponse = toolkit.deleteTemplate(fileId);
```

### Batch monitoring

```
DocGenToolkit toolkit = new DocGenToolkit();

// Submit a batch
DocGenRequest request = new DocGenRequest();
// ... configure request ...
DocGenResponse response = toolkit.submitDocGenBatch(request);

// Monitor the batch
String batchId = response.id;
DocGenResponse batchInfo = toolkit.getDocGenBatch(batchId);

// Check status
if (batchInfo.status == 'completed') {
    System.debug('Batch completed successfully');
} else if (batchInfo.status == 'failed') {
    System.debug('Batch failed: ' + batchInfo.error);
}
```

## Error handling

When using the `DocGenToolkit`, handle potential errors as shown below:

```
try {
    DocGenToolkit toolkit = new DocGenToolkit();
    List<DocGenResponse> responses = toolkit.GenerateDocGenForRecords(recordIds, templateId);
    for (DocGenResponse response : responses) {
        if (response.error != null) {
            System.debug('Error: ' + response.error);
        }
    }
} catch (Exception e) {
    System.debug('Exception occurred: ' + e.getMessage());
}
```

## Related classes

* `DocGenRequest` - Request object for document generation.
* `DocGenResponse` - Response object containing batch information.
* `DocGenTemplateRequest` - Request object for template creation.
* `DocGenTemplateResponse` - Response object for template operations.
* `DocGenTagsResponse` - Response object for tag operations.
* `DocGen_Template__c` - Custom object for storing template metadata.


# Experience Cloud Toolkit Global Methods
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/experience-cloud-toolkit/experience-cloud-toolkit-global-methods

The `ExperienceCloudToolkit` class provides global methods for managing Box App Users within Salesforce Experience Cloud environments.

The `ExperienceCloudToolkit` class provides global methods for managing Box App Users within Salesforce Experience Cloud environments. These methods support creating, deactivating, and looking up Box App Users linked to Salesforce users.

## Methods

### `createAppUserforCurrentUser()`

Creates a Box App User for the currently logged-in Salesforce user.

Signature:
`Global static BoxUser.Info createAppUserforCurrentUser()`

Returns:

* `BoxUser.Info`. Information about the created or existing Box App User.

Description:
This is a convenience method that calls `createAppUserforUser()` using the current user's ID. If an active App User already exists for the user, it returns the existing user's information.

Example:

```
BoxUser.Info appUser = ExperienceCloudToolkit.createAppUserforCurrentUser();
System.debug('Box User ID: ' + appUser.boxId);
```

### `createAppUserforUser(String userId)`

Creates or reactivates a Box App User for a specific Salesforce user.

Signature:
`Global static BoxUser.Info createAppUserforUser(String userId)`

Parameters:

| **Name** | **Type** | **Description** |
| - | - | - |
| `userId` | `String` | The Salesforce User ID to create a Box App User for. |

Returns:

* `BoxUser.Info`. Information about the created or existing Box App User.

Description:
This method links a platform-only Box App User to the specified Salesforce user ID. The logic is as follows:

1. It searches for an existing Box App User where the `external_app_user_id` matches the Salesforce `userId`.

2. If an active user is found, it returns that user's information.

3. If an inactive user is found, it reactivates the user and returns its information.

4. If no user is found, it creates a new App User with the following properties:
   * `name`: The Salesforce user's name

   * `external_app_user_id`: The Salesforce `userId`

   * `is_platform_access_only`: `true`

   * `status`: `active`

Example:

```
String salesforceUserId = '005xx000001SvWlAAK';
BoxUser.Info appUser = ExperienceCloudToolkit.createAppUserforUser(salesforceUserId);
System.debug('Created Box App User: ' + appUser.name);
```

### `deactivateCurrentUserAccount()`

Deactivates the Box App User account for the current Salesforce user.

Signature:
`Global static Boolean deactivateCurrentUserAccount()`

Returns:

* `Boolean`. Is `true` if deactivation was successful, `false` otherwise.

Description:
This is a convenience method that calls `deactivateUserAccount()` using the current user's ID to set their Box App User status to `inactive`.

Example:

```
Boolean success = ExperienceCloudToolkit.deactivateCurrentUserAccount();
if (success) { 
   System.debug('Account deactivated successfully.');
}
```

### `deactivateUserAccount(String boxUserId)`

Deactivates a specific Box App User account.

Signature:
`Global static Boolean deactivateUserAccount(String boxUserId)`

Parameters:

| **Name** | **Type** | **Description** |
| - | - | - |
| `boxUserId` | `String` | The Box User ID to deactivate. |

Returns:

* `Boolean`. Is `true` if the deactivation is successful (HTTP 200 OK), and `false` otherwise.

Description:
This method sends a request to the Box API to update a user's status to `inactive`. This prevents the user from accessing Box content but does not delete their account.

Example:

```
String boxUserId = '12345678';
Boolean success = ExperienceCloudToolkit.deactivateUserAccount(boxUserId);
if (success) {
    System.debug('Box user deactivated.');
}
```

### `searchForExistingUser(String externalAppUserId)`

Searches for a Box App User by their external ID.

Signature:
`Global static BoxUser.Info searchForExistingUser(String externalAppUserId)`

Parameters:

| **Name** | **Type** | **Description** |
| - | - | - |
| `externalAppUserId` | `String` | The external ID to search for (typically a Salesforce User ID). |

Returns:

* `BoxUser.Info`. Information about the found Box App User.

Throws:

* `ExperienceCloudToolkitException` if no user is found with the specified external ID.

Description:
Queries the Box API to find an App User whose `external_app_user_id` matches the provided value. This is useful for checking if a Salesforce user already has an associated Box App User.

Example:

```
try {
    String sfUserId = UserInfo.getUserId();
    BoxUser.Info existingUser = ExperienceCloudToolkit.searchForExistingUser(sfUserId);
    System.debug('Found existing Box user: ' + existingUser.boxId);
} catch (ExperienceCloudToolkit.ExperienceCloudToolkitException e) {
    System.debug('No existing user found. A new one can be created.');
}
```

## Exceptions

### `ExperienceCloudToolkitException`

A custom exception thrown for failed operations, such as when a user is not found by `searchForExistingUser()`.

## Notes

* All methods authenticate with the Box API using the Service Account token.

* Created App Users are "platform-only" (`is_platform_access_only = true`), meaning they can only access Box through the application.

* The `external_app_user_id` field links Box App Users to Salesforce User IDs.

* API versioning is managed through the `SettingUtils.getAPISetting('ExperienceCloudToolkit')` configuration.


# Flow Actions
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/flow-actions



Salesforce toolkit includes wrappers that allow admins
to invoke the following [methods]. It allows Box for Salesforce
users to build automated solutions, such as folder structure,
using [Salesforce Flows].

## Methods in Salesforce Flows

The list below contains all methods that can be invoked in
[Salesforce Flows].

### Box Sign

* Send Box Sign Request (`sendSignRequests`)

### Box Hubs

* Add Hub Item (`tkAddHubItem`)
* Copy Hub (`tkCopyHub`)
* Create Hub (`tkCreateHub`)
* Create Hub Collaboration (`tkCreateHubCollaboration`)
* Get All Hubs (`tkGetAllHubs`)
* Get Enterprise Hubs (`tkGetEnterpriseHubs`)
* Get Hub by ID (`tkGetHubById`)
* Get Hub Collaborations (`tkGetHubCollaborations`)
* Update Hub (`tkUpdateHub`)
* Update Hub Collaboration (`tkUpdateHubCollaboration`)

### Box AI

* Box AI Ask by Item Id (`askBoxAI`)
* Box AI Extract by Fields (`extractBoxAI`)
* Box AI Extract by Metadata Template (`extractBoxAI`)
* Box AI Extract by SObject Type (`extractBoxAI`)
* Box AI Generate Text by Item Id (`generateBoxAI`)

### Box Notes

* Create a Box Note in a Salesforce record's Box folder or in a specific Box folder (`createBoxNote`)

### Doc Gen

* Create Doc Gen Template (`createDocGenTemplate`)
* Generate Doc Gen For Record (`generateDocGenForRecord`)
* Submit Doc Gen Batch (`submitDocgenBatch`)
* Get Doc Gen Batch Status (`getDocgenBatch`)

### File Box Metadata and actions

* Create Box Metadata by File Id (`tkCreateBoxMetadataByFileId`)
* Delete Box Metadata by File Id (`tkDeleteBoxMetadataByFileId`)
* Get Box Metadata by File Id (`tkGetBoxMetadataByFileId`)
* Update Box Metadata by File Id (`tkUpdateBoxMetadataByFileId`)
* Move File (`tkMoveFile`)
* Get Last Item (`getLastItem`)
* Get Recent Items (`GetRecentItems`)

### Folder Box Metadata and actions

* Create Box Metadata by Folder Id (`tkCreateBoxMetadataByFolderId`)
* Delete Box Metadata by Folder Id (`tkDeleteBoxMetadataByFolderId`)
* Get Box Metadata by Folder Id (`tkGetBoxMetadataByFolderId`)
* Update Box Metadata by Folder Id (`tkUpdateBoxMetadataByFolderId`)

### Folder management

* Create Folder (`tkCreateFolder`)
* Create Folder Association (`tkCreateFolderAssociation`)
* Create Folder For Record ID (`tkCreateFolderForRecordId`)
* Create Folder For Record ID From Template (`tkCreateFolderForRecordIdFromTemplate`)
* Create Object Folder For Record ID (`tkCreateObjectFolderForRecordId`)
* Get Folder Associations By Salesforce Record ID (`tkGetFolderAssociationsByRecordId`)
* Get Folder ID By Record ID (`tkGetFolderIdByRecordId`)
* Get Folder URL (`tkGetFolderUrl`)
* Get Object Folder By Record ID (`tkGetObjectFolderByRecordId`)
* Get Record ID By Folder ID (`tkGetRecordIdByFolderId`)
* Get Root Folder ID (`tkGetRootFolderId`)
* Get URL For Folder (`tkGetUrlForFolder`)
* Move Folder (`tkMoveFolder`)
* Update Folder (`tkUpdateFolder`)
* Get Box Folder Contents by Folder Id (`tkGetFolderContents`)

### Cascade policies

* Create Metadata Cascade Policy (`tkCreateMetadataCascadePolicy`)
* Delete Metadata Cascade Policy (`tkDeleteBoxMetadataByFolderId`)
* Get Metadata Cascade Policies by Folder Id (`tkGetMetadataCascadePoliciesByFolderId`)
* Get Metadata Cascade Policy by Id (`tkGetMetadataCascadePolicyById`)

### Collaboration

* Create Collaboration (`tkCreateCollaboration`)
* Create Collaboration On Record (`tkCreateCollaborationOnRecord`)
* Delete Collaboration (`tkDeleteCollaboration`)
* Edit Collaboration (`tkEditCollaboration`)

### Slack integration

* Create Slack Channel Mapping (`tkCreateSlackChannelMapping`)
* Set Slack Channel Access Management Disabled (`tkSetSlackChannelAccessManagementDisabled`)

### Other / utilities

* Create File From Attachment (`tkCreateFileFromAttachment`)
* Enable Integration Activity (`tkEnableAppActivity`)
* Search (`search`)

[methods]: /guides/tooling/salesforce-toolkit/methods

[Salesforce Flows]: https://help.salesforce.com/s/articleView?id=sf.flow.htm&type=5

<RelatedLinks title="RELATED GUIDES" />


# Push File to Box
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/flow-actions/push-file-to-box



The **Push File to Box** Flow action lets Salesforce admins automatically send
files stored in Salesforce (as `ContentVersion` records) to a designated folder
in Box. You can use it to automate file management workflows between
Salesforce and Box.

## Overview

With the Box for Salesforce integration, you can use Flow Builder to automate
file transfers from Salesforce to Box. The **Push File to Box** action is an
invocable Flow action that:

* Uploads files from Salesforce to Box.
* Associates files with a specific Box folder.
* Supports automation through record-triggered or screen flows.

This is useful for scenarios such as:

* Uploading attachments from Salesforce records into Box automatically.
* Automating document storage for compliance or collaboration.
* Syncing files as part of business workflows.

## Prerequisites

Before you use this action, make sure that:

* Box for Salesforce is [installed and configured][sf-install].
* A Box service account is connected.
* Users are authenticated with Box.
* A Box root folder and folder mapping are configured.
* The connected app is configured as described in the [Box Sign Sync in Salesforce setup guide][sf-connected-app].

## How it works

The **Push File to Box** action takes a Salesforce file and uploads it to
Box. Internally:

1. Salesforce stores files as `ContentVersion` records.
2. The Flow action retrieves the file data.
3. The file is uploaded to a specified Box folder.
4. The file becomes available in Box for collaboration and storage.

The action supports files up to 25 MB and includes built-in retry handling
for rate limits.

## Create a flow using Push File to Box

<Steps>
  <Step title="Create or open the flow">
    1. In Salesforce, navigate to **Setup → Flows**.
    2. Click **New Flow**.
    3. Choose a flow type:
       * **Record-Triggered Flow** (recommended for automation).
       * **Screen Flow** (for user-driven uploads).
  </Step>

  <Step title="Add the Push File to Box action">
    1. In Flow Builder, click **+ Add Element**.
    2. Select **Action**.
    3. Search for **Push File to Box** and select the action.
  </Step>

  <Step title="Configure input parameters">
    Provide the required inputs:

    | Parameter | Required | Description |
    | - | - | - |
    | `Content Version ID` | Yes | The ID of the Salesforce file (`ContentVersion`) you want to upload. |
    | `Box Folder ID` | Yes | The numeric ID of the destination folder in Box (for example, `987654321`). |
    | `File Name` | No | Override the default file name if needed. |
  </Step>

  <Step title="Connect the flow">
    1. Connect the action to your flow logic.
    2. Make sure the flow retrieves or stores the `ContentVersionId` before
       this step.
    3. Save and activate the flow.
  </Step>
</Steps>

## Example use case

A common implementation looks like this:

1. A user uploads a file to a Salesforce record.
2. A record-triggered flow runs.
3. The flow retrieves the file's `ContentVersionId`.
4. The **Push File to Box** action uploads the file to the corresponding
   Box folder.

This ensures all files related to Salesforce records are automatically stored
in Box.

## FAQs

<AccordionGroup>
  <Accordion title="Is there a file size limit for uploads?">
    Yes. Files larger than 25 MB are not supported and will fail to upload.
  </Accordion>

  <Accordion title="What happens if the Box OAuth token is invalid or expired?">
    If the admin OAuth token is missing or expired, the action returns
    nothing. Make sure the Box connection is active and validate results
    using `isSuccess` and `errorMessage` after the action with a **Decision**
    element.
  </Accordion>

  <Accordion title="In what format should the Box Folder ID be?">
    Use the numeric Box folder ID (for example, `987654321`). Using a
    Salesforce record ID or a folder name causes the action to fail.
  </Accordion>

  <Accordion title="Why do I get permission-related errors when uploading files?">
    The action runs under the Box admin (service account). That user must
    have access to the destination folder in Box. If access is missing, the
    upload fails.
  </Accordion>
</AccordionGroup>

[sf-install]: https://support.box.com/hc/en-us/articles/360044195713-Installing-Box-For-Salesforce

[sf-connected-app]: https://support.box.com/hc/en-us/articles/50000961566611-Using-Box-Sign-Sync-in-Salesforce

<RelatedLinks title="RELATED GUIDES" />


# Salesforce Developer Toolkit
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/index



The Box for Salesforce Developer Toolkit allows customers to programmatically
customize the behavior of the Box for Salesforce integration. The Toolkit
consists of several global APEX methods that can be used to trigger and extend
the default behavior. The global methods can update the internal Salesforce
record to Box folder mapping and handle permission management.

<Note>
  This functionality is part of the latest Box for
  [Salesforce package][sf-package].
</Note>

<Warning>
  **What the Toolkit does NOT provide**

  The Toolkit is not a full-featured APEX wrapper for the BOX Content API. If
  this is what you are looking for, have a look at the
  [Box SDK for Salesforce][sf-sdk].
</Warning>

## Authentication

A solution for authentication is to allow API calls to use the service
account credentials.

This means that Salesforce Admins need to restrict access to the Toolkit global
APEX class. As these methods allow direct modification of Box content and
collaborations, Salesforce administrators should take appropriate precautions
by restricting access to the global Toolkit APEX class.

Toolkit methods that take `accessToken` as a parameter can use the service
account credentials by sending `null` for the `accessToken` value.

If a value is passed in `accessToken`, the API call to Box is done with
the access token sent. It is up to the developer to ensure the token being
passed is valid and the user associated with the token has permissions to
perform the requested operation.

[sf-package]: https://support.box.com/hc/en-us/articles/360044195713-Installing-and-Configuring-Box-For-Salesforce

[sf-sdk]: https://github.com/box/box-salesforce-sdk

<RelatedLinks title="RELATED GUIDES" />


# Methods and Operations
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/methods

Reference for Box for Salesforce Developer Toolkit methods and operations.

## Toolkit Details

Class Name: `box.Toolkit`

## Instance Variables

### `mostRecentError`

String to indicate the most recent error that occurred when calling instance
methods.

The presence of this string does not mean the operation did not succeed. It is
possible the error was recoverable; however, the lack of a value in this string
does indicate the operation was successful.

### `Enum CollaborationType`

Enum to indicate the [type of collaboration][collab-type].

Possible values: `EDITOR`, `VIEWER`, `PREVIEWER`, `UPLOADER`, `COOWNER`,
`OWNER`, `PREVIEWERUPLOADER`, or `VIEWERUPLOADER`

## Static Methods

### `deleteServiceUserAssociation`

Method to clear association between Service Account and Box for Salesforce
integration. This can be used to change the service account if an incorrect one
is being used.

Parameters:

* None

Returns:

* `true` if the user's account existed and was deleted.
* `false` if the user's account was not deleted for any reason (including because it didn't exist).

### `deleteUserAssociation`

| Parameter | Type | Description |
| - | - | - |
| `userId` | id | The ID of the user whose credentials are to be cleared. |

Returns:

* `true` if the user's account existed and was deleted.
* `false` if the user's account was not deleted for any reason (including because it didn't exist).

## Instance Methods - Constructors, Destructors

### `box.Toolkit()`

Parameters:

* None

### `commitChanges`

Treat this method as a destructor for the `box.Toolkit()` method.

<Warning>
  This method is critical. It must be called after all folder / collaboration
  operations are complete. Every time. No Exceptions.
</Warning>

Since Salesforce doesn't allow callouts after database updates / inserts /
deletes have occurred, the Toolkit class maintains some collections of objects
to be inserted once all callout operations are complete. If this method is not
called, those objects won't be in the database, and the tables that keep track
of user / record / folder associations will be out of sync and will need some
advanced debugging to fix.

Parameters:

* None

Returns:

* `Void`

### `commitChanges` with platform event

Treat this method as a destructor for the `box.Toolkit()` method.

This method is very similar to the `commitChanges` above. However, it uses
a platform event to commit changes to the database to perform DML statements
in a different transaction and avoid governor limits in some scenarios.

| Parameter | Type | Description |
| - | - | - |
| `usePlatformEvent` | `boolean` | `true` if you're using a platform event. `false` to call the original method. |

Returns:

* `Void`

## Generic Methods

The Box for Salesforce Developer Toolkit provides a global method that accepts
an [HttpRequest][sf-httprequest] object as a parameter and returns an
[HttpResponse][sf-httpresponse] object. This method uses the
authentication details of the Service Account to make callouts to Box's APIs,
allowing you to focus on the business logic of your integration.

### `sendRequest`

| Parameter | Type | Description |
| - | - | - |
| `request` | [HttpRequest][sf-httprequest] | An HttpRequest object with a set endpoint and method. |

Returns:

* An [HttpResponse][sf-httpresponse] object with the response details from calling Box's APIs.
* `Toolkit.BoxApiException` if there is any missing information from the HttpRequest input.
* `null` if there was an issue getting the authentication details for the Service Account. In this case, check `mostRecentError`.

## File Operations

### `createFileFromAttachment`

<Note>
  Available in version 3.46 and above.

  Salesforce has a String length limit of 6 million characters. Due to string
  bloat in the base64 encoding/decoding process, this results in an effective
  file size limit of 4.3 megabytes for synchronous Apex and 8.6 megabytes for
  asynchronous Apex.
</Note>

| Parameter | Type | Description |
| - | - | - |
| `att` | `Attachment` | The attachment to be converted into a File in Box. |
| `fileNameOverride` | `string` | Optional - Name of the new file. If no value is passed in, the name of the attachment is used. |
| `folderIdOverride` | `string` | Optional - Box folder ID to place this attachment in. If no value is passed in, the file will be placed in the folder associated with the record that is the `parentId` of the attachment. If the record-specific folder doesn't exist, it will be created. |
| `accessToken` | `string` | Optional - if `accessToken` is sent, that value is used for the Box API call. Otherwise, the default account credentials are used. |

Returns:

* `string` returned is the ID of the Box file that was created.
* `null` if there was an error. In this case, check `mostRecentError`.

### `pushFileToBox`

Uploads a Salesforce Files `ContentVersion` record to a Box folder.

<Warning>
  The maximum supported file size is 25 MB, or 26,214,400 bytes. Files exceeding this limit are rejected with an error message showing the file name and size.
</Warning>

| Parameter | Type | Required | Description |
| - | - | - | - |
| `cvId` | `id` | Yes | The Salesforce `ContentVersion` ID to upload. |
| `folderId` | `string` | Yes | The Box folder ID where the file will be placed. |

Returns:

* `PartnerSyncResponse` object with the upload details.
* `null` if the upload fails. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* It validates that the `ContentVersion` exists before attempting the upload.
* It checks the file size before upload so unsupported files fail early.
* Box API and rate-limit errors are surfaced through `mostRecentError`.
* Check `mostRecentError` when the method returns `null`.

### `createFileShareLink`

Creates a shared link for a Box file.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | `string` | Yes | The Box file ID to create a shared link for. |

Returns:

* `string` returned is the shared link URL.
* `null` if the shared link is not created. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* It creates the shared link with the default Box permissions.
* Check `mostRecentError` when the method returns `null`.

### `moveFile`

Moves a Box file to a different folder.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | `string` | Yes | Box file ID of the file to move. |
| `destinationFolderId` | `string` | Yes | Box folder ID of the destination folder. |
| `accessToken` | `string` | No | If `accessToken` is sent, that value is used for the Box API call. Otherwise, the default service account credentials are used. |

Returns:

* `File` object with the updated parent folder.
* If the move fails, the returned `File` object can include a `status` value. Check `mostRecentError` for details.

Usage notes:

* If `accessToken` is blank or `null`, the method uses service account credentials.
* Check the returned `File` object's `status` value for operation errors.
* Check `mostRecentError` if the operation fails.

## Folder Operations

### `getRootFolderId`

Parameters:

* None

Returns:

* `string` returned is the Box folder ID of the Salesforce root folder.

### `getObjectFolderByRecordId`

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | Salesforce record ID whose root folder ID you want to get. |

Returns:

* `string` returned is the Box folder ID of the object root folder for the record ID passed in.

### `getFolderUrl`

* This method gets the embed widget URL for a particular record so customers can use their own embed logic if desired.
* This method respects seamless login settings so the URL will automatically log the user in if seamless login is enabled.

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | Salesforce record ID whose root folder ID you want to get. |
| `isMobileContext` | `boolean` | Boolean to indicate whether the URL should be mobile (true) or not (false). |

Returns:

* `string` returned is a URL that points to the folder associated with the Salesforce record ID passed. This URL is for the Box Embed Widget and can be embedded in any Visualforce page.

### `createObjectFolderForRecordId`

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | Salesforce record ID whose root folder ID you want to get. |

Returns:

* `string` returned is the Box folder ID of the root folder that was created.
* If the root folder already existed, the value returned is the Box folder ID of the root folder that already existed.

### `createFolder`

| Parameter | Type | Description |
| - | - | - |
| `folderName` | `string` | Name of the folder to be created. Folder names are subject to some restrictions. <Link href="/reference/post-folders">See here for more details.</Link> |
| `parentFolderId` | `string` | Parent Box folder this folder will be created in. |
| `accessToken` | `string` | Optional - If `accessToken` is sent, that value is used for the Box API call; otherwise, the default service account credentials are used. |

Returns:

* `string` returned is the Box folder ID of the folder that was created.
* `null` is returned if a folder is not created. In this case, check `mostRecentError` for details.

### `createFolderShareLink`

Creates a shared link for a Box folder.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `folderId` | `string` | Yes | The Box folder ID to create a shared link for. |

Returns:

* `string` returned is the shared link URL.
* `null` if the shared link is not created. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* It creates the shared link with the default Box permissions.
* Check `mostRecentError` when the method returns `null`.

### `getFolderContents`

Retrieves files and subfolders from a Box folder.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `folderId` | `string` | Yes | The Box folder ID to retrieve contents from. |
| `accessToken` | `string` | No | If `accessToken` is sent, that value is used for the Box API call. Otherwise, the default service account credentials are used. |

Returns:

* `FolderContents` object containing the files and folders in the Box folder.
* If the request fails, the returned `FolderContents` object can include a `status` value. Check `mostRecentError` for details.

Usage notes:

* If `accessToken` is blank or `null`, the method uses service account credentials.
* The response can include both files and subfolders.
* Check the returned `FolderContents` object's `status` value for operation errors.
* Check `mostRecentError` if the operation fails.

### `createFolderForRecordId`

| Parameter | Type | Required | Description |
| - | - | - | - |
| `recordId` | `id` | Yes | Salesforce record ID that a Box folder will be created for. |
| `folderNameOverride` | `string` | No | By default, the record's name will be the folder name. If you want to name it something else, send that value here. |
| `optCreateRootFolder` | `boolean` | Yes | Boolean to indicate whether to create the object root folder if it doesn't exist. If false is sent and the root folder does not exist, the call will fail. |
| `addCurrentUserCollab` | `boolean` | Yes | Boolean to indicate whether the user running the current transaction should be added as a collaborator on the resulting folder. If `false`, this method behaves the same as the three-argument `createFolderForRecordId` overload. |

Returns:

* `string` returned is the Box folder ID of the folder that was created.
* `null` is returned if a folder is not created. In this case, check `mostRecentError` for details.
* If the Salesforce record was already associated with a Box folder, the existing Box folder ID is returned, and the collaboration is added to that existing folder when `addCurrentUserCollab` is `true`.

### `moveFolder`

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | Box folder ID of the folder to be moved. |
| `newParentFolderId` | `string` | Box folder ID of the folder that will be the new parent folder. |
| `accessToken` | `string` | Optional - If `accessToken` is sent, that value is used for the Box API call. Otherwise, the default service account credentials are used. |

Returns:

* `true` if the folder was moved successfully.
* `false` if the folder was not moved successfully. Check `mostRecentError` for details.

### `getUrlForFolder`

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | ID of the record. |

Returns:

* `pageReference` object with provided URL.
* `null` if the parameters are incorrect.

### `createFolderForRecordIdFromTemplate`

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | Salesforce record ID. |
| `templateFolderId` | `string` | Source folder which should be the template. |
| `folderNameOverride` | `string` | Name override of the new folder. |
| `optCreateRootFolder` | `boolean` | Flag that determines if a root folder is created if it doesn't exist. |

Returns:

* Newly created folder ID.
* `null` if the parameters are incorrect.

## Folder Association Methods

### `getFolderAssociationsByRecordId`

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | Salesforce record ID that the folder mapping entries returned are related to. |

Returns:

* List returned is a collection of all folder mapping entries associated with this record.
* Generally, it will be an empty list if no folder mapping entries exist, but under some circumstances, it could be `null`.

### `getFolderIdByRecordId`

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | Salesforce record ID whose folder ID you want to get. |

Returns:

* `string` returned is the Box folder ID associated with the Salesforce record ID passed in.

### `getFolderIdsByRecordIds`

Retrieves Box folder IDs associated with one or more Salesforce record IDs.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `recordIds` | `List<Id>` | Yes | Salesforce record IDs to look up. |

Returns:

* `Map<Id, String>` where each key is a Salesforce record ID and each value is the associated Box folder ID.
* An empty map if no folder associations exist.

Usage notes:

* This method queries Salesforce folder associations and does not call the Box API.
* It queries the `Record_ID_Indexed__c` field on the `FRUP__c` object.
* It returns only associations where `Box_Folder_ID__c` has a value.
* Use this method to look up multiple record-to-folder associations in one call.

### `getRecordIdByFolderId`

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | Box folder ID. |

Returns:

* `id` returned is the Salesforce record ID associated with the Box folder ID passed in.

### `createFolderAssociation`

| Parameter | Type | Description |
| - | - | - |
| `recordId` | `id` | Salesforce record ID that is being associated with a Box folder. |
| `folderId` | `string` | Box folder ID being associated with a Salesforce record. |

Returns:

* `box__FRUP__c` object - The FRUP object returned will be `null` if there was an error (check `mostRecentError`). Upon calling the `commitChanges` method, this FRUP entry will be inserted into the database. This method ensures consistency with other folder associations by not allowing the same folder to be associated with multiple records or vice versa.

## Collaboration Methods

<Warning>
  Collaborations created by the Box for Salesforce Developer Toolkit will not
  send collaboration emails to collaborators. Only the service account used for
  the Box for Salesforce integration will receive a collaboration email.
</Warning>

### `createCollaboration`

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | Box folder ID to create a collaboration on. |
| `boxUserId` | `string` | Box user ID to be collaborated (either `boxUserId` or `emailAddress` is required, but not both). |
| `emailAddress` | `string` | Email address of the Box user to be collaborated. |
| `collabType` | `box.Toolkit.CollaborationType` | Type of collaboration (see the `CollaborationType` enum definition). |
| `accessToken` | `string` | Optional - If sent, this value is used for authentication for the Box API call; if `null`, the service account credentials are used. |

Returns:

* `string` returned is the ID of the Box collaboration that was created.
* `null` returned if there was an error. In this case, check `mostRecentError`.

### `createCollaborationOnRecord`

| Parameter | Type | Description |
| - | - | - |
| `userId` | `id` | Salesforce user ID to be collaborated. |
| `recordId` | `id` | Salesforce record ID of the record folder to be collaborated on. |
| `collabType` | `box.Toolkit.CollaborationType` | Type of collaboration (see the `CollaborationType` enum definition). |
| `optCreateFolder` | `boolean` | Boolean to indicate whether to create the Box folder associated with the Salesforce record ID if it does not already exist. This also creates the root folder if it did not already exist. If set to `false` and the folder does not already exist, the call will fail. |

Returns:

* `string` returned is the ID of the Box collaboration that was created.
* `null` returned if there was an error. In this case, check `mostRecentError`.

[collab-type]: https://support.box.com/hc/en-us/articles/360044196413-Understanding-Collaborator-Permission-Levels

[sf-httprequest]: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_httprequest.htm

[sf-httpresponse]: https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_restful_http_httpresponse.htm#apex_classes_restful_http_httpresponse

### `editCollaboration`

| Parameter | Type | Description |
| - | - | - |
| `collabId` | `string` | Collaboration ID. |
| `collabType` | `enum` | `Box.Toolkit.CollaborationType` enum. |
| `accessToken` | `string` | Optional - If sent, this value is used for the Box API call; if `null`, the service account credentials are used. |

Returns:

* Boolean based on the transaction success.
* `false` if the parameters are incorrect.

### `deleteCollaboration`

| Parameter | Type | Description |
| - | - | - |
| `collabId` | `string` | Collaboration ID. |
| `accessToken` | `string` | Optional - If sent, this value is used for the Box API call; if `null`, the service account credentials are used. |

Returns:

* Boolean based on the transaction success.
* `false` if the parameters are incorrect.

## Search and Discovery

### `search`

Searches Box content accessible to the service account.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | The search query string. |

Returns:

* `SearchResults` object with matching files and folders.
* `null` if the search fails. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* It searches file names, descriptions, and content accessible to the service account.
* Box returns up to 100 results by default.
* Use `search` with filters when you need pagination or narrower search scope.
* Check `mostRecentError` when the method returns `null`.

### `search` with filters

Searches Box content with filtering, pagination, and scope controls.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `query` | `string` | Yes | The search query string. |
| `scope` | `string` | No | Search scope, such as `user_content` or `enterprise_content`. |
| `trashContent` | `string` | No | Trash filter, such as `trashed_only` or `non_trashed_only`. |
| `limit` | `integer` | No | Number of results to return. The Box API maximum is 200. |
| `offset` | `integer` | No | Starting position for pagination. |
| `ancestorFolderIds` | `List<String>` | No | Box folder IDs to restrict the search to. |
| `contentTypes` | `string` | No | Content type filter, such as `name`, `description`, or `tags`. |

Returns:

* `SearchResults` object with matching files and folders.
* `null` if the search fails. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* Use `scope` to choose between user content and enterprise content.
* The Box API supports up to 200 results per request.
* Use `offset` to paginate through larger result sets.
* Use `ancestorFolderIds` to limit results to specific folder hierarchies.
* Check `mostRecentError` when the method returns `null`.

### `getRecentInteractions`

Retrieves files and folders recently interacted with by the current user.

Parameters:

* None

Returns:

* `RecentItems` object containing recently accessed content.
* `null` if the request fails. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* Results are returned in order of most recent interaction.
* Interactions can include actions such as opening, previewing, downloading, or editing an item.
* Box limits the response to the API default, typically 100 items.
* Check `mostRecentError` when the method returns `null`.

## Enterprise Events

### `getEnterpriseEvents`

Retrieves enterprise events for auditing and monitoring Box activity.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `streamType` | `string` | Yes | Stream type, such as `admin_logs` or `admin_logs_streaming`. |
| `limit` | `integer` | No | Number of events to return. The Box API maximum is 500. |
| `streamPosition` | `string` | No | Stream position marker for pagination or polling. |
| `eventTypes` | `List<String>` | No | Event types to include, such as `ITEM_UPLOAD` or `ITEM_DOWNLOAD`. |
| `createdAfter` | `string` | No | ISO 8601 timestamp for events created after this time. |
| `createdBefore` | `string` | No | ISO 8601 timestamp for events created before this time. |

Returns:

* `EnterpriseEvents` object with event entries and the next stream position.
* `null` if the request fails. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication and requires enterprise admin privileges.
* Use the `streamPosition` from the previous response to continue polling the event stream.
* The Box API supports up to 500 events per request.
* Date filters must use ISO 8601 format, such as `YYYY-MM-DDTHH:MM:SSZ`.
* Check `mostRecentError` when the method returns `null`.

## Metadata

<Info>
  Check the `toolkit.mostRecentError` value for detailed error responses
  for all the methods.
</Info>

### `getMetadataTemplateByName`

Retrieves a metadata template definition by name and scope.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `templateName` | `string` | Yes | The name of the metadata template. |
| `scope` | `string` | Yes | The scope of the metadata template. Value is one of \[`global`, `enterprise`]. |

Returns:

* `MetadataTemplate` object with the template definition.
* `null` if the template is not retrieved. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* Use it to inspect or validate a metadata template before creating or updating metadata values.
* Check `mostRecentError` when the method returns `null`.

### `getBoxMetadataByFileId`

This method calls the <Link href="/reference/get-files-id-metadata-id-id">get metadata instance on file endpoint</Link>.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | `string` | Yes | The ID of the Box file for which you want to retrieve metadata. |
| `scope` | `string` | Yes | The scope of the metadata template. Value is one of \[`global`, `enterprise`]. |
| `template` | `string` | Yes | The name of the metadata template. |

Returns:

* `Metadata` object with the metadata key/value pairs.
* `null` if the metadata is not retrieved. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* The request returns an error if the metadata instance does not exist on the file.
* Check `mostRecentError` when the method returns `null`.

### `createBoxMetadataByFileId`

This method calls the <Link href="/reference/post-files-id-metadata-id-id">create metadata instance on file endpoint</Link>.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | `string` | Yes | The ID of the Box file for which you want to create metadata. |
| `scope` | `string` | Yes | The scope of the metadata template. Value is one of \[`global`, `enterprise`]. |
| `template` | `string` | Yes | The name of the metadata template. |
| `metadataValues` | `Map<String, Object>` | Yes | Key/value pairs that match fields in the metadata template. |

Returns:

* `Metadata` object with the created metadata values.
* `null` if the metadata is not created. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* The method fails if metadata already exists for the specified file, scope, and template. Use `updateBoxMetadataByFileId` to modify existing metadata.
* Metadata keys must match the template field names.
* Check `mostRecentError` when the method returns `null`.

### `updateBoxMetadataByFileId`

This method calls the <Link href="/reference/put-files-id-metadata-id-id">update metadata instance on file endpoint</Link>.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | `string` | Yes | The ID of the Box file for which you want to update metadata. |
| `scope` | `string` | Yes | The scope of the metadata template. Value is one of \[`global`, `enterprise`]. |
| `template` | `string` | Yes | The name of the metadata template. |
| `operations` | `List<Map<String, Object>>` | Yes | JSON Patch operations. Each operation includes values such as `op`, `path`, and `value`. |

Returns:

* `Metadata` object with the updated metadata values.
* `null` if the metadata is not updated. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* The `operations` parameter uses JSON Patch format.
* Each operation should include an `op`, `path`, and, when required by the operation, a `value`.
* Supported operations include `add`, `replace`, `remove`, and `test`.
* Check `mostRecentError` when the method returns `null`.

### `deleteBoxMetadataByFileId`

This method calls the <Link href="/reference/delete-files-id-metadata-id-id">delete metadata instance from file endpoint</Link>.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileId` | `string` | Yes | The ID of the Box file for which you want to delete metadata. |
| `scope` | `string` | Yes | The scope of the metadata template. Value is one of \[`global`, `enterprise`]. |
| `template` | `string` | Yes | The name of the metadata template. |

Returns:

* Boolean based on the transaction success.
* `false` if the metadata is not deleted. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* It deletes the metadata instance from the file. It does not delete the metadata template.
* Check `mostRecentError` when the method returns `false`.

### `getBoxMetadataByFolderId`

This method calls the <Link href="/reference/get-folders-id-metadata-id-id">get metadata instance on folder endpoint</Link>.

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | The ID of the Box folder for which you want to retrieve metadata. |
| `scope` | `string` | The scope of the metadata template. Value is one of `[global, enterprise]`. |
| `template_key` | `string` | The name of the metadata template. |

Returns:

* `FolderMetadata` record associated with this folder, scope, and template key. You can find the custom values in `keyValuePairs` variable of this object.
* `null`, if:
  * the parameters are incorrect,
  * access to the folder is missing,
  * metadata cascade policy is not found.

### `createBoxMetadataByFolderId`

This method calls the <Link href="/reference/post-folders-id-metadata-id-id">create metadata instance on folder</Link> endpoint.

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | ID of the Box folder for which you want to create metadata. |
| `scope` | `string` | Scope of the metadata template. Value is one of \[`global`, `enterprise`]. |
| `template_key` | `string` | Name of the metadata template. |
| `keyValuePairs` | `List<KeyValuePair>` | This class works as a map. Provide key/value pairs as a list, for the attributes to send to Box Metadata. The key/value mappings follow the same pattern as the <Link href="/reference/post-folders-id-metadata-id-id">API</Link>. Number types such as `'3000'` and multi-select values such as `'Customer;Order'` are represented as string inputs in the `value` field, as regular metadata values seen in the code samples. |

Returns:

* Newly created `FolderMetadata` object.
* `null`, if:
  * the parameters are incorrect,
  * access to the folder is missing,
  * metadata cascade policy is not found.

### `updateBoxMetadataByFolderId`

Calls the <Link href="/reference/put-folders-id-metadata-id-id">update metadata instance on folder</Link> endpoint.

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | ID of the Box folder for which you want to update metadata. |
| `scope` | `string` | The scope of the metadata template. Value is one of \[`global`, `enterprise`] |
| `template_key` | `string` | The name of the metadata template. |
| `mdUpdates` | `List<FolderMetadataUpdate>` | Metadata updates. Provide the operation, path, and value. The metadata update records follow the same pattern as the <Link href="/reference/put-folders-id-metadata-id-id">API</Link>. Number types such as `3000` and multi-select values such as `Customer;Order` are represented as string inputs in the `value` field, just as the regular metadata values in the code samples. |

Returns:

* Updated `FolderMetadata` object.
* `null`, if:
  * the parameters are incorrect,
  * access to the folder is missing,
  * metadata cascade policy is not found.

### `deleteBoxMetadataFolderId`

This method calls the <Link href="/reference/delete-folders-id-metadata-id-id">delete metadata instance from folder</Link> endpoint.

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | ID of the Box folder for which you want to delete metadata. |
| `scope` | `string` | The scope of the metadata template. Value is one of \[`global`, `enterprise`] |
| `template_key` | `string` | The name of the metadata template. |

Returns:

* Boolean based on the transaction success.
* `false` is returned if the parameters are incorrect or the metadata is not found.

### `getMetadataCascadePolicyById`

This method calls the <Link href="/reference/get-metadata-cascade-policies-id">get metadata cascade policy from folder</Link>
endpoint. As it requires an ID, you need to call the
`getMetadataCascadePoliciesByFolderId` method first.

| Parameter | Type | Description |
| - | - | - |
| `policyId` | `string` | The ID of the cascade policy you want to retrieve. |

Returns:

* `MetadataCascadePolicy` object retrieved from Box.
* `null`, if:
  * the parameters are incorrect,
  * access to the folder is missing,
  * metadata cascade policy is not found.

### `getMetadataCascadePoliciesByFolderId`

This method retrieves the cascade policies by providing a folder ID and
calling the <Link href="/reference/get-metadata-cascade-policies">get metadata cascade policies</Link> endpoint.

| Parameter | Type | Description | Required |
| - | - | - | - |
| `folderId` | `string` | Specifies for which folder to return the policies. This can't be used on the root folder with ID 0. | Yes |
| `paginationMarker` | `string` | Defines the position marker at which to begin returning results. This is used for marker-based pagination. | No |
| `offset` | `integer` | The offset of the item at which to begin the response. | No |
| `ownerEnterpriseId` | `string` | Enterprise ID for which to find the metadata cascade policies. If not specified, it defaults to the current enterprise. | No |

Returns:

* List of `MetadataCascadePolicy` objects retrieved from Box.
* `null`, if:
  * the parameters are incorrect,
  * access to the folder is missing,
  * metadata cascade policy is not found.

### `createMetadataCascadePolicy`

This method creates cascade policies by providing a Box folder ID, scope,
template key, and by calling the <Link href="/reference/post-metadata-cascade-policies">post metadata cascade policies</Link> endpoint.

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | ID of the Box folder for which you want to create the metadata cascade policy. |
| `scope` | `string` | The scope of the metadata cascade policy. Value is one of \[`global`, `enterprise`] |
| `template_key` | `string` | The name of the template key. |

Returns:

* Newly generated `MetadataCascadePolicy`.
* `null`, if:
  * the parameters are incorrect,
  * access to the folder is missing,
  * metadata cascade policy details are not found.

### `deleteMetadataCascadePolicy`

This method deletes the cascade policies by providing a cascade policy
ID and calling the <Link href="/reference/delete-metadata-cascade-policies-id">delete metadata cascade policies ID</Link> endpoint.

| Parameter | Type | Description |
| - | - | - |
| `policyId` | `string` | The ID of the cascade policy you want to delete. |

Returns:

* Boolean based on the transaction success.
* `false` is returned if parameters are incorrect, access to the folder is missing, or the metadata cascade policy is not found.

### `enableAppActivity`

This method enables the given folder for App Activities by applying
metadata on the folder and cascading it down.

| Parameter | Type | Description |
| - | - | - |
| `folderId` | `string` | The ID of the Box folder for which you want to enable App Activities. |

Returns:

* Boolean based on the transaction success.
* `false` in case of incorrect parameters.

## Salesforce and Slack

### `getIntegrationMappings`

This toolkit method calls the <Link href="/reference/get-integration-mappings-slack">get integration mappings</Link> endpoint to get the
existing mappings.

| Parameter | Type | Description |
| - | - | - |
| `integration` | String | `Slack` is currently the only supported value. |
| `partnerItemId` | String | ID of the mapped item on the provided integration side. Example: a Slack channel ID. |

Returns:

* A list of `IntegrationMapping` objects.
* `null` is returned if the parameters are incorrect, the access is missing, or the integration mapping is not found.

### `createIntegrationMapping`

This toolkit method calls the <Link href="/reference/post-integration-mappings-slack">create integration mapping</Link> endpoint to create
the mappings.

<Note>
  When you map to a Slack channel,
  `access_management_disabled` is set to `FALSE` by default.
  This causes an automatic removal of collaborators that are not part
  of the Slack channel member list. Depending on how your organization
  sets up sharing in Box, we recommend that you either set
  `access_management_disabled` to `TRUE` by using the
  `setSlackChannelAccessManagementDisabled` method, or use [groups][12].
  This ensures no users are removed, regardless of Slack settings.
  Collaborations are added or removed from Slack when a file is uploaded
  to a Slack channel.
</Note>

| Parameter | Type | Description |
| - | - | - |
| `integration` | String | `Slack` is currently the only supported value. |
| `mapping` | `IntegrationMapping` | Apex defined type `IntegrationMapping`. |

Returns:

* Boolean based on the transaction success.

### `deleteIntegrationMapping`

This toolkit method calls the <Link href="/reference/delete-integration-mappings-slack-id">delete integration mappings</Link> endpoint to
delete a mapping.

| Parameter | Type | Description |
| - | - | - |
| `integration` | String | `Slack` is currently the only supported value. |
| `integrationMappingId` | String | Retrieved from `getIntegrationMappings`. |

Returns:

* Boolean based on the transaction success.

### `mapSfdcRecordToSlackChannel`

This toolkit method uses the above integration mapping methods and
provides a wrapper with four different use cases:

1. If a mapping does not exist in Salesforce or Slack, it creates a folder under the Box for Salesforce folder structure, and an integration mapping to link it with the Slack channel.
2. If a mapping only exists from Salesforce, it continues to use the folder and does not change the location. It creates an integration mapping to link it with the Slack channel.
3. If a mapping only exists from Slack, it continues to use the folder and creates an FRUP record for the Salesforce record to use the existing folder. This folder is likely to be outside of the Salesforce root folder.
4. If Salesforce and Slack have existing mappings but are not related to each other, it throws an error through `Toolkit.mostRecentError` or within a flow action, stating that the mappings already exist.

This method/invocable is used in a flow template provided in the Box
for Salesforce package `Create Box Folder/Slack Channel Mapping`.

<Note>
  When you map to a Slack channel,
  `access_management_disabled` is set to `FALSE` by default.
  This causes an automatic removal of collaborators that are not part
  of the Slack channel member list. Depending on how your organization
  sets up sharing in Box, we recommend that you either set
  `access_management_disabled` to `TRUE` by using the
  `setSlackChannelAccessManagementDisabled` method, or use [groups][12].
  This ensures no users are removed, regardless of Slack settings.
  Collaborations are added or removed from Slack when a file is uploaded
  to a Slack channel.
</Note>

| Parameter | Type | Description |
| - | - | - |
| `recordId` | ID | Salesforce record ID. |
| `slackChannelId` | String | The Slack channel ID. |
| `slackWorkspaceOrOrgId` | String | If Box for Slack is installed org-wide, provide the Org ID (for example, E1234567) or the Workspace ID (for example, T5555555). |

Returns:

* Boolean based on the transaction success.

### `setSlackChannelAccessManagementDisabled`

This toolkit method calls the <Link href="/reference/put-integration-mappings-slack-id">put integration mappings</Link> endpoint to update
the access management deactivated setting.

This method/invocable is used in a flow template provided in the Box
for Salesforce package `Create Box Folder/Slack Channel Mapping`.

| Parameter | Type | Description |
| - | - | - |
| `channelId` | String | The Slack channel ID. |
| `disabled` | Boolean | Indicates whether a channel member's access to the underlying Box item is automatically managed. Depending on the type of the channel, access is managed through creating collaborations or shared links. |

Returns:

* Boolean based on the transaction success.

## Box Sign

### `sendSignRequests`

This method calls the <Link href="/reference/post-sign-requests">create sign request</Link> endpoint to send documents for signature.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `requests` | `List<BoxSignRequest>` | List of Box Sign Request objects containing signers, files, and configuration for the signature request. |

**Returns:**

List of `BoxSignResponse` objects, one for each request processed. Each response contains the sign request ID, status, and any error information.

`BoxSignResponse` returns error details, if:

* the parameters are incorrect,
* access to the files is missing,
* file upload fails,
* Box Sign API returns an error.

## Document Generation

### `submitDocGenBatch`

Submits a batch of documents to generate from a Box document generation template.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `templateFileId` | `string` | Yes | The Box file ID of the document generation template. |
| `documents` | `List<Map<String, Object>>` | Yes | Document configurations and merge data to use for generation. |

Returns:

* `DocGenBatch` object with the batch ID and status.
* `null` if the batch is not submitted. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* Each document configuration should include the generated file name and the merge data for the template, such as `fileName` and `data` values.
* Document generation runs asynchronously. Use `getDocGenBatch` to check the batch status.
* Check `mostRecentError` when the method returns `null`.

### `getDocGenBatch`

Retrieves the status and details of a document generation batch.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `batchId` | `string` | Yes | The batch ID returned from `submitDocGenBatch`. |

Returns:

* `DocGenBatch` object with the batch status and generated file details.
* `null` if the batch is not retrieved. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* Poll this method periodically to monitor batch progress.
* Batch statuses include `pending`, `processing`, `completed`, and `failed`.
* Generated file details are available after the batch is complete.
* Check `mostRecentError` when the method returns `null`.

## File Requests

### `copyFileRequest`

Creates a copy of an existing file request with customizable properties.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileRequestId` | `string` | Yes | The ID of the file request to copy. |
| `folderId` | `string` | Yes | The destination Box folder ID for uploaded files. |
| `title` | `string` | No | Custom title for the new file request. |
| `description` | `string` | No | Custom description for the new file request. |
| `status` | `string` | No | File request status, such as `active` or `inactive`. |
| `isDescriptionRequired` | `boolean` | No | Whether submitters must provide a description. |
| `isEmailRequired` | `boolean` | No | Whether submitters must provide an email address. |

Returns:

* `FileRequest` object with the new file request details.
* `null` if the file request is not copied. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* If optional parameters are `null`, the new file request inherits those values from the source file request.
* Use `active` to enable the copied file request immediately.
* Check `mostRecentError` when the method returns `null`.

### `copyFileRequest` with default settings

Creates a copy of an existing file request using the source file request settings and a new destination folder.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `fileRequestId` | `string` | Yes | The ID of the file request to copy. |
| `folderId` | `string` | Yes | The destination Box folder ID for uploaded files. |

Returns:

* `FileRequest` object with the new file request details.
* `null` if the file request is not copied. In this case, check `mostRecentError`.

Usage notes:

* This method uses service account authentication.
* The copied file request inherits settings from the source file request and uses the folder ID you provide.
* Use this method when you only need to change the destination folder.
* Check `mostRecentError` when the method returns `null`.

## Box Hubs

### Manage Box Hubs

#### `getHubById`

This method calls the <Link href="/reference/v2025.0/get-hubs-id">get hub by ID</Link> endpoint to retrieve a specific hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `hubId` | `string` | The ID of the hub to retrieve. |

**Returns:**

* Hub object containing the hub details and metadata.
* `HubsToolkitException` if:
  * the hub ID is blank or null,
  * access to the hub is missing,
  * the hub is not found.

#### `getAllHubs`

This method calls the <Link href="/reference/v2025.0/get-hubs">get all hubs</Link> endpoint to retrieve a list of all hubs.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `limitCount` | `integer` | Optional - maximum number of hubs to return. |
| `marker` | `string` | Optional - pagination marker for retrieving additional results. |

**Returns:**

* `HubsList` object containing the list of hubs and pagination information.
* `HubsToolkitException` if:
  * access to hubs is missing,
  * API request fails.

#### `getEnterpriseHubs`

This method calls the <Link href="/reference/v2025.0/get-enterprise-hubs">get enterprise hubs</Link> endpoint to retrieve enterprise-level hubs.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `limitCount` | `integer` | Optional - maximum number of hubs to return. |
| `marker` | `string` | Optional - pagination marker for retrieving additional results. |

**Returns:**

* `HubsList` object containing the list of enterprise hubs and pagination information.
* `HubsToolkitException` if:
  * access to enterprise hubs is missing,
  * API request fails.

#### `createHub`

This method calls the <Link href="/reference/v2025.0/post-hubs">create hub endpoint</Link> to create a new hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `title` | `string` | Required - title of the hub (maximum 50 characters). |
| `description` | `string` | Optional - description of the hub. |

**Returns:**

* Hub object containing the newly created hub details.
* `HubsToolkitException` if:
  * the title is blank or null,
  * the title exceeds 50 characters,
  * access to create hubs is missing,
  * API request fails.

#### `updateHub`

This method calls the <Link href="/reference/v2025.0/put-hubs-id">update hub endpoint</Link> to modify an existing hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `hubId` | `string` | Required - the ID of the hub to update. |
| `updateRequest` | `HubUpdateRequest` | Required - object containing the fields to update. |

**Returns:**

* Hub object containing the updated hub details.
* `HubsToolkitException` if:
  * the hub ID is blank or null,
  * the update request is null,
  * the title exceeds 50 characters,
  * access to the hub is missing,
  * API request fails.

#### `copyHub`

This method calls the <Link href="/reference/v2025.0/post-hubs-id-copy">copy hub endpoint</Link> to create a copy of an existing hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `hubId` | `string` | Required - the ID of the hub to copy. |
| `title` | `string` | Optional - title for the copied hub (maximum 50 characters). |
| `description` | `string` | Optional - description for the copied hub. |

**Returns:**

* Hub object containing the newly created copied hub details.
* `HubsToolkitException` if:
  * the hub ID is blank or null,
  * the title exceeds 50 characters,
  * access to the source hub is missing,
  * API request fails.

### Box Hub Collaborations

#### `createUserCollaboration`

This method calls the <Link href="/reference/v2025.0/post-hub-collaborations">create hub collaboration</Link> endpoint to add a user to a hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `hubId` | `string` | Required - the ID of the hub. |
| `userId` | `string` | Required - the ID of the user to add. |
| `role` | `string` | Required - the role for the user in the hub. |

**Returns:**

* `HubCollaboration` object containing the collaboration details.
* `HubsToolkitException` if:
  * the hub ID is blank or null,
  * the user ID is blank or null,
  * the role is blank or null,
  * access to the hub is missing,
  * API request fails.

#### `createHubCollaboration`

This method calls the <Link href="/reference/v2025.0/post-hub-collaborations">create hub collaboration</Link> endpoint to add a collaboration to a hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `request` | `HubCollaborationRequest` | Required - object containing the collaboration details including hub reference and accessible by information. |

**Returns:**

* `HubCollaboration` object containing the collaboration details.
* `HubsToolkitException` if:
  * the collaboration request is null,
  * the hub reference with ID is missing,
  * access to the hub is missing,
  * API request fails.

#### `getHubCollaborations`

This method calls the <Link href="/reference/v2025.0/get-hub-collaborations">get hub collaborations</Link> endpoint to retrieve collaborations for a hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `hubId` | `string` | Required - the ID of the hub. |
| `limitCount` | `integer` | Optional - maximum number of collaborations to return. |
| `marker` | `string` | Optional - pagination marker for retrieving additional results. |

**Returns:**

* `HubCollaborationsList` object containing the list of collaborations and pagination information.
* `HubsToolkitException` if:
  * the hub ID is blank or null,
  * access to the hub is missing,
  * API request fails.

#### `updateHubCollaboration`

This method calls the <Link href="/reference/v2025.0/put-hub-collaborations-id">update hub collaboration</Link> endpoint to modify a collaboration.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `collaborationId` | `string` | Required - the ID of the collaboration to update. |
| `role` | `string` | Required - the new role for the collaboration. |

**Returns:**

* `HubCollaboration` object containing the updated collaboration details.
* `HubsToolkitException` if:
  * the collaboration ID is blank or null,
  * the role is blank or null,
  * access to the collaboration is missing,
  * API request fails.

### Box Hub Items

#### `addHubItem`

This method calls the <Link href="/reference/v2025.0/post-hubs-id-manage-items">manage hub items</Link> endpoint to add an item to a hub.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `hubId` | `string` | Required - the ID of the hub. |
| `itemId` | `string` | Required - the ID of the item to add. |
| `itemType` | `string` | Required - the type of the item (for example, `file` or `folder`). |

**Returns:**

* `HubItemsManageResponse` object containing the result of the item management operation.
* `HubsToolkitException` if:
  * the hub ID is blank or null,
  * the item ID is blank or null,
  * the item type is blank or null,
  * access to the hub is missing,
  * API request fails.

## Box Notes

### `createBoxNote`

This method creates a Box Note in a Salesforce record's Box folder or in a specific Box folder.

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `content` | `string` | Initial body of the note. If blank or null, the note is created with an empty body. |
| `contentFormat` | `string` | Format of content. If blank or `null`, defaults to `markdown`. `markdown` is the currently supported value. |
| `recordOrFolderId` | `string` | Either a Box folder ID (numeric) or a Salesforce record ID. When a Salesforce record ID is passed, the associated Box folder is used, or is created if it does not exist. |
| `name` | `string` | Name of the Box Note to create. Box appends the ".boxnote" extension automatically. |

Returns:

* The Box file ID of the Box Note that is created.
* `null` if the note is not created. In this case, check `mostRecentError` for error messages.

Usage notes:

* This method uses standard-user authentication for the callout to Box, and restores the previous authentication mode after the call completes, even if the call fails.
* `recordOrFolderId` accepts either a Box folder ID or a Salesforce record ID:
  * If the value is fully numeric it is treated as a Box folder ID and used as-is. Otherwise it is parsed as a Salesforce record ID. If that record already has an associated Box folder, the note is created there. If not, the root folder and the record folder are created automatically before the note is created.
  * If the value is neither numeric nor a valid Salesforce ID, the method returns `null` and `mostRecentError` is set to `Invalid recordOrFolderId provided: <value>`.
* If `name` or `recordOrFolderId` is blank, the method returns `null` without calling Box and `mostRecentError` is set to `Unable to create note: name or recordOrFolderId is not set.`
* Blank `content` is normalized to an empty string so the note is created rather than rejected.
* Blank `contentFormat` is normalized to `markdown`.
* Check `mostRecentError` when the method returns `null`.

## Debugging

### `setEnhancedDebugging`

Enables or disables enhanced debug logging for the current Toolkit instance.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `enabled` | `boolean` | Yes | `true` to enable enhanced debugging; `false` to disable. |

Returns:

* `Void`

Usage notes:

* Enhanced debugging applies only to the current Toolkit instance.
* When enabled, enhanced debugging logs additional HTTP request and response details.
* Use enhanced debugging for troubleshooting, and disable it in production to avoid unnecessary logging.
* The setting does not persist across transactions.

### `isEnhancedDebuggingEnabled`

Checks whether enhanced debugging is enabled for the current Toolkit instance.

Parameters:

* None

Returns:

* `true` if enhanced debugging is enabled.
* `false` if enhanced debugging is disabled.

Usage notes:

* This method has no side effects.
* Use it to conditionally run debug-only logic.
* The returned value reflects the setting applied by `setEnhancedDebugging`.

[12]: https://support.box.com/hc/articles/360043694554-Creating-and-Managing-Groups

<RelatedLinks title="RELATED GUIDES" />


# Code Samples
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/samples



## Generic Method

The following code will create metadata on a Box folder in Salesforce using the
generic Toolkit method:

```java Apex theme={null}
// Instantiate the Toolkit object
box.Toolkit toolkit = new box.Toolkit();

// Get the Salesforce record id associated with a Box folder
String recordId = toolkit.getRecordIdByFolderId('{some folder id}');

// Construct an object containing all the metadata you want
Map<String, Object> metadata = new Map<String, Object>{
    'salesforce_id' => recordId,
    'salesforce_url' => System.URL.getSalesforceBaseUrl().toExternalForm() + '/' + recordId,
    'salesforce_user_name' => UserInfo.getName(),
    'salesforce_user_email' => UserInfo.getUserEmail()
};

// Specify the Box API endpoint to call
String endpoint = 'https://api.box.com/2.0/folders/' + '{some folder id}' + '/metadata/global/properties';

// Create a new HttpRequest object and set appropriate values
HttpRequest request = new HttpRequest();
request.setMethod('POST');
request.setEndpoint(endpoint);
request.setBody(JSON.serialize(metadata));
request.setHeader('content-type', 'application/json');

// Send the HttpRequest through the generic Toolkit method, which will handle the authentication details
HttpResponse response = toolkit.sendRequest(request);
```

## New Folder Association

The following code will create a folder for a specific Salesforce record Id:

```java Apex theme={null}
// Instantiate the Toolkit object
box.Toolkit boxToolkit = new box.Toolkit();
// Create a folder and associate it with an account
Id accountId = '001j000000FBozw';
String accountFolderId = boxToolkit.createFolderForRecordId(accountId, null, true);
system.debug('new item folder id: ' + accountFolderId);

// If there was an error, accountFolderId will be null. mostRecentError will contain the error message
if(accountFolderId == null) {
system.debug('most recent error: ' + boxToolkit.mostRecentError);
}

// ALWAYS call this method when finished.Since salesforce doesn't allow http callouts after dml operations, we need to commit the pending database inserts/updates or we will lose the associations created
boxToolkit.commitChanges();
```

## Folder Templates

The following code will create a folder for a record, create subfolders (folder
template), and collaborate the current user:

```java Apex theme={null}
// Instantiate the Toolkit object
box.Toolkit boxToolkit = new box.Toolkit();

// Create a folder and associate it with an account
Id accountId = '001j000000FBozz';
String accountFolderId = boxToolkit.createFolderForRecordId(accountId, null, true);
system.debug('new item folder id: ' + accountFolderId);

// Create two sub-folders in the newly created account folder
String legalFolderId = boxToolkit.createFolder('Legal Documents', accountFolderId, null);
system.debug('Legal Folder id: ' + legalFolderId);
String pictureFolderId = boxToolkit.createFolder('Pictures', accountFolderId, null);
system.debug('Picture Folder id: ' + pictureFolderId);

// Collaborate the current user on the account folder. Note that we're sending false for the optCreateFolder param that shouldn't actually matter since the folder(s) already exists
Id userId = UserInfo.getUserId();
box.Toolkit.CollaborationType collabType = box.Toolkit.CollaborationType.EDITOR;
String collabId = boxToolkit.createCollaborationOnRecord(userId, accountId, collabType, false);
system.debug('new collaboration id: ' + collabId);

// ALWAYS call this method when finished. Since salesforce doesn't allow http callouts after dml operations, we need to commit the pending database inserts/updates or we will lose the associations created
boxToolkit.commitChanges();
```

## Metadata

The following code will get, add, delete, and update Box folder metadata and
cascade policies.

```java Apex theme={null}
// Get metadata & attributes types
Box.toolkit tk = new Box.Toolkit();
Box.MetadataTemplate mdt = tk.getMetadataTemplateByName('enterprise',
'testtemplate');
System.debug(mdt);
System.debug(mdt.getAttributeTypes()); //get Map<String, String> of values and types.

// Get Metadata
Box.Toolkit tk = new Box.Toolkit();
Box.FolderMetadata fmd = tk.getBoxMetadataByFolderId('193488737189', 'enterprise',
'testTemplate');
System.debug(tk.mostRecentError);
System.debug(fmd);

// Create Metadata
Box.KeyValuePair kvp = new Box.KeyValuePair();
kvp.key = 'recordName';
kvp.value = 'Account Test Name';
Box.KeyValuePair kvp2 = new Box.KeyValuePair();
kvp2.key = 'recordUrl';
kvp2.value = 'https://speed-nosoftware-3605-dev-
ed.scratch.lightning.force.com/lightning/r/Account/001DR00001PsY7YYAV/view';
List<Box.KeyValuePair> kvps = new List<Box.KeyValuePair>();
kvps.add(kvp);
kvps.add(kvp2);
Box.Toolkit tk = new Box.Toolkit();
Box.FolderMetadata newfmd = tk.createBoxMetadataByFolderId('193488737189', 'enterprise',
'testTemplate', kvps);
System.debug(tk.mostRecentError);
System.debug(newfmd);

// Update Metadata
List<Box.FolderMetadataUpdate> updates = new List<Box.FolderMetadataUpdate>();
Box.FolderMetadataUpdate up1 = new Box.FolderMetadataUpdate();
Box.FolderMetadataUpdate up2 = new Box.FolderMetadataUpdate();
up1.op = 'replace';
up1.path = '/recordName';
up1.value = 'Account Name Test 2';
updates.add(up1);
up2.op = 'replace';
up2.path = '/recordUrl';
up2.value = 'https://speed-nosoftware-2356-dev-
ed.scratch.lightning.force.com/lightning/r/Account/001DR00001PsY7YYAV/view';
updates.add(up2);
Box.Toolkit tk = new Box.Toolkit();
Box.FolderMetadata fmd = tk.UpdateBoxMetadataByFolderId('193488737189', 'global',
'lobSalesforceRecord', updates);
System.debug(fmd);

// Delete Metadata
Box.Toolkit tk = new Box.Toolkit();
Boolean fmd = tk.deleteBoxMetadataByFolderId('193488737189', 'global',
'lobSalesforceRecord');
System.debug(tk.mostRecentError);
System.debug(fmd);

// Get Cascade Policy List
Box.Toolkit tk = new Box.Toolkit();
List<Box.MetadataCascadePolicy> mcp =
tk.getMetadataCascadePoliciesByFolderId('193488737189', null, 0, null);
System.debug(mcp);
System.debug(tk.mostRecentError);

// Get Cascade Policy
Box.Toolkit tk = new Box.Toolkit();
Box.MetadataCascadePolicy mcp =
tk.getMetadataCascadePolicyById('MTkzNDg4NzM3MTg5I2cjbG9iU2FsZXNmb3JjZVJlY29yZC0wMTIwMTI0ZC03YWUxLTQzNjItYjdlMC05Y2RiYzhkMzIzZjM');
System.debug(mcp);
System.debug(tk.mostRecentError);

// Create Cascade Policy
Box.Toolkit tk = new Box.Toolkit();
Box.MetadataCascadePolicy mcp = tk.createMetadataCascadePolicy('193488737189', 'global',
'lobSalesforceRecord');
System.debug(mcp);
System.debug(tk.mostRecentError);

// Delete Cascade Policy
Box.Toolkit tk = new Box.Toolkit();
Boolean mcp =
tk.deleteMetadataCascadePolicyById('MTkzNDg4NzM3MTg5I2cjbG9iU2FsZXNmb3JjZVJlY29yZC0wMTIwMTI0ZC03YWUxLTQzNjItYjdlMC05Y2RiYzhkMzIzZjM');
System.debug(mcp);
System.debug(tk.mostRecentError);
```

More examples:

```java Apex theme={null}
// Get metadata example 1
Box.toolkit tk = new Box.Toolkit();
Box.FolderMetadata fmt = tk.getBoxMetadataByFolderId('205776356105', 'enterprise',
'testTemplate');
for(KeyValuePair kvp : fmt.keyValuePairs){
System.debug(kvp);
}
// Get metadata example 2
Box.toolkit tk = new Box.Toolkit();
System.debug(tk.getBoxMetadataByFolderId('205776356105', 'global',
'lobSalesforceRecord'));
```

```java Apex theme={null}
// Create metadata
Box.toolkit tk = new Box.Toolkit();
List<Box.KeyValuePair> kvps = new List<Box.KeyValuePair>();
Box.KeyValuePair kvp1 = new Box.KeyValuePair();
kvp1.key = 'name';
kvp1.value = 'test';
kvps.add(kvp1);
Box.KeyValuePair kvp2 = new Box.KeyValuePair();
kvp2.key = 'revenue';
kvp2.value = '5000';
kvps.add(kvp2);
Box.KeyValuePair kvp3 = new Box.KeyValuePair();
kvp3.key = 'typeMulti';
kvp3.value = 'Customer;Other';
kvps.add(kvp3);
System.debug(tk.createBoxMetadataByFolderId('205776356105', 'enterprise',
'testtemplate', kvps));
System.debug(tk.mostRecentError);
```

```java Apex theme={null}
// Update Metadata
Box.toolkit tk = new Box.Toolkit();
System.debug(tk.getBoxMetadataByFolderId('205776356105', 'enterprise',
'mitchtemplate'));
List<Box.FolderMetadataUpdate> fmus = new List<Box.FolderMetadataUpdate>();
Box.FolderMetadataUpdate fmu = new Box.FolderMetadataUpdate();
fmu.op = 'replace';
fmu.path = '/name';
fmu.value = 'Test 2';
fmus.add(fmu);
Box.FolderMetadataUpdate fmu2 = new Box.FolderMetadataUpdate();
fmu2.op = 'replace';
fmu2.path = '/revenue';
fmu2.value = '3000';
fmus.add(fmu2);
Box.FolderMetadataUpdate fmu3 = new Box.FolderMetadataUpdate();
fmu3.op = 'add';
fmu3.path = '/typeMulti';
fmu3.value = 'Customer';
fmus.add(fmu3);
System.debug(tk.updateBoxMetadataByFolderId('205776356105', 'enterprise',
'testTemplate', fmus));
System.debug(tk.mostRecentError);
```

## Create a sign request

The following code creates a Box Sign request in Salesforce.

```java Apex theme={null}
//Send Sign Request
Box.BoxSignRequest request = new Box.BoxSignRequest();
Box.Signer signer = new Box.Signer();
signer.role = 'signer';
signer.email = 'test@test.com';
request.signers = new List<Box.Signer>{ signer };
Box.File srcFile = new Box.File();
srcFile.id = '1947563411908';
request.source_files = new List<Box.File>{ srcFile };
request.recordId = '0017z00001IdXIHAA3';
request.subject = 'Test Subject';
request.message = 'Test Message';
request.send_reminders = false;
List<Box.BoxSignResponse> responses = Box.BoxSignService.sendSignRequests(new List<Box.BoxSignRequest>{ request });
System.debug(responses[0]);
```

## Get Box Hubs

The following code retrieves Box Hubs.

```java Apex theme={null}
//Get All Hubs
Box.HubsToolkit tk = new Box.HubsToolkit();
Box.HubsList hubsList = tk.getAllHubs();
for(Box.Hub hub : hubsList.entries){
//process hubs
}
//Get Hub by Id
Box.Hub hub = tk.getHubById('106600628');
//processing single Hub by using hub.title, hub.id, etc.
```

<RelatedLinks title="RELATED GUIDES" />


# UI Elements in Salesforce
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/ui-elements



The Box for Salesforce managed package offers the following
<Link href="/guides/embed/ui-elements">UI Elements</Link> as Lightning Components: <Link href="/guides/embed/ui-elements/picker">content picker</Link>,
<Link href="/guides/embed/ui-elements/explorer">explorer</Link>, <Link href="/guides/embed/ui-elements/preview">preview</Link>, and <Link href="/guides/embed/ui-elements/uploader">uploader</Link>. You can use them on
Lightning Pages, or in Flows.

## Content picker

<Link href="/guides/embed/ui-elements/picker/#options">Options</Link> available in picker with Box for Salesforce are:

* `folderId` - if the lightning component is on a record page, it defaults to the record folder
* `chooseButtonLabel`
* `cancelButtonLabel`
* `canSetShareAccess`
* `canCreateNewFolder`
* `canUpload`
* `maxSelectable`

## Content explorer

<Link href="/guides/embed/ui-elements/explorer/#options">Options</Link> available in explorer with Box for Salesforce are:

* `folderId` - if the lightning component is on a record page, it defaults to the record folder
* `canSetShareAccess`
* `canCreateNewFolder`
* `canUpload`
* `canPreview`
* `canDownload`
* `canDelete`
* `canRename`
* `canShare`

## Content preview

<Link href="/guides/embed/ui-elements/preview/#options">Options</Link> available in preview with Box for Salesforce are:

* `fileId` (<Link href="/guides/files/get">find your file ID</Link>)
* **File Id API Field Name** - Salesforce specific; on a record page, you can use an API field name that holds the file ID to be displayed

## Content uploader

<Link href="/guides/embed/ui-elements/uploader/#options">Options</Link> available in uploader with Box for Salesforce are:

* `folderId` - if the lightning component is on a record page, it defaults to the record folder
* `fileLimit`

<RelatedLinks title="RELATED GUIDES" />


# Wiring the Box file picker to a custom invocable
Source: https://developer.box.com/guides/tooling/salesforce-toolkit/wiring-the-box-file-picker-to-a-custom-invocable



Add the Box File Picker to your own Agentforce action so users pick a Box file in the action input instead of pasting file IDs. Two packaged pieces make it work:

* **`FileSelection`** — global Apex type with `selectedFileId` / `selectedFileName`. The value the picker returns.
* **`boxFileSelection`** — Lightning Type that renders the `boxFilePicker` UI (Recent Items / Browse Box Files / Current Record Folder).

Both ship in the package — you don't build them.

## Namespace (subscriber orgs)

Everything is under the `boxagents` namespace. In a subscriber org, reference packaged components with the prefix — the bare names won't compile:

| **Component** | **In a subscriber org** |
| - | - |
| Apex type | `boxagents.FileSelection` |
| Lightning Type | `boxagents__boxFileSelection` |

Using bare `FileSelection` causes *Invalid type: FileSelection* / *InvocableVariable fields do not support type ...* / *Variable does not exist: req.file*.

## Steps

1. Add a `boxagents.FileSelection` `@InvocableVariable` to your `Request`.
2. Read `req.file.selectedFileId` (and `selectedFileName`).
3. In Agent Builder, map that input to the `boxagents__boxFileSelection` Lightning Type so the picker UI renders.

Example

```
global with sharing class BoxFilePickerExample {
    @InvocableMethod(label='Get Selected Box File (Example)' description='Accept a file-picker selection and return the file ID' category='Box')
    global static List<Response> getSelectedFile(List<Request> requests) {
        List<Response> responses = new List<Response>();
        for(Request req : requests) {
            if(req.file == null || String.isBlank(req.file.selectedFileId)) {
                throw new IllegalArgumentException('File selection is required');
            }
            Response resp = new Response();
            resp.fileId = req.file.selectedFileId;
            resp.fileName = req.file.selectedFileName;
            responses.add(resp);
        }
        return responses;
    }
    global class Request {
        @InvocableVariable(label='Select File' description='Choose a Box file' required=true)
         global boxagents.FileSelection file;
    }    
    global class Response {
        @InvocableVariable(label='File ID') global String fileId;
        @InvocableVariable(label='File Name') global String fileName;
    }
}
```

## Mapping the input in Agent assets

<img alt="Mapping input agent assets" />

The Apex input lets the action *accept* a selection; mapping it to the Lightning Type makes the *picker UI render*:

1. Open your custom action (Agentforce Studio → Agent Actions, or Flow Builder).
2. Select the **Select File** input.
3. Set its reference / Lightning Type to **`boxagents__boxFileSelection`** (*Box File Picker*).
4. Save and activate.

## Notes

* Namespace prefix in subscriber orgs is the #1 source of errors.
* Null-check `req.file` / `req.file.selectedFileId`.
* The ID is what Box APIs need; the name is for display/logging.
* Full references: the shipped `BoxAIAskWithFilePicker`, `BoxAIGenTextWithFilePicker`, `BoxAIExtractFieldsWithFilePicker`, `BoxAIExtractMetadataWithFilePicker`.

<RelatedLinks title="RELATED GUIDES" />


# Create a review workflow in Box Automate with Slack notifications
Source: https://developer.box.com/tutorials/box-automate-review-workflow

Build a review workflow with Box Automate that routes files through approval tasks, sends notifications in Box, and posts updates to a Slack channel using HTTPS Request outcomes.

Routing documents through reviewers and approvers usually means juggling email threads, chat messages, and spreadsheets to track who has signed off. Missed notifications stall the process, and there is no single audit trail.

This tutorial builds a review workflow in Box Automate that eliminates that manual coordination. When a file is uploaded, moved, or copied into a folder, the workflow assigns a review task, routes the file through approval, and posts status updates to both Box and Slack.

## What you are building

By the end of this tutorial, you have a working Box Automate workflow that:

* Triggers when a file is uploaded, moved, or copied into a designated folder.
* Assigns a General Task to a reviewer for initial review.
* Routes the file through an Approval Task with separate branches for approved and rejected outcomes.
* Sends HTTPS requests on both branches for downstream system integration.
* Merges the branches and sends a final Box notification summarizing the result.
* Posts updates to a Slack channel using the Slack Web API.

## Prerequisites

Before you start, make sure you have the following:

* A <Link href="https://www.box.com/pricing">Box Enterprise account</Link> with an Advanced plan (required for HTTPS Request outcomes).
* Box Automate enabled in the <Link href="https://support.box.com/hc/en-us/articles/51190675028499-Enabling-Box-Automate"> Admin Console</Link>.
* A Slack workspace where you can <Link href="https://api.slack.com/apps/">install apps</Link> (for the Slack integration section).
* Permission to add connectors in the Box Admin Console.

## Post Slack updates with HTTPS Request

Within the workflow, you can use Box Automate's HTTPS Request outcome to post messages to a Slack channel through Slack's `chat.postMessage` API. This section shows you how to set up the Slack app, allow-list the connector in Box, and configure the request.

<Warning>
  You need workspace admin access in Slack and Admin Console access in Box to complete this setup.
</Warning>

### Create and configure the Slack app

<Steps>
  <Step title="Create the Slack app">
    1. Go to [Slack API: Your Apps](https://api.slack.com/apps) and sign in.
    2. Select **Create New App** > **From scratch**.
    3. Enter an app name and select your workspace, then select **Create App**.
  </Step>

  <Step title="Add bot token scopes">
    1. In your app, open **OAuth & Permissions**.
    2. Under **Scopes** > **Bot Token Scopes**, add `chat:write`.
    3. Optional: add `chat:write.public` to post in public channels without inviting the bot.

    <Tip>
      Inviting `@YourBot` to each channel is clearer than relying on `chat:write.public`.
    </Tip>
  </Step>

  <Step title="Install the app and copy the token">
    1. Select **Install to Workspace**. Reinstall after any scope change.
    2. Open **Basic Information** > **App-Level Tokens** and generate or open a token.
    3. Copy the **Bot User OAuth Token** (begins with `xoxb-`).
    4. For private channels, run `/invite @YourBotName` in the channel.
  </Step>

  <Step title="Allow-list Slack in the Box Admin Console">
    1. In the Box Admin Console, confirm that Box Automate and HTTPS Request outcomes are enabled for builders.
    2. Go to **Integrations** > **Connectors**.
    3. Add `https://slack.com` as an allowed connector.
    4. Select **Save**.

    <Note>
      If builders cannot add connectors, ask an admin to pre-create a Slack Web API connector for `slack.com`.
    </Note>
  </Step>
</Steps>

## Build the review workflow

Next, build the review workflow. This workflow triggers when a file is uploaded, moved, or copied into a designated folder. It assigns a review task to a reviewer, routes the file through an approval process, and posts status updates to both Box and Slack.

<Steps>
  <Step title="Open the Box Automate builder">
    In the Box end-user view, open the Box Automate builder and select **New +** to start a new workflow. Name the workflow in the header – for example, `Document Review Pipeline`.
  </Step>

  <Step title="Add the trigger">
    From the **Flow Triggers** section in the side panel, drag a **File** trigger onto the canvas. Configure the trigger to start the workflow when a file is:

    * Uploaded
    * Moved
    * Copied
      Then select the folder to trigger the workflow.
  </Step>

  <Step title="Add the General Task outcome">
    Select the **+** helper node after the trigger. From the side panel, add a **General Task** outcome. Assign the task to the appropriate reviewer and set any required instructions or due dates.
  </Step>

  <Step title="Add the Approval Task">
    After the General Task, select the **+** helper node and add an **Approval Task** outcome. Assign the approver(s) and select the file used to trigger the workflow.

    <Tip>
      One common scenario for assignees is the workflow starter and one specified reviewer to approve the file changes.
    </Tip>

    The Approval Task automatically creates two branches: **Approved** and **Rejected**.
  </Step>

  <Step title="Configure the Approved and Rejected branches">
    Select the **+** node after the Approval Task and add an **HTTPS Request** outcome. Configure the endpoint and payload that should run when the file is approved or rejected.

    | Field | Value |
    | - | - |
    | **Connector** | `slack.com` |
    | **Endpoint** | `/api/chat.postMessage` |
    | **HTTPS Method** | `POST` |
    | **Authentication** | Custom Header |
    | **Credentials** | Key: `Authorization`, Value: `Bearer <your token>` (generated in the Slack app dashboard) |

    Set the request body to:

    ```json theme={null}
    {
      "channel": "box-announcements",
      "markdown_text": "Box Automate: {{workflow.name}} has completed with status {{workflow.status}}. The file {{file.name}} was {{file.status}}."
    }
    ```

    Replace `box-announcements` with your channel name or ID. For production, drive the message text from workflow variables using the Automate variable picker or `/` search.

    <Tip>
      For richer messages, add `blocks` ([Block Kit](https://api.slack.com/block-kit)), `thread_ts` for replies, or `username` and `icon_emoji` overrides where Slack permits.
    </Tip>

    **Test the request**

    Test the HTTPS request directly in the Box Automate builder before publishing the workflow:

    1. In the **HTTPS Request** outcome configuration panel, enter the connector, endpoint, method, headers, and request body.
    2. Select **Test** at the bottom of the panel to send a test request to Slack.
    3. Review the response in the panel:

    * **Success**: Status code `200` with `"ok": true`. The response payload returns message details, including `ts` and `channel`.
    * **Failure**: If `"ok": false`, review the `error` property returned by Slack (such as `invalid_auth`, `channel_not_found`, or `missing_scope`).
  </Step>

  <Step title="Capture the response with JSONPath">
    The results of the `chat.postMessage` from Slack are a JSON payload which are not usable by Box Automate until you pull individual values out of it. JSONPath expressions point at the specific properties you need, so you can store them as workflow variables:

    | Variable | JSONPath | Meaning |
    | - | - | - |
    | `slack_ts` | `$.ts` | Message timestamp. Pass as `thread_ts` in a follow-up HTTPS request to reply in a thread. |
    | `slack_ok` | `$.ok` | Success flag. |
  </Step>

  <Step title="Merge the branches">
    Use the **Merge** option to combine the Approved and Rejected branches back into a single path.
  </Step>

  <Step title="Add final outcomes">
    After the merge point, add a **Send Notification** outcome. Customize the recipients, subject line, and message body, using variables to include workflow details such as the file name or initiator.

    Select the **+** node after the notification and add a final **HTTPS Request** outcome to complete any downstream system action.
  </Step>

  <Step title="Save and publish">
    Select **Save** to create a draft of the workflow. Once complete, select **Publish** to validate and activate it.

    <Note>
      Box Automate does not execute workflow actions as the user who created the workflow. Enterprise-level and folder-level restrictions still apply to every step in the workflow.
    </Note>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Workflow does not trigger when a file is uploaded">
    Confirm the workflow is published, not just saved as a draft. A saved workflow does not execute. Also verify the trigger folder matches the folder you are uploading to – subfolders are not included unless the trigger is configured to monitor them.
  </Accordion>

  <Accordion title="Slack message is not posted (HTTPS Request returns an error)">
    Check the HTTPS Request response in the workflow run details:

    * `invalid_auth` or `not_authed`: the Bot User OAuth Token is missing, expired, or incorrectly formatted. Regenerate the token in the Slack app dashboard and update the `Authorization` header value to `Bearer xoxb-...`.
    * `channel_not_found`: the channel name or ID is incorrect, or the bot has not been invited. Run `/invite @YourBotName` in the target channel.
    * `missing_scope`: the bot token is missing the `chat:write` scope. Add the scope under **OAuth & Permissions** and reinstall the app to your workspace.
  </Accordion>

  <Accordion title="HTTPS Request outcome is not available in the builder">
    HTTPS Request outcomes require a Box Enterprise Advanced plan. Confirm your plan supports this feature and that an admin has enabled HTTPS Request outcomes for builders in the Admin Console.
  </Accordion>

  <Accordion title="Connector blocked or not listed">
    The `slack.com` connector must be allow-listed in the Admin Console under **Integrations** > **Connectors**. If you do not see the option to add connectors, ask a Box admin to pre-create a Slack Web API connector for `slack.com`.
  </Accordion>

  <Accordion title="Task is not assigned or the assignee does not receive it">
    Verify the assignee is a valid, active Box user in the same enterprise. If the user is external, they must be invited as a collaborator on the file or folder before a task can be assigned to them.
  </Accordion>

  <Accordion title="Workflow publishes but actions do not execute">
    Box Automate enforces enterprise-level and folder-level restrictions on every step. If a workflow action targets content the service context does not have access to, that step fails without notification. Verify the target folders and files are accessible and that the required permissions (such as task assignment or notification delivery) are not restricted by Admin Console policies.
  </Accordion>
</AccordionGroup>

## Next steps

Using Box Automate to configure your review processes keeps you on track with notifications in both Box and Slack. While this example covers a single approval flow, you can use it as a template for different iterations – using the HTTPS Request outcome at every action, in just one place, or even combining it with other outcomes such as Box Sign. You can also begin with a File Request trigger to start the workflow.

<CardGroup>
  <Card title="Invoice intake automation" href={localizeLink("/tutorials/invoice-intake")} icon="file-invoice">
    Automate accounts payable with Box AI Extract, metadata, and webhooks.
  </Card>

  <Card title="Sales RFP answer bank" href={localizeLink("/tutorials/sales-rfp-answer-bank")} icon="magnifying-glass">
    Build an AI-powered knowledge base for sales teams using Box Hubs and Box AI.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Route claims evidence for review with Box Automate
Source: https://developer.box.com/tutorials/claims-evidence-review

Build a claims service that runs an automated approval workflow. Box handles the approval or rejection of tasks. Your app chooses the files and starts the review.

A claims system collects evidence into a case folder: photos, police reports, repair estimates, medical records. Someone has to decide whether that evidence is complete and acceptable. That decision then has to be recorded.

This tutorial hands the review to Box. When your app calls `POST /reviews` with selected evidence file IDs, the service tags those files with the claim ID and begins a Box Automate workflow. Box Automate assigns the approval task, waits for the decision, then runs the approved or rejected branch.

<Card title="Clone the working sample" href="https://github.com/box-community/Route-claims-evidence-for-review" icon="github">
  Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
</Card>

<Warning>
  The Box Automate workflow endpoints used in this tutorial are **Beta** and are not available on the [Free Developer Plan](/guides/getting-started/free-developer-plan). Every request must include the `box-version: 2026.0` header. Beta endpoints can change before general availability.
</Warning>

## What you are building

By the end of this tutorial, you have a working Python service that:

* Exposes a `POST /reviews` endpoint your claims system uses to start a review on selected evidence files.
* Writes the claim ID onto each selected evidence file as Box metadata, so the workflow can read it as a variable.
* Looks up the published Automate workflow attached to the claims folder and starts it on the selected files.
* Receives a webhook when the reviewer approves or rejects, and patches `reviewStatus` on each file to `approved` or `rejected`.

Box Automate owns the review itself. Your service never polls for task state or implements approval logic. A V2 webhook closes the loop by writing the decision back to the file's metadata.

<Info>
  **Why a webhook updates review status.** Box Automate assigns the approval task and runs approved or rejected branches, but it does not write file metadata when the task completes. Outbound custom HTTPS actions from Automate to your API are blocked for many URLs. A V2 webhook on `TASK_ASSIGNMENT.UPDATED` lets your service receive the decision and patch `reviewStatus` through the Metadata API.
</Info>

| Component | Purpose | API |
| - | - | - |
| **Automate workflow actions** | Find the published workflow attached to the claims folder | `GET /2.0/automate_workflows` |
| **Manual start** | Start the approve and reject tasks on the selected evidence files | `POST /2.0/automate_workflows/:id/start` |
| **Metadata** | Carry the claim ID into the workflow as a variable | `POST /2.0/files/:id/metadata/:scope/:template` |
| **V2 webhooks** | Receive the approval or rejection and patch `reviewStatus` | `POST /2.0/webhooks` |

<Info>
  **Why metadata carries the claim ID.** During the Beta, the start endpoint does not accept fields at runtime, so you cannot pass a claim ID in the request body. Writing the claim ID to each file as metadata makes it available as a workflow variable. When fields at start become available, you can pass the claim ID directly and drop this step.
</Info>

## Prerequisites

Before you start, make sure you have the following:

* A [Box Enterprise Advanced account](https://www.box.com/pricing) with **Box Automate** enabled. See [Enabling Box Automate](https://docs.box.com/en/box-automate/enabling-box-automate).
* A Box platform application configured with **Client Credentials Grant** authentication. Enable **Read and write all files and folders stored in Box** and **Manage Webhooks**. Set application access to **App + Enterprise Access**, and turn on **Generate user access tokens**. After you change these settings, re-authorize the app in the Admin Console.
* The **user ID** of a managed user who can build and start Automate workflows (for testing, use your own user ID). The Automate list and start endpoints return workflows that user can start. They do not return results for the enterprise service account.
* **Admin access** to create a metadata template, or a Box administrator who can create one for you.
* Permission to build and publish workflows in the Box Automate builder.
* Python 3.11 or higher.
* A coding agent with <Link href="/ai/agent-skills">Box Agent Skills</Link> installed. Run `npx skills add box/box-for-ai` in your project, or install the Cursor, Codex, or Claude Code plugin. See <Link href="/ai/agent-skills">Box Agent Skills</Link> for setup.

<Note>
  Automate and metadata calls require `root_readwrite`, the OAuth scope behind **Read and write all files and folders stored in Box**. Webhook registration requires **Manage Webhooks**. If a scope or feature is missing from the Developer Console, contact Box Support with the user or app context you plan to use.
</Note>

## Configure Box once

These steps happen in the Box Admin Console and Automate builder. An agent cannot do them for you. Complete them before you build the service.

1. **Create a `Claim` metadata template** in the [Admin Console](https://app.box.com/master) under **Metadata**. Add two text fields: Claim ID and Review status. Select **Save**, select the template again, then copy the template key. Confirm the generated field keys with `GET /2.0/metadata_templates/enterprise/<TEMPLATE_KEY>/schema`. This tutorial assumes `claimId` and `reviewStatus`.

2. **Configure Client Credentials Grant for a managed user.** In Developer Console > your CCG app > **Configuration**, enable **Read and write all files and folders stored in Box** and **Manage Webhooks**. Set application access to **App + Enterprise Access**, enable **Generate user access tokens**, and save. Re-authorize the app in the Admin Console. Copy the managed user's ID (Admin Console > Users & Groups, or `GET /2.0/users/me` with that user's token). You pass this ID as `BOX_USER_ID` so the service authenticates as that user, not as the enterprise service account.

   <Warning>
     A service-account token can often read the claims folder and write metadata, yet `GET /2.0/automate_workflows` still returns an empty `entries` list, and start returns `400 Action not found`. Authenticate as a managed user who can run Automate.
   </Warning>

3. **Create a `Claims Review` folder** in Box as that managed user (or invite them as an **Editor**), note its folder ID from the URL, and upload two or three sample PDFs. Without folder access for the user your app acts as, file and metadata calls return 404.

4. **Build and publish a Manual Start workflow** in the Box Automate builder. For a full walkthrough of the builder UI, see [Creating workflows in Box Automate](https://docs.box.com/en/box-automate/creating-workflows-in-box-automate).

   1. Open **Automate**, select **New+** → **Workflow**, and name it `Claims evidence review`.
   2. Drag **Manual Start** onto the canvas and scope it to the `Claims Review` folder.
   3. Add a **Task Action** outcome. Set the type to **Approval**, assign the file to **Trigger: File**, and for testing set both complete and manage to **Workflow owner**. Optionally include the Claim ID metadata field in the task message.
   4. Branch on **Approved** and **Rejected**, and add **Send Notification** on each branch.
   5. Select **Activate** (not only **Save**).

   <Warning>
     The Manual Start folder must match the `folder_id` you query later. An unpublished draft, or a different folder, returns an empty `entries` list rather than an error. `BOX_CLAIMS_WORKFLOW_NAME` must match the published workflow name exactly. The folder display name is unrelated.
   </Warning>

5. **Optional: inspect the workflow IDs** so you recognize the response shape later. Use an access token for the same managed user your app will act as:

```bash theme={null}
curl -X GET "https://api.box.com/2.0/automate_workflows?folder_id=<FOLDER_ID>" \
  -H "box-version: 2026.0" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
```

| Response field | Where it goes |
| - | - |
| `entries[].workflow.id` | Path parameter `workflow_id` |
| `entries[].id` | Body field `workflow_action_id` |

The top-level `id` is the **action** ID, not the workflow ID. Passing the action ID in the path returns a 404.

## Build the service

Choose how to scaffold the service. Both paths produce the same app; continue to [Run and verify](#run-and-verify) when you finish.

<Tabs>
  <Tab title="Build with an agent">
    With Box configured and <Link href="/ai/agent-skills">Box Agent Skills</Link> installed, paste the following prompt into your coding agent. Replace the placeholders only if you want the agent to pre-fill `.env`; otherwise leave them and fill credentials yourself after scaffolding.

    ```text theme={null}
    Build a Python Flask service named claims-evidence-review that starts a Box
    Automate manual-start workflow when POST /reviews receives selected evidence
    file IDs.

    Prerequisites already done in Box:
    - Enterprise metadata template key: <TEMPLATE_KEY> (fields claimId, reviewStatus)
    - Folder ID for Manual Start: <FOLDER_ID>
    - Published Automate workflow named exactly: Claims evidence review
    - CCG app has read/write files and Manage Webhooks scopes, App + Enterprise
      Access, and Generate user access tokens enabled and re-authorized
    - Managed user ID for Automate calls: <USER_ID> (not the service account)

    Create these files:

    1. box_client.py — CCG BoxClient from BOX_CLIENT_ID, BOX_CLIENT_SECRET,
       and BOX_USER_ID via python-dotenv. Authenticate as the managed user
       (CCGConfig user_id). Do NOT use enterprise_id / the service account;
       Automate list and start return empty or Action not found for that actor.

    2. automate.py — wrap the Beta Automate APIs with client.make_request
       (Box Python SDK v10 has no automate_workflows manager yet):
       - Always send header box-version: 2026.0
       - GET https://api.box.com/2.0/automate_workflows?folder_id=...
       - Map each entry to WorkflowAction(workflow_id=entry.workflow.id,
         action_id=entry.id, name=entry.workflow.name)
       - find_workflow_action(client, folder_id, workflow_name) raises LookupError
         with a clear message if none match
       - start_workflow POSTs to
         /2.0/automate_workflows/{workflow_id}/start with body
         { "workflow_action_id": action_id, "file_ids": [...] }
       - MAX_FILES_PER_RUN = 20
       - Do NOT use legacy /2.0/workflows or invent folder/flow/outcomes fields

    3. claims_metadata.py — export tag_evidence and replace_metadata. For each
       file_id, create enterprise metadata with { claimId, reviewStatus: "in_review" }.
       On 409 Conflict, call replace_metadata to JSON-Patch replace both fields
       (resubmitted evidence).

    4. app.py — POST /reviews accepts { claim_id, file_ids }. Validate inputs,
       tag metadata first, resolve workflow by BOX_CLAIMS_WORKFLOW_NAME on
       BOX_CLAIMS_FOLDER_ID, start workflow, return 202
       { status, claim_id, workflow, file_ids }.

    5. app.py — also add POST /webhooks/task-updated that receives
       TASK_ASSIGNMENT.UPDATED webhooks from Box, verifies the signature with
       WebhooksManager.validate_message (Box Python SDK v10), reads the decision
       from source.resolution_state and the file ID from source.item.id, normalizes
       the decision to lowercase, and patches reviewStatus on the file to approved
       or rejected using replace_metadata from claims_metadata.py. Env vars:
       BOX_WEBHOOK_PRIMARY_KEY, BOX_WEBHOOK_SECRET_KEY.

    6. register_webhook.py — one-time setup script. Takes a URL argument and
       creates a V2 webhook on BOX_CLAIMS_FOLDER_ID for
       TASK_ASSIGNMENT.UPDATED using client.webhooks.create_webhook.

    7. .env.example and .gitignore (.env excluded). Env vars:
       BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_USER_ID,
       BOX_CLAIMS_FOLDER_ID, BOX_CLAIMS_TEMPLATE_KEY,
       BOX_CLAIMS_WORKFLOW_NAME, BOX_WEBHOOK_PRIMARY_KEY,
       BOX_WEBHOOK_SECRET_KEY

    Use Python 3.11+, boxsdk>=10, flask, python-dotenv. Create the project at
    ~/claims-evidence-review, create a venv, install deps, and print the curl
    command to test POST /reviews after I fill .env.
    ```

    When the agent finishes, copy `.env.example` to `.env` and fill in your credentials, user ID, folder ID, and template key. Put each variable on its own line.
  </Tab>

  <Tab title="Build by hand">
    Prefer to write the code yourself, or need a reference when the agent drifts? Complete [Configure Box once](#configure-box-once) first, then follow the steps in order.

    <AccordionGroup>
      <Accordion title="1. Set up the development environment">
        1. Create a project directory:

        ```bash theme={null}
        mkdir ~/claims-evidence-review && cd ~/claims-evidence-review
        ```

        2. Create and activate a Python virtual environment:

        ```bash theme={null}
        python3 -m venv .venv
        source .venv/bin/activate
        ```

        After activation, your terminal prompt shows `(.venv)` at the beginning.

        <Note>
          Every time you open a new terminal window or tab, re-activate with `source .venv/bin/activate`. `ModuleNotFoundError` usually means the venv is not activated.
        </Note>

        3. Install packages:

        ```bash theme={null}
        pip install "boxsdk>=10" flask python-dotenv
        ```

        4. Create a `.env` file:

        ```bash theme={null}
        BOX_CLIENT_ID=your_client_id
        BOX_CLIENT_SECRET=your_client_secret
        BOX_USER_ID=your_managed_user_id
        BOX_CLAIMS_FOLDER_ID=your_claims_review_folder_id
        BOX_CLAIMS_TEMPLATE_KEY=your_metadata_template_key
        BOX_CLAIMS_WORKFLOW_NAME=Claims evidence review
        ```

        <Warning>
          Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
        </Warning>
      </Accordion>

      <Accordion title="2. Authenticate the Box client">
        Create `box_client.py`:

        ```python theme={null}
        import os

        from box_sdk_gen import BoxCCGAuth, BoxClient, CCGConfig
        from dotenv import load_dotenv

        load_dotenv()


        def get_box_client() -> BoxClient:
            config = CCGConfig(
                client_id=os.getenv("BOX_CLIENT_ID"),
                client_secret=os.getenv("BOX_CLIENT_SECRET"),
                user_id=os.getenv("BOX_USER_ID"),
            )
            return BoxClient(auth=BoxCCGAuth(config=config))
        ```

        <Tip>
          Client Credentials Grant with `user_id` authenticates as that managed user. The Automate Manual Start endpoints return workflows that user can start. Do not use `enterprise_id` here: the enterprise service account can access the folder yet still sees an empty Automate list. For other options, see [Select an authentication method](/guides/authentication/select).
        </Tip>
      </Accordion>

      <Accordion title="3. Call the Automate endpoints">
        Create `automate.py`. This module wraps both Automate endpoints and turns the nested list response into a small value object, so the rest of your app never handles the two raw IDs.

        ```python theme={null}
        from dataclasses import dataclass

        from box_sdk_gen import BoxClient
        from box_sdk_gen.networking.fetch_options import FetchOptions, ResponseFormat

        BOX_API_BASE = "https://api.box.com/2.0"
        AUTOMATE_HEADERS = {"box-version": "2026.0"}

        MAX_FILES_PER_RUN = 20


        @dataclass(frozen=True)
        class WorkflowAction:
            """A published Automate workflow that can be started through the API."""

            workflow_id: str
            action_id: str
            name: str


        def list_workflow_actions(client: BoxClient, folder_id: str) -> list[WorkflowAction]:
            response = client.make_request(
                FetchOptions(
                    url=f"{BOX_API_BASE}/automate_workflows",
                    method="GET",
                    params={"folder_id": folder_id},
                    headers=AUTOMATE_HEADERS,
                    response_format=ResponseFormat.JSON,
                )
            )

            return [
                WorkflowAction(
                    workflow_id=entry["workflow"]["id"],
                    action_id=entry["id"],
                    name=entry["workflow"].get("name", ""),
                )
                for entry in response.data.get("entries") or []
            ]


        def find_workflow_action(
            client: BoxClient, folder_id: str, workflow_name: str
        ) -> WorkflowAction:
            actions = list_workflow_actions(client, folder_id)

            if not actions:
                raise LookupError(
                    f"No Automate workflow actions on folder {folder_id}. Confirm the "
                    "workflow is published and its Manual Start trigger uses this folder."
                )

            for action in actions:
                if action.name == workflow_name:
                    return action

            available = ", ".join(sorted(action.name for action in actions))
            raise LookupError(
                f"Workflow {workflow_name!r} not found on folder {folder_id}. "
                f"Available workflows: {available}."
            )


        def start_workflow(
            client: BoxClient, action: WorkflowAction, file_ids: list[str]
        ) -> None:
            client.make_request(
                FetchOptions(
                    url=f"{BOX_API_BASE}/automate_workflows/{action.workflow_id}/start",
                    method="POST",
                    headers=AUTOMATE_HEADERS,
                    data={"workflow_action_id": action.action_id, "file_ids": file_ids},
                    response_format=ResponseFormat.JSON,
                )
            )
        ```

        <Note>
          The Automate endpoints are not yet in the generated Python SDK, so this module uses `client.make_request`. The SDK still handles token refresh, retries, and error mapping to `BoxAPIError`. When the endpoints reach the SDK, swap the two `make_request` calls for generated methods and leave the rest of the app untouched.
        </Note>

        A successful start returns `204 No Content`. Treat a non-raising call as confirmation that Box accepted the run.
      </Accordion>

      <Accordion title="4. Tag evidence with the claim ID">
        Create `claims_metadata.py`. This writes the claim context onto each file before the workflow starts.

        ```python theme={null}
        import os

        from box_sdk_gen import (
            BoxAPIError,
            BoxClient,
            CreateFileMetadataByIdScope,
            UpdateFileMetadataByIdRequestBody,
            UpdateFileMetadataByIdRequestBodyOpField,
            UpdateFileMetadataByIdScope,
        )
        from dotenv import load_dotenv

        load_dotenv()

        HTTP_CONFLICT = 409


        def tag_evidence(client: BoxClient, file_ids: list[str], claim_id: str) -> None:
            """Attach claim context to each evidence file so the workflow can read it."""
            template_key = os.getenv("BOX_CLAIMS_TEMPLATE_KEY")
            values = {"claimId": claim_id, "reviewStatus": "in_review"}

            for file_id in file_ids:
                try:
                    client.file_metadata.create_file_metadata_by_id(
                        file_id=file_id,
                        scope=CreateFileMetadataByIdScope.ENTERPRISE,
                        template_key=template_key,
                        request_body=values,
                    )
                except BoxAPIError as error:
                    if error.response_info.status_code != HTTP_CONFLICT:
                        raise
                    replace_metadata(client, file_id, template_key, values)


        def replace_metadata(
            client: BoxClient, file_id: str, template_key: str, values: dict[str, str]
        ) -> None:
            """Overwrite fields on an existing metadata instance."""
            client.file_metadata.update_file_metadata_by_id(
                file_id=file_id,
                scope=UpdateFileMetadataByIdScope.ENTERPRISE,
                template_key=template_key,
                request_body=[
                    UpdateFileMetadataByIdRequestBody(
                        op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
                        path=f"/{key}",
                        value=value,
                    )
                    for key, value in values.items()
                ],
            )
        ```

        A file that already carries an instance of the template returns `409 Conflict` on create. The handler falls back to replacing the values so a restarted review does not fail.
      </Accordion>

      <Accordion title="5. Build the start review endpoint">
        Create `app.py`. This is the endpoint your claims system calls to start a review on selected evidence files.

        ```python theme={null}
        import os

        from box_sdk_gen import BoxAPIError
        from dotenv import load_dotenv
        from flask import Flask, jsonify, request

        from automate import MAX_FILES_PER_RUN, find_workflow_action, start_workflow
        from box_client import get_box_client
        from claims_metadata import tag_evidence

        load_dotenv()
        app = Flask(__name__)


        @app.post("/reviews")
        def start_review():
            payload = request.get_json(silent=True) or {}
            claim_id = payload.get("claim_id")
            file_ids = payload.get("file_ids") or []

            if not claim_id:
                return jsonify({"error": "claim_id is required"}), 400
            if not file_ids:
                return jsonify({"error": "file_ids must list at least one file"}), 400
            if len(file_ids) > MAX_FILES_PER_RUN:
                return jsonify(
                    {"error": f"Box Automate accepts at most {MAX_FILES_PER_RUN} files per run"}
                ), 400

            client = get_box_client()
            folder_id = os.getenv("BOX_CLAIMS_FOLDER_ID")
            workflow_name = os.getenv("BOX_CLAIMS_WORKFLOW_NAME")

            try:
                tag_evidence(client, file_ids, claim_id)
                action = find_workflow_action(client, folder_id, workflow_name)
                start_workflow(client, action, file_ids)
            except LookupError as error:
                return jsonify({"error": str(error)}), 404
            except BoxAPIError as error:
                return jsonify({"error": error.message}), error.response_info.status_code

            return jsonify(
                {
                    "status": "review_started",
                    "claim_id": claim_id,
                    "workflow": action.name,
                    "file_ids": file_ids,
                }
            ), 202


        if __name__ == "__main__":
            app.run(port=5000)
        ```

        Tag metadata before starting the workflow. A workflow variable can only read metadata that already exists on the file.
      </Accordion>

      <Accordion title="6. Close the loop with a webhook handler">
        The workflow assigns a task and runs the approved or rejected branch, but it does not write the decision back to the file's metadata. A <Link href="/guides/webhooks/v2/create-v2">V2 webhook</Link> on `TASK_ASSIGNMENT.UPDATED` closes the loop.

        Add the webhook endpoint to `app.py`, below the existing `/reviews` route:

        ```python theme={null}
        from box_sdk_gen.managers.webhooks import WebhooksManager
        from claims_metadata import replace_metadata, tag_evidence

        VALID_DECISIONS = {"approved", "rejected"}


        @app.post("/webhooks/task-updated")
        def handle_task_updated():
            body = request.get_data(as_text=True)
            headers = {k.lower(): v for k, v in request.headers}

            primary_key = os.getenv("BOX_WEBHOOK_PRIMARY_KEY", "")
            secondary_key = os.getenv("BOX_WEBHOOK_SECRET_KEY", "")

            if not WebhooksManager.validate_message(
                body, headers, primary_key, secondary_key=secondary_key
            ):
                return jsonify({"error": "invalid signature"}), 403

            payload = request.get_json(silent=True) or {}
            trigger = payload.get("trigger", "")
            if trigger != "TASK_ASSIGNMENT.UPDATED":
                return "", 200

            source = payload.get("source", {})
            resolution = source.get("resolution_state", "").lower()
            if resolution not in VALID_DECISIONS:
                return "", 200

            file_id = source.get("item", {}).get("id")
            if not file_id:
                return "", 200

            client = get_box_client()
            template_key = os.getenv("BOX_CLAIMS_TEMPLATE_KEY")
            replace_metadata(client, file_id, template_key, {"reviewStatus": resolution})

            return "", 200
        ```

        Finally, create `register_webhook.py` to register the webhook once per environment:

        ```python theme={null}
        import os
        import sys

        from box_sdk_gen.managers.webhooks import (
            CreateWebhookTarget,
            CreateWebhookTargetTypeField,
            CreateWebhookTriggers,
        )
        from dotenv import load_dotenv

        from box_client import get_box_client

        load_dotenv()


        def main():
            if len(sys.argv) < 2:
                print("Usage: python register_webhook.py <WEBHOOK_URL>")
                sys.exit(1)

            address = sys.argv[1]
            folder_id = os.getenv("BOX_CLAIMS_FOLDER_ID")
            client = get_box_client()

            webhook = client.webhooks.create_webhook(
                target=CreateWebhookTarget(
                    id=folder_id,
                    type=CreateWebhookTargetTypeField.FOLDER,
                ),
                address=address,
                triggers=[CreateWebhookTriggers.TASK_ASSIGNMENT_UPDATED],
            )
            print(f"Webhook created: {webhook.id}")


        if __name__ == "__main__":
            main()
        ```

        Add the signature keys to `.env`:

        ```bash theme={null}
        BOX_WEBHOOK_PRIMARY_KEY=your_primary_signature_key
        BOX_WEBHOOK_SECRET_KEY=your_secondary_signature_key
        ```

        Project layout:

        ```text theme={null}
        claims-evidence-review/
        ├── .env
        ├── .venv/
        ├── app.py
        ├── automate.py
        ├── box_client.py
        ├── claims_metadata.py
        └── register_webhook.py
        ```

        Then continue to [Run and verify](#run-and-verify).
      </Accordion>
    </AccordionGroup>
  </Tab>
</Tabs>

## Run and verify

1. **Terminal 1 — start the server.** Make sure you are in the `claims-evidence-review` directory and the virtual environment is activated:

```bash theme={null}
cd ~/claims-evidence-review
source .venv/bin/activate
python3 app.py
```

You should see:

```text theme={null}
* Running on http://127.0.0.1:5000
```

Leave this terminal running.

2. **Terminal 2 — start a review.** Open a new terminal tab or window. Use file IDs from the sample PDFs in `Claims Review`, not the folder ID:

```bash theme={null}
curl -X POST http://127.0.0.1:5000/reviews \
  -H "Content-Type: application/json" \
  -d '{
    "claim_id": "CLM-1042",
    "file_ids": ["123456789", "987654321"]
  }'
```

A successful response looks like:

```json theme={null}
{
  "status": "review_started",
  "claim_id": "CLM-1042",
  "workflow": "Claims evidence review",
  "file_ids": ["123456789", "987654321"]
}
```

3. Confirm in Box:

   * Open an evidence file → **Metadata** tab shows claim `CLM-1042` and status `in_review`.
   * As the task assignee, open the approval task and confirm the claim ID appears in the message.
   * Approve or reject from the file's **Activity** sidebar panel, and confirm the matching branch runs.

`reviewStatus` stays `in_review` after this step. Continue to [Update review status after the decision](#update-review-status-after-the-decision) to patch metadata when the task completes.

## Update review status after the decision

The workflow assigns the task and runs the approved or rejected branch, but it does not write back to the file's metadata. To close the loop, add a <Link href="/guides/webhooks/v2/create-v2">V2 webhook</Link> that listens for `TASK_ASSIGNMENT.UPDATED` and patches `reviewStatus` to `approved` or `rejected`.

### Add webhook signature keys

1. In the [Developer Console](https://cloud.app.box.com/developers/console), open your app and select **Webhooks** → **Manage signature keys**. Generate a primary and secondary key.
2. Add them to `.env`:

```bash theme={null}
BOX_WEBHOOK_PRIMARY_KEY=your_primary_signature_key
BOX_WEBHOOK_SECRET_KEY=your_secondary_signature_key
```

Use the keys generated for your Box app. Generic test values cannot validate signatures from Box.

### Expose the app for webhook delivery

Box must reach your endpoint over HTTPS. For local testing, use a tunnel such as [ngrok](https://ngrok.com/):

```bash theme={null}
ngrok http 5000
```

Copy the `https://` forwarding URL. You need it for the registration step.

<Note>
  A tunnel forwards HTTPS traffic to your local Flask app at `/webhooks/task-updated`. A webhook delivered to a different public URL does not run this handler unless you forward the request or reimplement the metadata patch there.
</Note>

### Register the webhook

Run `register_webhook.py` once with the public URL of your endpoint. From the project directory with the virtual environment activated:

```bash theme={null}
cd ~/claims-evidence-review
source .venv/bin/activate
python3 register_webhook.py https://<YOUR_DOMAIN>/webhooks/task-updated
```

The script creates a V2 webhook on the claims folder for `TASK_ASSIGNMENT.UPDATED`. Register the webhook once per environment. If you create it in the Box UI instead, skip the script.

If you create the webhook in the Box UI, set **Content Type** to **Folder**, select the `Claims Review` folder, and select **Task Assignment Updated**. In this form, content type means the target item type, not the HTTP `Content-Type` header.

<Note>
  Your app must have the **Manage Webhooks** scope enabled in the Developer Console. If the scope is unavailable, contact Box Support.
</Note>

### Add the webhook handler

If you used the agent prompt, the handler is already in `app.py`. If you built by hand, add the endpoint from [step 6 of Build by hand](#build-the-service).

The handler:

1. Verifies the webhook signature using the SDK's `WebhooksManager.validate_message`.
2. Reads the decision from `source.resolution_state` and the file ID from `source.item.id`.
3. Normalizes the decision to `approved` or `rejected` and patches `reviewStatus` on the file.

If you process webhooks outside Flask, verify the Box signature, read `source.resolution_state` and `source.item.id`, normalize the decision to lowercase, and call `PUT /2.0/files/:id/metadata/enterprise/:templateKey` with a JSON Patch replace on `/reviewStatus`.

### Verify the full loop

1. Start a review with `POST /reviews`.
2. Open the file's **Metadata** tab and confirm that `reviewStatus` is `in_review`.
3. Approve or reject the task from the file's **Activity** sidebar.
4. Confirm that the webhook endpoint returns `200`.
5. Refresh the file's **Metadata** tab. `reviewStatus` now displays `approved` or `rejected`.

The gap is closed only when the metadata value changes. A delivered webhook does not update metadata unless your handler calls the Metadata API.

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Configuration.
    * Ensure the app is authorized and its type is Client Credentials Grant.
  </Accordion>

  <Accordion title="invalid_grant: Grant credentials are invalid">
    Your app is requesting a user token, but the Developer Console is not set up for it. Confirm **App + Enterprise Access** and **Generate user access tokens**, then re-authorize the app in the Admin Console. Verify `BOX_USER_ID` is the managed user's ID (digits only, no spaces).
  </Accordion>

  <Accordion title="Empty entries list from GET /2.0/automate_workflows">
    The request succeeded, but no workflow matched for this caller. Check each of the following:

    * You are authenticated as a **managed user** who can run Automate, not as the enterprise service account. A user token that returns the workflow while the app returns `entries: []` usually means the app still uses `enterprise_id` instead of `user_id`.
    * The workflow is **published**, not saved as a draft.
    * The workflow has a **Manual Start** trigger.
    * The trigger's folder is the folder whose ID you passed as `folder_id`.
    * The managed user can access that folder.
  </Accordion>

  <Accordion title="404 Not Found on an Automate endpoint">
    Several causes produce a 404 here:

    * Box Automate is not enabled for your enterprise. Ask your admin to [enable Box Automate](https://docs.box.com/en/box-automate/enabling-box-automate).
    * Your account is on the Free Developer Plan, where these endpoints are unavailable.
    * The `box-version: 2026.0` header is missing.
    * You passed the action ID in the URL path. The path takes `entries[].workflow.id`; the body takes `entries[].id`.
  </Accordion>

  <Accordion title="400 Action not found when starting the workflow">
    The workflow and action IDs can be valid for a different actor. Hardcoding IDs from a successful user-token curl does not help if the app still authenticates as the service account. Switch the client to `BOX_USER_ID`, then confirm that `file_ids` contains at least one ID, at most 20 IDs, and that every file is within the Manual Start folder scope.
  </Accordion>

  <Accordion title="400 Bad Request when starting the workflow">
    The request reached the workflow but the payload was rejected. Confirm that `file_ids` contains at least one ID, that it holds no more than 20 IDs, and that every file is within the folder scope configured on the Manual Start trigger.
  </Accordion>

  <Accordion title="The approval task shows no claim ID">
    The workflow variable is not resolving to your metadata field. Confirm that the field keys in `tag_evidence` match the `fields[].key` values returned by `GET /2.0/metadata_templates/enterprise/:key/schema`, and that the task message references the Claim ID field from that template.
  </Accordion>

  <Accordion title="Workflow not found on folder">
    The list call succeeded, but `find_workflow_action` returned no match for `BOX_CLAIMS_WORKFLOW_NAME`. Confirm that the published workflow name matches the value in `.env` exactly. Rename the workflow in the Automate builder and activate it again, or set `BOX_CLAIMS_WORKFLOW_NAME` to the name shown in the error response. The folder display name is unrelated.
  </Accordion>

  <Accordion title="403 Forbidden">
    The app is missing a required scope. Enable **Read and write all files and folders stored in Box** for metadata and Automate calls, and **Manage Webhooks** for webhook registration. Depending on your authentication method and enterprise settings, the app may need admin authorization or reauthorization in the Admin Console before a scope change takes effect.
  </Accordion>

  <Accordion title="Webhook returns 403 invalid signature">
    Confirm that `BOX_WEBHOOK_PRIMARY_KEY` and `BOX_WEBHOOK_SECRET_KEY` in `.env` match the keys shown in the Developer Console under **Webhooks** → **Manage signature keys**. If you recently rotated a key, the in-flight delivery may still carry the old signature. See <Link href="/guides/webhooks/v2/signatures-v2">Verify webhook signatures</Link>.
  </Accordion>

  <Accordion title="reviewStatus does not update after approval">
    Open the file's **Activity** sidebar and confirm that the task has a final decision. Inspect the webhook body and confirm that `source.resolution_state` is `approved` or `rejected` and `source.item.id` is the evidence file ID. Box may send the decision in uppercase in the webhook body. Normalize it to lowercase before you compare or write metadata. If the webhook never arrives, verify that the webhook is registered and that your handler is reachable from the internet. An external processor must call the Metadata API to change `reviewStatus`.
  </Accordion>

  <Accordion title="The agent used /2.0/workflows or invented SDK methods">
    The Automate endpoints are Beta and the Box Python SDK v10 does not yet provide an Automate workflows manager. Re-paste the prompt and emphasize `client.make_request` with `box-version: 2026.0`, or select the **Build by hand** tab in [Build the service](#build-the-service) for the tested modules.
  </Accordion>
</AccordionGroup>

## Scaling to production

<AccordionGroup>
  <Accordion title="Cache the workflow and action IDs">
    The sample calls `GET /2.0/automate_workflows` on every review to resolve the workflow by name. That list call is optional in production. The IDs you need are stable for a given published workflow:

    | Value | Source | Used in |
    | - | - | - |
    | Workflow ID | `entries[].workflow.id` | Path: `POST /2.0/automate_workflows/{workflow_id}/start` |
    | Action ID | `entries[].id` | Body: `workflow_action_id` |

    Resolve them once at startup, or store them as configuration after a successful list call:

    ```bash theme={null}
    BOX_AUTOMATE_WORKFLOW_ID=<workflow_id_from_list>
    BOX_AUTOMATE_WORKFLOW_ACTION_ID=<action_id_from_list>
    ```

    Then call start with those IDs and skip `find_workflow_action`. Keep the list lookup as a fallback if start begins failing (for example after you replace the workflow in the builder).

    <Warning>
      Caching IDs only skips the list call. Start still requires a managed user who can run Automate. Hardcoding IDs from a successful user-token curl does not work if the app authenticates as the enterprise service account. That case returns `400 Action not found`, not an empty list.
    </Warning>
  </Accordion>

  <Accordion title="Make review starts idempotent">
    A double-submitted request starts the workflow twice and can create duplicate approval tasks on the same evidence. You can use `reviewStatus` as a guard: skip the start if the value is already `in_review`. The webhook handler resets it to `approved` or `rejected` after the decision, so the field accurately reflects the current state.

    Alternatively, catch duplicates in your claims system. For example, ignore a second request with the same `claim_id` and `file_ids` while a review is still open. You can also list tasks on the file and skip start if an incomplete approval task already exists.
  </Accordion>

  <Accordion title="Secure the endpoint">
    `POST /reviews` needs authentication in production. Verify a signed request from your claims system, or place the service behind your existing gateway. Keep credentials in a secret manager rather than a `.env` file, and never expose user or app tokens to a browser client. Prefer a dedicated managed user with the least Automate and folder access your flow needs, rather than a personal admin account.
  </Accordion>

  <Accordion title="Plan for fields at start">
    Tagging metadata before the run is a workaround for a Beta limitation, and it costs one API call per file. When the start endpoint accepts fields at runtime, pass the claim ID directly in the start request and keep metadata only where you want the claim ID to persist on the file for search and reporting. Isolating the workaround in `claims_metadata.py` makes that a single-module change.
  </Accordion>

  <Accordion title="Handle more than 20 files">
    A single start request accepts 20 files at most. For larger evidence sets, split the files into batches and start one run per batch (each batch can create its own approval tasks), or restructure the workflow to trigger on the case folder rather than on individual files.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Box Agent Skills" href={localizeLink("/ai/agent-skills")} icon="graduation-cap">
    Install skills so your coding agent can scaffold more Box integrations from natural language.
  </Card>

  <Card title="Start Automate workflow" href={localizeLink("/reference/v2026.0/post-automate-workflows-id-start")} icon="code">
    See the full API specification for the manual start endpoint.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Build your company brain
Source: https://developer.box.com/tutorials/company-brain

Turn scattered company content into governed knowledge. Review new files with Box AI and publish approved content to Box Hubs, allowing humans and AI agents to work from the same trusted source.

A personal AI knowledge base - a folder of notes, research, and strategy docs that an agent can read and act on - works well for one person. Startups and enterprises, however, need a shared source of truth that multiple people and multiple agents can use safely. Teams have to answer questions like:

* Who can access specific information, and who can update it?
* Which version is current?
* How do you review agent-generated changes?
* Can an answer be traced back to the source material it came from?

The answer is a **shared company brain**: a governed repository of company context, product knowledge, operating rules, and generated outputs that humans and agents use to operate the business. This provides the same trusted content whether it is reached by a developer's local coding agent, a cloud agent over MCP, or a person in the Box web app.

This tutorial builds that knowledge layer with Box:

1. You organize content into a **domain-based structure** - one curated knowledge base per domain - with a staging area for new files and an approved area for trusted ones.
2. When a file lands in staging, you use **Box AI** to review it: summarize it, score its content health, suggest a domain and tags, and flag issues like missing owners or stale guidance.
3. You record that review as **Box metadata** so every file carries its governance status, and you promote approved content into a **Box Hub** - the trusted destination that agents query.
4. Humans and agents query the brain through **Box AI**, getting answers grounded in approved, permission-controlled content, with citations back to the source.

For the query-shaped overview of this pattern, e.g. enterprise repository, hub, permission-inheriting Ask, see <Link href="/guides/hubs-api/access-controlled-knowledge-base">Turn an enterprise document repository into an access-controlled AI knowledge base</Link>.

<Card title="Clone the working sample" href="https://github.com/box-community/box-company-brain" icon="github">
  Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
</Card>

## What you are building

By the end of this tutorial, you have a working Python project that:

* Provisions a governed folder structure - the company brain - organized by domain, each with a staging and an approved area.
* Uses a dedicated **service account** as the shared, governed identity that both your automation and your agents act through.
* Reviews staged files with Box AI, producing a summary, a suggested domain, tags, and a content health score, then flags quality issues.
* Writes the review back to each file as a governance metadata instance, so status and ownership are searchable and auditable.
* Publishes approved content to a domain Box Hub and answers natural-language questions grounded in that trusted content.
* Gives your local and cloud agents a safe, permission-aware way to work from the same source of truth.

## Prerequisites

Before you start, make sure you have the following:

* A <Link href="https://account.box.com/signup/developer">free Box developer account</Link>, or a <Link href="https://www.box.com/pricing">Box Enterprise account</Link> with **Box AI** and **Box Hubs** enabled. See <Link href="https://docs.box.com/en/box-hubs/box-hubs-for-admins/configuring-box-hubs">Configuring Box Hubs</Link>.
* A platform application configured with **Client Credentials Grant** authentication.
* **Admin access** to create a metadata template (Step 2), or a Box administrator who can create one for you.
* Python 3.11 or higher.
* The following scopes enabled on your platform app:
  * Read and write all files and folders stored in Box
  * Manage AI
  * Manage enterprise properties (required to create and write metadata)

## Step-by-step process

A company brain is built from four Box capabilities working together. Each one maps to a requirement that a shared, trusted knowledge layer must meet.

| Component | Purpose | API |
| - | - | - |
| **Folders** | Organize content by domain, and separate staged files from approved ones | `GET /2.0/folders/:id/items` |
| **Box AI Extract** | Review staged content: summarize, score health, suggest a domain and tags | `POST /2.0/ai/extract_structured` |
| **Metadata** | Record governance state (domain, owner, status, health) on each file | `POST /2.0/files/:id/metadata/:scope/:template` |
| **Hubs** and **Box AI Ask** | Publish approved content and answer questions grounded in it | `POST /2.0/hubs`, `POST /2.0/ai/ask` |

<Info>
  Box Hubs and Box AI inherit permissions from the underlying source files. Both people and agents only ever see answers derived from content they already have access to in Box. The company brain does not add a separate access-control layer - it reuses the one you already trust.
</Info>

<Steps>
  <Step title="Design your company brain structure">
    The best knowledge bases are domain-based, not generic. Rather than one giant brain, create a focused knowledge base per domain - security, legal, product, and so on - and let each domain team own its content.

    Within each domain, separate content that has been reviewed from content that has not. New files land in a `_staging` area; only approved files move to the `approved` area that agents are pointed at.

    Create a folder structure in Box similar to the following:

    ```
    Company Brain/
    ├── security/
    │   ├── _staging/        # new or updated files awaiting review
    │   └── approved/        # trusted, published knowledge
    ├── legal/
    │   ├── _staging/
    │   └── approved/
    ├── product/
    │   ├── _staging/
    │   └── approved/
    ├── operating-rules/     # rules that govern how agents behave
    │   └── agent-operating-rules.md
    └── outputs/             # content generated by agents, saved back
    ```

    Note the **folder ID** of the top-level `Company Brain` folder, and the ID of one domain's `_staging` folder (for example, `security/_staging`). You use these in later steps. The folder ID is the number at the end of the folder's URL: `https://app.box.com/folder/123456789` means the folder ID is `123456789`.

    <Tip>
      The `operating-rules` folder is part of the brain, not an afterthought. Storing your agent operating rules alongside the knowledge they govern means every agent - local or cloud - reads the current rules from the same place, instead of each teammate copying yesterday's version into their own workspace.
    </Tip>

    <Note>
      This tutorial works one domain end to end (for example, `security`). Once the pattern works, repeat it per domain. Adding a domain is easy: a new folder pair and a new Hub, owned by the team closest to the work.
    </Note>
  </Step>

  <Step title="Create the knowledge governance metadata template">
    Governance is what separates a trusted knowledge base from a folder of files. A metadata template lets every file carry the same governance fields - which domain it belongs to, who owns it, whether it is approved, and how healthy its content is - so status is explicit, searchable, and auditable.

    <Tip>
      This step requires Admin access. If you do not have access, contact your Box administrator.
    </Tip>

    1. Open the [Box Admin Console](https://app.box.com/master) and select **Metadata**.
    2. Click **New** and name the template `Knowledge Governance`.
    3. Add the following fields:

    | Field name | Type | Description |
    | - | - | - |
    | Domain | Text | The domain this file belongs to, for example `security` |
    | Owner | Text | The person or team accountable for keeping this file current |
    | Status | Text | `staged`, `approved`, or `rejected` |
    | Content Health Score | Number | A 0-100 score for how usable this content is as knowledge |
    | Summary | Text | A short, agent-readable summary of the file |
    | Tags | Text | Comma-separated tags for retrieval |
    | Review Notes | Text | Issues flagged during review, for example missing owner or stale date |

    4. Click **Save**.
    5. Click back into your newly created template and copy the **template key** shown under the template name. You need it in a later step.

    <Note>
      Box derives each field's **key** from its display name in camel case - `Content Health Score` becomes `contentHealthScore`. The code in Step 6 uses these keys. If you rename a field, confirm its key in the Admin Console and update the code to match. For a detailed walkthrough, see <Link href="https://docs.box.com/en/box-admin-tools/managing-content/metadata/customizing-metadata-templates">Customizing Metadata Templates</Link>.
    </Note>
  </Step>

  <Step title="Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir company-brain && cd company-brain
    ```

    2. Create and activate a Python virtual environment:

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    After activation, your terminal prompt shows `(.venv)` at the beginning. This confirms you are working inside the virtual environment.

    <Note>
      Every time you open a new terminal window or tab, re-activate the virtual environment by running `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError` when running commands, it usually means the venv is not activated.
    </Note>

    3. Install the required packages:

    ```bash theme={null}
    pip install boxsdk python-dotenv
    ```

    4. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your actual credentials from the Box Developer Console:

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    BOX_METADATA_TEMPLATE_KEY=your_template_key
    STAGING_FOLDER_ID=your_domain_staging_folder_id
    APPROVED_FOLDER_ID=your_domain_approved_folder_id
    ```

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>

    <Note>
      **Understanding environment variables:** The `.env` file stores sensitive values (your actual credentials). Your Python code reads these values by referencing their **names** using `os.getenv("VARIABLE_NAME")`. When you copy the code in the following steps, keep the quoted variable names exactly as shown. Do not replace them with your actual credentials.
    </Note>
  </Step>

  <Step title="Authenticate as a service account">
    A company brain is shared, so it should be reached through a shared, governed identity rather than any one person's account. Client Credentials Grant gives your automation - and the agents you connect later - their own **service account** in Box. That service account is the security boundary: it can only touch content you explicitly share with it.

    Create a file called `box_client.py` and add the following code:

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig

    load_dotenv()

    def get_box_client() -> BoxClient:
        config = CCGConfig(
            client_id=os.getenv("BOX_CLIENT_ID"),
            client_secret=os.getenv("BOX_CLIENT_SECRET"),
            enterprise_id=os.getenv("BOX_ENTERPRISE_ID"),
        )
        auth = BoxCCGAuth(config=config)
        return BoxClient(auth=auth)
    ```

    <Warning>
      **Share the company brain with the service account.** A CCG app acts as a separate service account user that does not automatically have access to your content. Invite the service account email as a collaborator on the top-level `Company Brain` folder with the **Editor** role - Editor is required so the app can write metadata and move approved files.

      To find the email: go to the [Developer Console](https://app.box.com/developers/console), open your app, and look in the **App Details** sidebar for the **Service Account ID** (it looks like `AutomationUser_xxxxx_xxxxxx@boxdevedition.com`). Without this, API calls return `404 Not found`.
    </Warning>

    <Tip>
      Sharing only the `Company Brain` folder - not your whole account - is the point. The service account gets exactly the access the brain needs and nothing more. This is the same boundary you rely on later when an agent authenticates as this identity.
    </Tip>
  </Step>

  <Step title="Review staged content with Box AI">
    If an agent can search everything, it can also find the wrong thing - an old scope deck, an unreviewed draft, a template with outdated assumptions. For a person that is annoying; for an agent it is a trust problem. So before a file becomes part of the trusted layer, it goes through an intake review.

    Instead of prompting Box AI with an open-ended question, you define a fixed review schema so every file comes back in the same shape. Create a file called `review.py`:

    ```python theme={null}
    from box_sdk_gen import (
        AiItemBase,
        CreateAiExtractStructuredFields,
        CreateAiExtractStructuredFieldsOptionsField,
    )
    from box_client import get_box_client

    REVIEW_FIELDS = [
        CreateAiExtractStructuredFields(
            key="summary",
            display_name="Summary",
            type="string",
            prompt="A two to three sentence summary of what this document contains.",
        ),
        CreateAiExtractStructuredFields(
            key="suggested_domain",
            display_name="Suggested domain",
            type="enum",
            prompt="The single domain this content best belongs to.",
            options=[
                CreateAiExtractStructuredFieldsOptionsField(key="security"),
                CreateAiExtractStructuredFieldsOptionsField(key="legal"),
                CreateAiExtractStructuredFieldsOptionsField(key="product"),
                CreateAiExtractStructuredFieldsOptionsField(key="other"),
            ],
        ),
        CreateAiExtractStructuredFields(
            key="suggested_tags",
            display_name="Suggested tags",
            type="string",
            prompt="Three to six comma-separated topic tags for retrieval.",
        ),
        CreateAiExtractStructuredFields(
            key="content_health_score",
            display_name="Content health score",
            type="float",
            prompt=(
                "A score from 0 to 100 for how usable this is as trusted knowledge. "
                "Lower the score for stale dates, missing ownership, unclear status, "
                "or content that reads like an unreviewed draft."
            ),
        ),
        CreateAiExtractStructuredFields(
            key="review_notes",
            display_name="Review notes",
            type="string",
            prompt=(
                "Concise notes on any issues an owner should resolve before approval, "
                "such as missing owner, stale dates, duplicate guidance, or draft assumptions."
            ),
        ),
    ]

    def review_file(file_id: str) -> dict:
        client = get_box_client()

        response = client.ai.create_ai_extract_structured(
            items=[AiItemBase(id=file_id)],
            fields=REVIEW_FIELDS,
        )

        return response.to_dict()["answer"]
    ```

    The fixed schema is what makes the review dependable: the same fields, in the same shape, for every file - so the intake step behaves consistently no matter who uploaded the document or how it is formatted.

    <Tip>
      Treat the content health score as a signal, not a verdict. A low score means "an owner should look at this before agents rely on it," which is exactly what the approval step in Step 6 is for.
    </Tip>
  </Step>

  <Step title="Record the review as governance metadata">
    A review is only useful if it stays attached to the file. Writing the result back as a metadata instance means every file carries its own governance record - domain, owner, status, and health - that both people and agents can see, search, and audit.

    Create a file called `intake.py`. It reviews every file in a domain's staging folder and stamps each one with governance metadata:

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import BoxClient, CreateFileMetadataByIdScope

    from box_client import get_box_client
    from review import review_file

    load_dotenv()

    def build_governance(review: dict) -> dict:
        return {
            "domain": review.get("suggested_domain", "other"),
            "owner": "unassigned",
            "status": "staged",
            "contentHealthScore": review.get("content_health_score", 0),
            "summary": review.get("summary", ""),
            "tags": review.get("suggested_tags", ""),
            "reviewNotes": review.get("review_notes", ""),
        }

    def apply_governance(client: BoxClient, file_id: str, governance: dict):
        template_key = os.getenv("BOX_METADATA_TEMPLATE_KEY")
        client.file_metadata.create_file_metadata_by_id(
            file_id=file_id,
            scope=CreateFileMetadataByIdScope.ENTERPRISE,
            template_key=template_key,
            request_body=governance,
        )

    def process_staging_folder(client: BoxClient, folder_id: str):
        items = client.folders.get_folder_items(folder_id).entries

        for item in items:
            if item.type != "file":
                continue

            print(f"\nReviewing: {item.name} ({item.id})")
            review = review_file(item.id)
            governance = build_governance(review)

            print(f"  Domain:  {governance['domain']}")
            print(f"  Health:  {governance['contentHealthScore']}")
            print(f"  Summary: {governance['summary']}")
            if governance["reviewNotes"]:
                print(f"  Notes:   {governance['reviewNotes']}")

            apply_governance(client, item.id, governance)
            print("  Governance metadata applied.")

    def main():
        client = get_box_client()
        staging_folder_id = os.getenv("STAGING_FOLDER_ID")
        process_staging_folder(client, staging_folder_id)

    if __name__ == "__main__":
        main()
    ```

    Upload a document or two to your domain's `_staging` folder in Box, then run:

    ```bash theme={null}
    python3 intake.py
    ```

    For each staged file you see the suggested domain, a health score, a summary, and any review notes - and each file is stamped with a `staged` governance record.

    <Note>
      The intake step sets `status` to `staged` and `owner` to `unassigned` on purpose. A file being uploaded does not make it trusted knowledge. A human still decides what gets approved and who owns it - the next step.
    </Note>

    <Tip>
      To run intake automatically whenever a file lands in staging, trigger it from a folder event instead of running it by hand. See <Link href="/guides/box-automate/index">Box Automate</Link> for event-driven routing and approval tasks, or register a <Link href="/guides/webhooks/v2/signatures-v2">webhook</Link> on the staging folder.
    </Tip>
  </Step>

  <Step title="Approve content and publish it to a domain Hub">
    Once a domain owner is satisfied with a file, it becomes trusted knowledge and needs a destination where both people and agents can find it. A Box Hub is that destination: a curated, permission-inheriting knowledge base for one domain. Pointing agents at a small set of approved content - rather than every file the company has - is what keeps answers grounded and trustworthy.

    Create a file called `publish.py`. It marks a file as approved, moves it into the domain's `approved` folder, and ensures a domain Hub exists and contains that folder:

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        UpdateFileMetadataByIdScope,
        UpdateFileMetadataByIdRequestBody,
        UpdateFileMetadataByIdRequestBodyOpField,
        UpdateFileByIdParent,
        FolderReferenceV2025R0,
        HubItemOperationV2025R0,
        HubItemOperationV2025R0ActionField,
    )

    from box_client import get_box_client

    load_dotenv()

    def approve_file(client: BoxClient, file_id: str, owner: str):
        template_key = os.getenv("BOX_METADATA_TEMPLATE_KEY")
        client.file_metadata.update_file_metadata_by_id(
            file_id=file_id,
            scope=UpdateFileMetadataByIdScope.ENTERPRISE,
            template_key=template_key,
            request_body=[
                UpdateFileMetadataByIdRequestBody(
                    op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
                    path="/status",
                    value="approved",
                ),
                UpdateFileMetadataByIdRequestBody(
                    op=UpdateFileMetadataByIdRequestBodyOpField.REPLACE,
                    path="/owner",
                    value=owner,
                ),
            ],
        )
        print(f"Approved file {file_id}, owner set to {owner}")

    def move_to_approved(client: BoxClient, file_id: str, approved_folder_id: str):
        client.files.update_file_by_id(
            file_id, parent=UpdateFileByIdParent(id=approved_folder_id)
        )
        print(f"Moved file {file_id} to approved folder {approved_folder_id}")

    def create_domain_hub(client: BoxClient, domain: str) -> str:
        hub = client.hubs.create_hub_v2025_r0(
            f"{domain.title()} Knowledge Base",
            description=(
                f"Curated, approved {domain} knowledge for the company brain. "
                "Answers are grounded in reviewed, source-backed content."
            ),
        )
        print(f"Created hub: {hub.title} (ID: {hub.id})")
        return hub.id

    def add_folder_to_hub(client: BoxClient, hub_id: str, folder_id: str):
        client.hub_items.manage_hub_items_v2025_r0(
            hub_id,
            operations=[
                HubItemOperationV2025R0(
                    action=HubItemOperationV2025R0ActionField.ADD,
                    item=FolderReferenceV2025R0(id=folder_id),
                )
            ],
        )
        print(f"Added approved folder {folder_id} to hub {hub_id}")

    def main():
        client = get_box_client()

        approved_folder_id = os.getenv("APPROVED_FOLDER_ID")

        # Replace with a file ID from your staging folder and the accountable owner.
        file_id = "YOUR_FILE_ID"
        owner = "security-team@example.com"
        domain = "security"

        approve_file(client, file_id, owner)
        move_to_approved(client, file_id, approved_folder_id)

        hub_id = create_domain_hub(client, domain)
        add_folder_to_hub(client, hub_id, approved_folder_id)

        print(f"\n{domain.title()} knowledge base ready. Hub ID: {hub_id}")

    if __name__ == "__main__":
        main()
    ```

    Run it once for a file you want to approve:

    ```bash theme={null}
    python3 publish.py
    ```

    Save the hub ID from the output - you need it to query the brain.

    <Note>
      You create a domain's Hub once, then reuse it. In production, look up the existing Hub for a domain and only create one if it does not exist, rather than creating a new Hub on every approval. Adding a folder to a Hub automatically indexes the files within it, and new files added to that folder are picked up automatically.
    </Note>

    <Tip>
      Control who can query the knowledge base by adding Hub collaborations - `viewer` for people who consume knowledge, `editor` for the domain owners who curate it. See <Link href="/guides/hubs-api/hubs-collaborations/hub-collaborations">Manage hub collaborations</Link>.
    </Tip>
  </Step>

  <Step title="Query the company brain">
    With approved content published, both people and agents can ask natural-language questions and get answers grounded in reviewed, source-backed material - with citations back to the files the answer came from. Create a file called `ask.py`:

    ```python theme={null}
    from dotenv import load_dotenv
    from box_sdk_gen import BoxClient, CreateAiAskMode, AiItemAsk

    from box_client import get_box_client

    load_dotenv()

    def ask_company_brain(client: BoxClient, hub_id: str, question: str):
        response = client.ai.create_ai_ask(
            mode=CreateAiAskMode.SINGLE_ITEM_QA,
            prompt=question,
            items=[AiItemAsk(type="hubs", id=hub_id)],
            include_citations=True,
        )
        return response

    def main():
        client = get_box_client()

        hub_id = "YOUR_HUB_ID"  # From Step 7

        questions = [
            "What is our approved policy for handling customer data at rest?",
            "Which security controls must a new integration pass before launch?",
        ]

        for question in questions:
            print(f"\nQ: {question}")
            response = ask_company_brain(client, hub_id, question)
            print(f"A: {response.answer}")

            if response.citations:
                print("Sources:")
                for citation in response.citations:
                    print(f"  - {citation.name}")

    if __name__ == "__main__":
        main()
    ```

    Replace `YOUR_HUB_ID` with the hub ID from the previous step, then run:

    ```bash theme={null}
    python3 ask.py
    ```

    Because the Hub inherits Box permissions, the answer only ever draws on documents the querying identity can access, and each answer lists the approved files it came from. The result is a knowledge base agents can depend on, instead of a guess assembled from a random mix of search results.

    At this point, your project directory should contain the following files:

    ```
    company-brain/
    ├── .env
    ├── .venv/
    ├── ask.py
    ├── box_client.py
    ├── intake.py
    ├── publish.py
    └── review.py
    ```

    <Warning>
      After publishing content to a Hub, allow a few minutes for Box to index the files before querying. Queries against newly added content may return empty or incomplete results until indexing completes.
    </Warning>
  </Step>

  <Step title="Connect your agents to the company brain">
    <Info>
      This step is guidance rather than code you run now. It shows how the same governed brain you just built becomes the memory layer for your agents, wherever they run.
    </Info>

    The whole point of a company brain is that it stays put while the agents change. Different teammates use different tools - a coding agent, a cloud assistant, a workflow bot - and the brain should not have to change as the agent changes; it should keep compounding. Box exposes the same source of truth through two access paths:

    * **Local agents** (for example, a coding agent working against synced files) reach the brain through Box Drive or the <Link href="/guides/cli/index">Box CLI</Link>, treating it like a local repository. Authenticate the CLI as the *service account* from Step 4 so the agent inherits exactly the access you granted the brain. More information is available on how to <Link href="/tutorials/connect-an-agent-to-box#set-up-the-connection">authenticate into Box CLI with a CCG app</Link>.
    * **Cloud agents** (for example, an assistant in a chat app) reach the same content through the <Link href="/guides/box-mcp/index">Box MCP server</Link>, with permission-aware access and admin controls. See more information on how to <Link href="/tutorials/connect-an-agent-to-box#box-mcp-hosted-server">set up the connection with Box MCP</Link>.

    Both are working from the same underlying files, permissions, and versions. Store the rules that govern agent behavior in the `operating-rules` folder so every agent reads the current version from the brain itself. For example:

    ```text theme={null}
    - Always authenticate as the Box service account, never a personal user.
    - Only operate inside the approved folders and Hubs you are given.
    - Answer only from approved content, and cite the source files.
    - Ask before deleting or overwriting content; preserve version history.
    - Save generated outputs back to the outputs folder for reuse.
    ```

    <Tip>
      Version history, review workflows, and audit trails are not extra work you bolt on - they come from Box. When an agent writes an output back to the brain, it inherits the same governance every human contribution does.
    </Tip>
  </Step>

  <Step title="Keep the brain healthy">
    <Info>
      This step provides reference patterns for keeping the knowledge base trustworthy over time. You do not need to run it now.
    </Info>

    The default failure mode of any knowledge base is drift: policies go stale, best practices stay trapped in one team, and approved content slowly ages out of date. A healthy company brain closes the loop - the organization's own work continuously improves it.

    Use the governance metadata you are already writing to surface content that needs attention. A <Link href="/guides/metadata/queries">metadata query</Link> can find every approved file below a health threshold, or every file still `staged` after too long:

    ```python theme={null}
    import os
    from box_sdk_gen import BoxClient

    def find_low_health_content(client: BoxClient, template_key: str, threshold: int = 60):
        enterprise_id = os.getenv("BOX_ENTERPRISE_ID")
        results = client.search.search_by_metadata_query(
            from_=f"enterprise_{enterprise_id}.{template_key}",
            ancestor_folder_id="0",  # search the whole enterprise; scope to the brain folder in production
            query="status = :status AND contentHealthScore < :score",
            query_params={"status": "approved", "score": threshold},
        )
        for entry in results.entries:
            print(f"Needs review: {entry.name} ({entry.id})")
    ```

    Feed those signals back to the domain owner. Every workflow also generates signals worth capturing - missing context, repeated review comments, gaps an agent could not answer. Route them into the next review cycle so the brain gets more valuable the more it is used.

    <Note>
      The `from` value must include your enterprise ID. Use `enterprise_{BOX_ENTERPRISE_ID}.{template_key}` - for example, `enterprise_123456789.knowledgeGovernance`.
    </Note>

    <Tip>
      Pair this with a scheduled review per domain. The owner re-reviews low-health and aging content, updates or archives it, and the Hub reindexes automatically. Ownership is what keeps quality from degrading - assign every domain an accountable owner.
    </Tip>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Configuration.
    * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID (Admin Console > Account & Billing, or Developer Console > icon in the top-right > Copy Enterprise ID).
    * Ensure your app is authorized in the Developer Console and uses Client Credentials Grant.
  </Accordion>

  <Accordion title="404 Not Found">
    The service account does not have access to the folder or file. Invite the service account email (Developer Console > General Settings) as a collaborator with the **Editor** role on the top-level `Company Brain` folder. Because subfolders inherit collaboration, this grants access to every domain, staging, and approved folder inside it.
  </Accordion>

  <Accordion title="metadata_template must have both scope and template_key">
    The `BOX_METADATA_TEMPLATE_KEY` value in your `.env` file is missing or empty. Add the template key you copied when creating the `Knowledge Governance` template in Step 2.
  </Accordion>

  <Accordion title="Metadata write fails with 400 bad_request: Request contains invalid parameters">
    This means the request reached your template (a missing template returns `404`, not `400`), but one of the keys in the payload is not a field in the template, or a value breaks a field's type. The most common cause is a field name mismatch - for example, if the first field was created as `Domain` in the Admin Console, Box generates the key `domain`, but if it was named anything else the key differs and the `domain` key the code sends is rejected.

    Every key in `build_governance` (`domain`, `owner`, `status`, `contentHealthScore`, `summary`, `tags`, `reviewNotes`) must exactly match a field key in your template. Print the actual keys and types to compare:

    ```python theme={null}
    from box_sdk_gen import GetMetadataTemplateScope
    from box_client import get_box_client

    client = get_box_client()
    template = client.metadata_templates.get_metadata_template(
        GetMetadataTemplateScope.ENTERPRISE, "knowledgeGovernance"
    )
    for field in template.fields:
        print(field.type, field.key, "-", field.display_name)
    ```

    Then either rename or add the field in the Admin Console so its key matches (field keys are immutable once created, so add a correctly named field rather than trying to rename the key), or update the dict keys in `build_governance` to match what the template actually uses. A `Number` field also rejects non-numeric values, so make sure the health score is sent as a number.
  </Accordion>

  <Accordion title="Box AI returns empty or irrelevant answers">
    This usually means the Hub content has not finished indexing, or the approved folder is empty:

    * Wait a few minutes after publishing before querying. Indexing is not instantaneous.
    * Verify the approved folder contains files (not just subfolders) and that they contain text (scanned image PDFs without OCR are not searchable).
    * Confirm you are querying the correct hub ID from Step 7.
  </Accordion>
</AccordionGroup>

## Scaling to production

<AccordionGroup>
  <Accordion title="Automate the intake and approval loop">
    Instead of running `intake.py` by hand, trigger the review when a file lands in a `_staging` folder and route the result to the right owner as an approval task. See <Link href="/guides/box-automate/index">Box Automate</Link> for event-driven workflows, or register a <Link href="/guides/webhooks/v2/signatures-v2">webhook</Link> on each staging folder.
  </Accordion>

  <Accordion title="One hub per domain, combined per task">
    Provision a dedicated Hub for each domain and let agents combine the hubs a task needs - a product-planning agent might draw on product, legal, and security, while a code-review agent draws on architecture, security, and accessibility. Loop over your domains to create their folder pairs and Hubs, and give each domain an accountable owner.
  </Accordion>

  <Accordion title="Support conversational follow-ups">
    The `POST /2.0/ai/ask` endpoint accepts a `dialogue_history` parameter carrying previous question-and-answer pairs. Maintain a list of exchanges and pass it with each request so users can ask follow-ups without losing context. See <Link href="/tutorials/sales-rfp-answer-bank">Build a sales RFP answer bank</Link> for a conversational implementation.
  </Accordion>

  <Accordion title="Govern content lifecycle">
    Combine the brain with <Link href="/guides/retention-policies">retention policies</Link> to archive or delete outdated material automatically, and use enterprise events to see which content agents rely on most. Treat the knowledge layer as enterprise infrastructure, not an AI feature - the organizations that build it as a governed, reusable, permission-aware layer gain an advantage every time a new agent enters the business.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Sales RFP answer bank" href={localizeLink("/tutorials/sales-rfp-answer-bank")} icon="magnifying-glass">
    Apply the same Hubs and Box AI pattern to a sales knowledge base, and embed it in your CRM.
  </Card>

  <Card title="Box Hubs API reference" href={localizeLink("/guides/hubs-api/index")} icon="server">
    See the full Hubs API guide for advanced hub management.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Connect an AI agent to Box
Source: https://developer.box.com/tutorials/connect-an-agent-to-box

Connect a coding or autonomous agent to a Box developer account through OAuth with the Box CLI or Box MCP server.

An AI agent is more useful when it can work with the same current content as
your team. This tutorial explains how to connect an agent to an isolated Box
developer account through either the Box CLI or the hosted Box MCP server.

<Note>
  The examples use [Codex](https://developers.openai.com/codex), but the
  connection patterns apply to other agents. Use the **Box CLI** path when an
  agent can run shell commands. Use the **Box MCP** path when an agent supports
  the Model Context Protocol.
</Note>

## What you are building

By the end of this tutorial, your agent can read, search, upload, organize, and
use Box AI with Box content.

<CardGroup>
  <Card title="Box CLI path" icon="terminal" href="#set-up-the-connection">
    Sign in with OAuth on the agent's local computer, a remote host, or a
    headless container.
  </Card>

  <Card title="Box MCP path" icon="plug" href="#set-up-the-connection">
    Connect the hosted Box MCP server with OAuth. The Box user you authorize
    determines the content available to the agent.
  </Card>
</CardGroup>

## Authentication and access boundaries

Both paths in this tutorial use OAuth. The agent acts as the Box user who
completes the OAuth flow and can access the content available to that user,
subject to the integration's scopes and Box security policies.

The Box CLI's built-in OAuth application supports files and folders, Box AI,
and Box Sign. Box MCP uses the scopes configured for the integration. Neither
path restricts the agent to a single folder when you authorize your own user.

<Warning>
  Use a fresh [Box developer account](https://account.box.com/signup/developer)
  that contains only sample content. Do not use this tutorial to connect an
  agent to a production Box enterprise, your everyday Box account, or sensitive
  content.
</Warning>

For production - e.g. a chosen Box user or service account, least-privilege scopes, and
unchanged waterfall permissions - see
[Give an AI agent secure, permission-aware access to enterprise documents](/guides/box-mcp/permission-aware-access).

## Choose the right path

Both paths use the same developer-account user but expose Box through different
interfaces.

| | Box CLI | Box MCP |
| - | - | - |
| Interface | Shell commands | MCP tools |
| OAuth login | `box login` locally or `box login --code` on a headless runtime | Browser authorization through the MCP client |
| Content access | Content available to the signed-in Box user | Content available to the signed-in Box user |
| Recommended use | Agents that can run terminal commands | MCP-native agents and chat clients |

Choose the **Box CLI** path if your agent runs in a terminal or on a server, or
inside a container. Choose the **Box MCP** path if your agent is MCP-native.

## Prerequisites

<Steps>
  <Step title="An isolated Box developer account">
    Create a free [Box developer account](https://account.box.com/signup/developer)
    specifically for testing. Add only sample content that you are comfortable
    making available to the agent. The account works for both paths and gives
    you the admin access needed to enable the MCP integration yourself.
  </Step>

  <Step title="Your agent, installed and working">
    Use any coding or autonomous agent. Confirm it runs and responds before you
    connect Box.

    <Accordion title="Example: installing Codex">
      ```bash theme={null}
      # via npm
      npm install -g @openai/codex

      # or via Homebrew
      brew install codex

      codex --version
      ```

      Swap these for your own agent's install steps. Claude Code, Cursor, Hermes, Pi, and OpenClaw each have their own.
    </Accordion>
  </Step>

  <Step title="Basic terminal familiarity">
    You'll run a handful of commands. For a remote login, you also need access
    to a browser on another computer.
  </Step>
</Steps>

## Set up the connection

<Tabs>
  <Tab title="Box CLI (OAuth)">
    The Box CLI turns Box into a headless, scriptable surface. Any agent that can
    run shell commands can then read, upload, search, and organize Box content by
    calling a `box` command.

    The CLI can also call Box AI. The `box ai:ask`, `box ai:text-gen`, and
    `box ai:extract` commands send requests to the Box AI API for content stored in
    Box.

    <Note>
      A free developer account includes 1,000 AI Units each month for testing Box AI
      capabilities. Higher-tier Enterprise plans offer increased AI query limits and
      advanced capabilities. Enable the AI API for your account before using these
      commands.
    </Note>

    You'll authenticate the CLI with OAuth as your developer-account user. The
    correct login command depends on whether a browser is available on the machine
    where the agent and CLI run.

    <Steps>
      <Step title="Install the Box CLI">
        Install the CLI on the machine where the agent runs:

        ```bash theme={null}
        npm install --global @box/cli
        box --version
        ```
      </Step>

      <Step title="Log in with OAuth">
        Choose the instructions that match where the Box CLI and agent run.

        <AccordionGroup>
          <Accordion title="Local computer with a browser">
            Run the standard login command on the same computer as the agent:

            ```bash theme={null}
            box login
            ```

            At the authentication-method prompt, choose the official Box CLI
            application. The CLI opens your browser and starts a local callback
            server. Sign in with your isolated developer-account user and select
            **Grant Access to Box**. The browser returns the authorization response
            directly to the CLI.
          </Accordion>

          <Accordion title="VPS, remote host, or headless container">
            Start a manual-code login on the remote runtime:

            ```bash theme={null}
            box login --code
            ```

            The runtime does not need a browser, but a person must still complete
            the OAuth authorization in a browser on another computer.

            At the authentication-method prompt, choose the official Box CLI
            application. The CLI prints an authorization URL and waits for input:

            1. Copy the URL and open it in a browser on your local computer.
            2. Sign in with your isolated developer-account user and select
               **Grant Access to Box**.
            3. The browser redirects to a `localhost` URL that contains `code` and
               `state` query parameters. The page fails to load because the callback
               server is not running on your local computer. This is expected.
            4. Copy the `code` and `state` values from the browser's address bar and
               enter them in the remote CLI when prompted.

            For the complete flow, see
            [Login for headless environments](/guides/cli/headless-login).

            <Warning>
              In a container, persist the CLI's authentication state in a protected
              volume so it survives restarts. Never bake tokens or CLI
              authentication data into a container image or commit them to source
              control. If the stored OAuth session is removed or can no longer be
              refreshed, run `box login --code` again.
            </Warning>
          </Accordion>
        </AccordionGroup>
      </Step>

      <Step title="Verify the Box user">
        Confirm that the active CLI session uses your developer-account user:

        ```bash theme={null}
        box users:get me
        ```

        <Check>
          The response should show the name and login of the Box user that completed
          OAuth. This is the identity your agent uses for every Box CLI command.
        </Check>
      </Step>

      <Step title="Connect the agent and inspect access">
        Add instructions for your agent. In Codex, add them to `AGENTS.md` in the
        working directory:

        ```markdown theme={null}
        ## Box access
        - Use the Box CLI for Box operations.
        - Use the currently authenticated OAuth session. Do not add or switch credentials.
        - Operate only on Box items explicitly named in the task.
        - Ask before deleting, moving, or overwriting content.
        ```

        Then enter this prompt in the agent chat to confirm the identity and content
        available to it:

        ```text theme={null}
        Use the Box CLI to show the authenticated Box user, then list the items at
        the root level.
        ```

        The agent should identify your developer-account user and list the sample
        content in the account. In the background, it executes these CLI commands:

        ```bash theme={null}
        box users:get me
        box folders:items 0
        ```
      </Step>

      <Step title="Put it to work">
        Enter each prompt in the agent chat in order; each builds on the last:

        1. ```text theme={null}
           Create a short product-launch brief and a separate notes file in the
           root of my Box account.
           ```
        2. ```text theme={null}
           Read the product-launch brief and notes in the root of my Box account,
           draft a one-page status summary, and save it at the root.
           ```
      </Step>
    </Steps>

    <Accordion title="Troubleshoot the CLI path">
      * **No browser opens on the runtime**: use `box login --code` and complete
        authorization in a browser on another computer.
      * **The localhost redirect fails during `--code` login**: this is expected.
        Copy the `code` and `state` values from the URL into the CLI.
      * **The CLI shows the wrong user**: start a new login and authorize with the
        isolated developer-account user.
      * **The OAuth session is no longer valid**: run the appropriate `box login`
        command again.
      * **Box AI permission error**: confirm that the AI API is enabled for your
        developer account.
    </Accordion>
  </Tab>

  <Tab title="Box MCP (hosted server)">
    The [Model Context Protocol](https://modelcontextprotocol.io) allows an agent to
    use Box tools for search, Box AI, and file and folder operations. Box hosts the
    server at `https://mcp.box.com`.

    The Box user who completes OAuth determines what the agent can access. For this
    tutorial, sign in with the user from your isolated developer account.

    <Info>
      Any MCP client can connect to Box through `https://mcp.box.com` and OAuth.
      This example uses the Box plugin for Codex. See the
      [Box MCP platform setup guides](/guides/box-mcp/index#platform-setup-guides)
      for other clients.
    </Info>

    <Steps>
      <Step title="Enable the integration">
        <Badge>Admin</Badge>

        You are the admin of your free developer account, so you can complete this
        step yourself:

        1. Sign in to the [Box Admin Console](https://app.box.com/master).
        2. Select **Integrations** in the left navigation, then search for
           **ChatGPT** and set its availability to the users who need it. For a
           different MCP client, enable that client's integration instead.
        3. Select **Box AI** in the left navigation, then open **Settings**. Enable
           **AI API** and **Official Box Integrations** for the required users or for all
           users.
      </Step>

      <Step title="Confirm the Box user for OAuth">
        Use the user from your isolated developer account. The agent can access the
        content available to this user, so confirm that the account contains only
        sample content before continuing.
      </Step>

      <Step title="Install the Box plugin">
        Open the Codex app or start a Codex CLI chat. In the chat input, enter:

        ```text theme={null}
        /plugins
        ```

        Open the plugin marketplace, search for **Box**, and install the plugin.
        Complete the OAuth flow with the Box user selected in the previous step.

        <Note>
          Using a different agent? You can connect to the same server
          (`https://mcp.box.com`) elsewhere: in Claude, add Box under **Connectors**;
          in Cursor, add it as a
          remote MCP server; other platforms follow their own "add MCP server" flow and
          then the same OAuth sign-in.
        </Note>
      </Step>

      <Step title="Confirm the MCP server">
        In the same agent chat, enter:

        ```text theme={null}
        /mcp
        ```

        Confirm that the Box server is connected and that its tools are available.

        <Check>
          You should see the Box server connected, exposing tools such as
          `search_files_keyword`, `ai_qa_single_file`, `upload_file`, and
          `list_folder_content_by_folder_id`.
        </Check>
      </Step>

      <Step title="Confirm the agent's access and run a task">
        In the agent chat, enter:

        ```text theme={null}
        Use the Box tools to identify the authenticated Box user and list the items
        at the root level. Report the user name and each folder name.
        ```

        The agent should identify your developer-account user and list the sample
        content available to that user.

        Then enter these prompts in the agent chat:

        1. ```text theme={null}
           Create a short product-launch brief and a separate notes file in the
           root of my Box account.
           ```
        2. ```text theme={null}
           Read the product-launch brief and notes in the root of my Box account,
           draft a one-page status summary, and save it at the root.
           ```
      </Step>
    </Steps>

    <Accordion title="Troubleshoot the MCP path">
      * **The integration is unavailable**: verify the integration and Box AI
        settings in the Admin Console.
      * **The agent has broader access than expected**: disconnect and reconnect
        with the intended Box user.
      * **Restrict available tools**: configure the MCP client to allow only the
        tools the agent needs. In Codex, configure this in `~/.codex/config.toml`.
    </Accordion>
  </Tab>
</Tabs>

## Plan a production agent identity

This tutorial uses user OAuth in an isolated developer account so that you
can evaluate the connection without creating a server-authentication app. Do not
copy this authentication design into a production workflow without reviewing
the identity, scopes, credentials, and content boundary with your Box Admin and
security team.

The Box user types relevant to an agent integration are:

| User type | Interactive login | How it is created | Production considerations |
| - | - | - | - |
| Managed User | Yes | Provisioned in a Box enterprise | Can complete OAuth for the CLI or MCP. The agent receives the content access of that user and the user consumes a Box seat. |
| Service Account | No; API only | Generated when an Admin authorizes a CCG or JWT app | Represents the server app. Its capabilities depend on app scopes and access settings, and it can perform Admin-level actions when elevated permissions are enabled. |
| App User | No; API only | Created through the API by an authorized app's Service Account | Provides a separate folder tree and identity for a process, agent, or tenant. It cannot sign in to Box or complete MCP OAuth. |

For a production agent, an organization may choose to have its Admin or platform
team authorize a server app and provision an App User for the agent. An App User
does not remove the Service Account or the parent CCG or JWT application from
the architecture. The Service Account creates the App User, and the authorized
application obtains tokens for it.

<Warning>
  Do not give a shell-capable agent direct access to the parent application's
  client secret, private key, or unrestricted Service Account credentials. Keep
  parent credentials under platform-team control, request only the minimum
  scopes, keep the application at **App Access Only** unless broader access is
  required, and expose narrowly scoped operations or short-lived tokens to the
  agent through an organization-approved runtime.
</Warning>

CCG and JWT apps always require explicit Admin authorization in a managed
enterprise because their Service Accounts can receive elevated permissions.
App User provisioning, credential brokering, monitoring, and revocation are
production architecture concerns and are outside this tutorial. To design that
flow, see [Box user types](/guides/getting-started/users),
[create an App User](/guides/users/create-app-user),
[select an authentication method](/guides/authentication), and
[Platform App approval](/guides/authorization/platform-app-approval).

## Use cases

* **Content and launch work**: create captions, descriptions, and review notes
  from the current project files.
* **Living documents**: assemble a release checklist from the current
  specification, mockups, and quality-assurance notes.
* **Engineering context**: give an agent access to current design documents,
  incident notes, and other maintained technical content.
* **Legal and contracts**: compare the current redline with a previous version
  and flag changed clauses for human review.

## Related resources

<CardGroup>
  <Card title="Box CLI docs" icon="terminal" href="https://developer.box.com/guides/cli">
    Command reference and authentication options.
  </Card>

  <Card title="Headless CLI login" icon="server" href="/guides/cli/headless-login">
    Complete OAuth when the CLI runs on a VPS or in a container.
  </Card>

  <Card title="Box MCP server" icon="plug" href="https://developer.box.com/guides/box-mcp">
    Hosted server, supported platforms, and available tools.
  </Card>

  <Card title="Box user types" icon="users" href="/guides/getting-started/users">
    Compare Managed Users, Service Accounts, and App Users.
  </Card>
</CardGroup>


# Build a document dashboard with the Content Explorer metadata view
Source: https://developer.box.com/tutorials/explorer-metadata-view

Embed the enhanced metadata view of the Box Content Explorer to browse, filter, and edit documents by their metadata, with a single setup script and one HTML page.

Any set of documents in Box gets harder to work through as it grows, even when the metadata is all there. A filterable, sortable, editable grid over that metadata normally means weeks of front-end work. The <Link href="/guides/embed/ui-elements/explorer-metadata-v2">enhanced metadata view (v2)</Link> of the Box Content Explorer provides that grid as a single embeddable component: filters for every field, sorting, list and grid layouts, and metadata editing in a side panel. This tutorial uses invoices as the example, though the same page fits contracts, claims, or anything else with a metadata template.

Box AI fills the grid for you: a setup script reads the fields straight out of the documents and stores them as metadata, so the table shows real data rather than values you typed in. In about 15 minutes, you have a working invoice dashboard, with no backend and no build tooling.

<SignupCTA>
  A free developer account gives you access to the Developer Console, admin rights in your own Box environment, and a developer token — everything you need to create the metadata template and embed the Content Explorer in this tutorial.
</SignupCTA>

<Card title="Clone the working sample" href="https://github.com/box-community/box-document-metadata-dashboard" icon="github">
  Prefer to start from running code? The setup script and webpage built in this tutorial are on GitHub. Clone the repo, add your Box credentials, and run.
</Card>

## What you are building

By the end of this tutorial, you have:

* A minimal `Invoice` metadata template created entirely from code.
* The invoice files in your folder tagged with vendor, invoice number, amount, and status — values that Box AI reads from the documents themselves.
* A single HTML page that embeds the Content Explorer metadata view (v2) so you can filter, sort, and edit those invoices in the browser.

<Frame>
  <img alt="Content Explorer metadata view listing five invoices, with filter chips for each field and columns for vendor, invoice number, amount, and status. The selected row opens a metadata panel for inline editing." />
</Frame>

## Prerequisites

Before you start, you need:

* A **free** <Link href="https://account.box.com/signup/developer">Box developer account</Link>. It gives you admin rights in your own Box environment, which lets you create metadata templates, and it includes free AI units this tutorial uses.
* A platform app that uses **User Authentication (OAuth 2.0)** in the <Link href="https://account.box.com/developers/console">Developer Console</Link>. See <Link href="/guides/getting-started/first-application">Create your first application</Link>.
* A Box folder that contains a few invoice files in a format Box AI can read, such as PDF, DOCX, or a scanned image. See <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured#supported-file-formats">supported file formats</Link>. Note the folder ID from the URL. For example, for `https://app.box.com/folder/123456789`, the ID is `123456789`.
* Node.js 22 or later.

<Tip>
  No invoices to test with? Download these <Link href="/static/tutorials/explorer-metadata-view/box-sample-invoices.zip">sample invoices</Link> (`INV-1001.pdf` through `INV-1005.pdf`) and unzip them. The samples are billed in different currencies, so the **Amount** column mixes them. Add a currency field to the template if you want to compare amounts directly.
</Tip>

Get those files into your folder in either of these ways:

* **In the Box web app**, open the folder and select **Upload** > **Files**, or drag the files onto the folder.
* **From the API**, upload each file to the folder ID you noted. See <Link href="/guides/uploads/direct/file">Upload a new file</Link>.

The setup script calls <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured">Box AI structured extraction</Link> once per document, which consumes AI units. Your developer account includes 1,000 AI units per month, so the five sample invoices use only a small part of your monthly allowance.

This tutorial uses a short-lived <Link href="/guides/authentication/tokens/developer-tokens">developer token</Link> for everything: the setup script and the webpage both authenticate with it. You generate that token yourself in the Developer Console, so you don't have to implement the OAuth 2.0 redirect flow to try this out.

Developer tokens suit prototypes only. For production, pick an authentication method that fits your app and downscope the token before it reaches the browser. See the <Link href="/guides/authentication">authentication overview</Link> and [Scaling to production](#scaling-to-production).

<Warning>
  Developer tokens expire after **60 minutes**. If a call starts failing with `401 Unauthorized`, generate a fresh token in the Developer Console, and then update it in `.env` and in `index.html`.
</Warning>

## Step-by-step process

This tutorial uses four Box capabilities:

| Component | Purpose | API |
| - | - | - |
| **Metadata templates** | Define the invoice fields the view displays | `POST /2.0/metadata_templates/schema` |
| **Box AI Extract** | Read those fields out of each invoice document | `POST /2.0/ai/extract_structured` |
| **File metadata** | Tag each invoice in your folder with the extracted values | `POST /2.0/files/:id/metadata/:scope/:template` |
| **Content Explorer (metadata view v2)** | Render the metadata table in the browser | Box UI Elements (CDN) |

<Steps>
  <Step title="Allowlist localhost and get a developer token">
    1. Open your app in the <Link href="https://account.box.com/developers/console">Developer Console</Link>.
    2. Go to **Configuration** > **CORS Domains** and add the origin you serve the page from:

    ```text theme={null}
    http://localhost:8080
    ```

    <Warning>
      The metadata view calls `api.box.com` **directly from the browser**. Box rejects those calls with `403 Forbidden` unless the exact serving origin (scheme, host, and port) is on the CORS allowlist. `http://localhost:8080` and `http://127.0.0.1:8080` are different origins; add whichever you open.
    </Warning>

    3. In **Configuration** > **Application Scopes**, enable the following scopes:
       * Read and write all files and folders stored in Box
       * Manage AI

    4. Select **Save Changes**.

    5. In **Configuration** > **App Details** > **Access**, locate the **Developer Token** field, select **Generate Developer Token**, and copy the value. You need it in the next steps.

    <Note>
      Generate the token last. If you change and save your app configuration afterwards, generate a fresh token before you carry on.
    </Note>
  </Step>

  <Step title="Set up the project and run the setup script">
    1. Create a project directory and install the SDK:

    ```bash theme={null}
    mkdir invoice-explorer && cd invoice-explorer
    npm init -y
    npm install box
    ```

    <Info>
      The <Link href="/guides/tooling/box-npm-package">box</Link> package installs the Box Node SDK and the Box CLI as direct dependencies. Existing projects can keep using `npm install box-node-sdk`.
    </Info>

    2. In the project directory, create a file called `.env` that holds your credentials, so they stay out of your code:

    ```text theme={null}
    BOX_DEVELOPER_TOKEN=YOUR_DEVELOPER_TOKEN
    BOX_FOLDER_ID=YOUR_FOLDER_ID
    ```

    <Warning>
      `.env` holds a live credential. Add it to `.gitignore` before you commit anything.
    </Warning>

    3. In the same directory, create a file called `setup.js` and paste the following code. The script creates the <Link href="/guides/metadata/templates/create">metadata template</Link>, asks Box AI to read those fields out of each document in your folder, writes the results back as metadata, and prints the configuration values the webpage needs.

    ```javascript theme={null}
    const { BoxClient, BoxDeveloperTokenAuth } = require("box/sdk");

    const ACCESS_TOKEN = process.env.BOX_DEVELOPER_TOKEN;
    const FOLDER_ID = process.env.BOX_FOLDER_ID;
    const TEMPLATE_KEY = "invoice";

    async function main() {
      if (!ACCESS_TOKEN || !FOLDER_ID) {
        throw new Error("Set BOX_DEVELOPER_TOKEN and BOX_FOLDER_ID in .env.");
      }

      const client = new BoxClient({
        auth: new BoxDeveloperTokenAuth({ token: ACCESS_TOKEN }),
      });

      // 1. Create the Invoice metadata template, or reuse it if it already exists.
      let template;
      try {
        template = await client.metadataTemplates.createMetadataTemplate({
          scope: "enterprise",
          displayName: "Invoice",
          templateKey: TEMPLATE_KEY,
          fields: [
            { type: "string", key: "vendor", displayName: "Vendor" },
            { type: "string", key: "invoiceNumber", displayName: "Invoice Number" },
            { type: "float", key: "amount", displayName: "Amount" },
            {
              type: "enum",
              key: "status",
              displayName: "Status",
              options: [{ key: "Paid" }, { key: "Pending" }, { key: "Overdue" }],
            },
          ],
        });
        console.log(`Created template '${template.templateKey}'`);
      } catch {
        template = await client.metadataTemplates.getMetadataTemplate(
          "enterprise",
          TEMPLATE_KEY
        );
        console.log(`Template '${template.templateKey}' already exists, reusing it.`);
      }

      const scope = template.scope; // for example, "enterprise_123456"

      // 2. Read the files already in your folder. This returns the first page
      // only, which is 100 items unless you pass a larger limit.
      const items = await client.folders.getFolderItems(FOLDER_ID);
      const files = items.entries.filter((entry) => entry.type === "file");
      if (files.length === 0) {
        throw new Error(
          `Folder ${FOLDER_ID} has no files. Add a few invoices and run again.`
        );
      }

      // 3. Extract the template fields from each document with Box AI, then
      // write them back as metadata. Box AI takes one file per request.
      for (const file of files) {
        let extracted;
        try {
          const response = await client.ai.createAiExtractStructured({
            items: [{ id: file.id, type: "file" }],
            metadataTemplate: {
              templateKey: TEMPLATE_KEY,
              type: "metadata_template",
              scope: scope,
            },
          });
          extracted = response.answer;
        } catch (error) {
          console.log(`  Skipped ${file.name}: extraction failed (${error.message})`);
          continue;
        }

        // Keep only the fields Box AI actually read, so the metadata request
        // doesn't carry empty values.
        const metadata = Object.fromEntries(
          Object.entries(extracted).filter(
            ([, value]) => value !== null && value !== ""
          )
        );

        if (Object.keys(metadata).length === 0) {
          console.log(`  Skipped ${file.name}: no fields found.`);
          continue;
        }

        try {
          await client.fileMetadata.createFileMetadataById(
            file.id,
            "enterprise",
            TEMPLATE_KEY,
            metadata
          );
          console.log(`  Tagged ${file.name}: ${JSON.stringify(metadata)}`);
        } catch (error) {
          console.log(`  Skipped ${file.name}: ${error.message}`);
        }
      }

      // 4. Print the values to paste into index.html.
      console.log("\n--- Paste these into index.html ---");
      console.log(`FOLDER_ID     = ${FOLDER_ID}`);
      console.log(`METADATA_FROM = ${scope}.${TEMPLATE_KEY}`);
    }

    main().catch((error) => {
      console.error(error.message);
      process.exit(1);
    });
    ```

    4. Run the script. Node reads your credentials straight out of `.env`:

    ```bash theme={null}
    node --env-file=.env setup.js
    ```

    Extraction takes a few seconds per document. The output shows the values Box AI read from each file, followed by the two values you need next:

    ```text theme={null}
    Created template 'invoice'
      Tagged INV-1001.pdf: {"vendor":"Acme Solutions Inc.","invoiceNumber":"INV-1001","amount":1250,"status":"Paid"}
      Tagged INV-1002.pdf: {"vendor":"Acme Solutions Inc.","invoiceNumber":"INV-1002","amount":3480.5,"status":"Pending"}
      Tagged INV-1003.pdf: {"vendor":"Acme Solutions Inc.","invoiceNumber":"INV-1003","amount":980,"status":"Overdue"}
      Tagged INV-1004.pdf: {"vendor":"Acme Solutions Inc.","invoiceNumber":"INV-1004","amount":7200,"status":"Paid"}
      Tagged INV-1005.pdf: {"vendor":"Acme Solutions Inc.","invoiceNumber":"INV-1005","amount":450.75,"status":"Pending"}

    --- Paste these into index.html ---
    FOLDER_ID     = 987654321
    METADATA_FROM = enterprise_123456.invoice
    ```

    <Note>
      Passing `metadataTemplate` instead of `fields` means the template you just created also serves as the extraction schema, so Box AI returns values that already match the field keys and types the metadata view expects. Box AI leaves off anything it can't find, and you can fill those fields in manually in the metadata view after it loads.
    </Note>

    <Note>
      You create templates in the `enterprise` scope, and the API returns that scope as `enterprise_123456`, where the number is your enterprise ID. Other scopes exist, such as the read-only `global` scope that holds `global.properties`, so don't hard-code the `enterprise_` prefix. The metadata view needs the full `scope.templateKey` string, which the script prints for you. See <Link href="/guides/metadata/scopes">Metadata scopes</Link>.
    </Note>
  </Step>

  <Step title="Create the webpage">
    Create a file called `index.html` in the same directory. Replace the three placeholder values at the top of the script (`ACCESS_TOKEN`, `FOLDER_ID`, and `METADATA_FROM`) with your developer token and the values the setup script printed.

    <Note>
      This page reads its token from the file rather than from `.env`, because a static page has no server to read `.env` for it. Every UI Element needs a token in the browser, so production apps mint a downscoped one server-side instead of shipping the file. See [Scaling to production](#scaling-to-production).
    </Note>

    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en-US">
      <head>
        <meta charset="utf-8" />
        <title>Invoice explorer</title>
        <!-- Box UI Elements v24.0.0 or higher is required for the metadata view v2 -->
        <link
          rel="stylesheet"
          href="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.css"
        />
        <style>
          html, body { margin: 0; height: 100%; }
          body {
            padding: clamp(12px, 2.5vh, 40px) clamp(12px, 2vw, 32px);
            box-sizing: border-box;
          }
          .container {
            height: 100%;
            max-width: 1440px;
            margin: 0 auto;
          }
        </style>
      </head>
      <body>
        <div class="container"></div>

        <script src="https://cdn01.boxcdn.net/platform/elements/26.3.0/en-US/explorer.js"></script>
        <script>
          // Prototype only. In production, serve a downscoped token from your
          // backend and keep your app credentials server-side.
          const ACCESS_TOKEN = "YOUR_DEVELOPER_TOKEN";
          const FOLDER_ID = "YOUR_FOLDER_ID";
          const METADATA_FROM = "enterprise_123456.invoice"; // scope.templateKey

          // Fully qualified metadata field IDs: metadata.<scope>.<templateKey>.<field>
          const field = (key) => `metadata.${METADATA_FROM}.${key}`;

          const columns = [
            { textValue: "Vendor", id: field("vendor"), type: "string", allowsSorting: true },
            { textValue: "Invoice Number", id: field("invoiceNumber"), type: "string", allowsSorting: true },
            { textValue: "Amount", id: field("amount"), type: "number", allowsSorting: true },
            { textValue: "Status", id: field("status"), type: "singleSelect", allowsSorting: true },
          ];

          const contentExplorer = new Box.ContentExplorer();
          contentExplorer.show(FOLDER_ID, ACCESS_TOKEN, {
            container: ".container",
            defaultView: "metadata",
            metadataQuery: {
              from: METADATA_FROM,
              ancestor_folder_id: FOLDER_ID,
              fields: columns.map((c) => c.id),
            },
            features: {
              contentExplorer: {
                metadataViewV2: true, // required to enable the enhanced view
              },
            },
            metadataViewProps: {
              columns,
              isSelectionEnabled: true, // enables row selection, which activates the Metadata button
            },
          });
        </script>
      </body>
    </html>
    ```

    <Note>
      The column `type` values use the metadata view's own vocabulary, which differs slightly from the template field types: a template `float` field maps to a `number` column, and an `enum` field maps to a `singleSelect` column. The supported column types are `string`, `number`, `date`, `singleSelect`, and `multiSelect`.
    </Note>
  </Step>

  <Step title="Serve the page and explore">
    Serve the static HTML over HTTP so the origin matches your CORS allowlist. Don't open the HTML file directly in the browser (for example, with a `file://` URL). From the project directory, start a static server on port 8080:

    ```bash theme={null}
    npx serve -l 8080
    ```

    <Note>
      `npx` downloads `serve` the first time you run it and asks you to confirm. Any static server works, as long as it serves the page on the port you allowlisted. If port 8080 is already in use, `serve` starts on a different port and prints that address instead, so check its output before you go to the page: a different port is a different origin, and Box rejects the API calls.
    </Note>

    Go to <Link href="http://localhost:8080">[http://localhost:8080](http://localhost:8080)</Link>. The page shows your invoices in a metadata table. From here you can:

    * **Filter** by vendor, amount, or status by using the filter chips in the action bar.
    * **Sort** any column by selecting its header.
    * **Toggle** between list and grid layouts.
    * **Select** a row, and then select **Metadata** in the header and **Edit** in the panel that opens. You edit values in that panel, not in the grid cells.

    <Tip>
      The view writes your changes straight back to Box metadata. Refresh the page (or query the folder from the API) to confirm that the edits persisted.
    </Tip>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="403 Forbidden in the browser console (calls to api.box.com)">
    The serving origin isn't on the CORS allowlist. Add the **exact** origin you opened (for example, `http://localhost:8080`) under **CORS Domains** in the Developer Console, select **Save Changes**, wait a minute, and then reload. Remember that `localhost` and `127.0.0.1` are different origins, and that a static server falls back to another port when the one you asked for is taken, so confirm the address your server printed.
  </Accordion>

  <Accordion title="401 Unauthorized">
    Your developer token expired (developer tokens last 60 minutes) or you pasted it incorrectly. Generate a fresh token in the Developer Console, and then update `BOX_DEVELOPER_TOKEN` in `.env` and `ACCESS_TOKEN` in `index.html`.
  </Accordion>

  <Accordion title="Box AI returned no fields, or the wrong ones">
    Box AI reads text from a broad range of documents, images, and spreadsheets, and applies OCR to image files and scanned documents, but a file in an unsupported format returns nothing. Check your files against the <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured#supported-file-formats">supported file formats</Link>. If the file is readable but the values are off, the layout may be ambiguous. Add a `description` to each template field, or switch from `metadataTemplate` to an explicit `fields` array, where each field also takes a `prompt` that describes how to find and format the value. See <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured">Extract structured metadata</Link>.
  </Accordion>

  <Accordion title="The script skips every file with a 409 conflict">
    The files already carry the `Invoice` template, which is what happens when you run `setup.js` a second time. Writing metadata fails when an instance already exists, so the script reports `409 tuple_already_exists` and keeps the values already on the file. Those values still appear in the metadata view, so you can safely ignore a repeat run. To extract everything again, remove the existing metadata first, either from the metadata panel in the Box web app or with <Link href="/reference/delete-files-id-metadata-id-id">Remove metadata instance from file</Link>, and then run `setup.js` again.
  </Accordion>

  <Accordion title="The table is empty">
    Confirm that `METADATA_FROM` matches the `scope.templateKey` the setup script printed, and that `FOLDER_ID` is the folder that contains your invoices. The `metadataQuery.from` and `ancestor_folder_id` values must point to the folder that holds the tagged files.
  </Accordion>

  <Accordion title="Nothing renders, or the console shows Box is not defined">
    The CDN scripts didn't load, or the version is too old. The metadata view v2 requires Box UI Elements **v24.0.0 or higher**. Check the `explorer.js` and `explorer.css` URLs and your network tab.
  </Accordion>

  <Accordion title="You don't have permission to create metadata templates">
    A developer token belongs to the account you were signed in with when you generated it in the Developer Console. If you were signed in as a different Box user, the token doesn't carry the admin rights that template creation needs. Sign in with your developer account, generate a fresh token, and then run the script again.
  </Accordion>
</AccordionGroup>

## Scaling to production

<AccordionGroup>
  <Accordion title="Replace the developer token with a real authentication flow">
    Developer tokens are for prototyping only. In production, mint a short-lived, **downscoped** token server-side and pass it to the browser; never ship a full-privilege token to the client. See <Link href="/guides/authentication/tokens/downscope">Downscope a token</Link> and <Link href="/guides/embed/ui-elements/scopes">UI Elements scopes</Link>.
  </Accordion>

  <Accordion title="Tag documents as they arrive">
    This script extracts metadata for a folder on demand. In production, trigger the same extraction from a `FILE.UPLOADED` webhook so every new document is tagged when it arrives, and the metadata view stays current without anyone running a script. See <Link href="/tutorials/invoice-intake">Automate invoice intake</Link>.
  </Accordion>

  <Accordion title="Improve extraction accuracy">
    For dense or inconsistent documents, replace `metadataTemplate` with an explicit `fields` array so you can attach a `description` and `prompt` to each field, request confidence scores with `includeConfidenceScore`, and route low-confidence results to a human. The Enhanced Extract Agent handles longer and more complex documents. See <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured">Extract structured metadata</Link>.
  </Accordion>

  <Accordion title="Filter the query server-side">
    For large folders, narrow the result set with the `query` and `query_params` fields of `metadataQuery` (for example, only `Overdue` invoices). See the <Link href="/reference/post-metadata-queries-execute-read/">Metadata Query API</Link>.
  </Accordion>

  <Accordion title="Use React instead of the CDN">
    For a componentized app, import `ContentExplorer` from the `box-ui-elements` package and pass the same `metadataQuery` and `metadataViewProps`. You get an embeddable dashboard component you can drop into an existing app. See the React setup in the <Link href="/guides/embed/ui-elements/explorer-metadata-v2">metadata view v2 guide</Link>.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Invoice intake automation" href={localizeLink("/tutorials/invoice-intake")} icon="file-invoice">
    Run the same extraction from a webhook so documents are tagged as they arrive, instead of on demand.
  </Card>

  <Card title="Metadata view v2 guide" href={localizeLink("/guides/embed/ui-elements/explorer-metadata-v2")} icon="table">
    See every configuration option for the enhanced Content Explorer metadata view.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Extract EXIF metadata with Box representations
Source: https://developer.box.com/tutorials/extract-exif-metadata

Extract embedded technical metadata such as EXIF, then write selected fields to a Box metadata template so you can filter them in a Box Apps dashboard.

This script extracts embedded technical metadata (EXIF, ICC Profile, JFIF, and related fields), writes selected values to a metadata template, and lets you filter those images in a Box Apps dashboard.

<Note>
  You can generate `embedded_metadata` representations for any file type in Box. The set of attributes depends on the file. Not every file includes every EXIF, JFIF, ICC, or MakerNotes field, and some tools strip this data, so not all files return useful metadata.
</Note>

## Before you start

Complete these Box setup steps before you build. You need:

* A <Link href="https://account.box.com/signup/developer#ty9l3">free Box developer account</Link>, or a <Link href="https://www.box.com/pricing">Box Enterprise account</Link>.
* A Box application configured with **Client Credentials Grant** authentication, authorized in the Admin Console, with this scope:
  * Read and write all files and folders stored in Box
* Python 3.11 or higher. For the agent path, you can also use Node.js 20+, Java 17+, or .NET 8+.
* For the agent path, a coding agent such as Codex, Claude Code, or Cursor. Installing <Link href="/ai/agent-skills">Box Agent Skills</Link> helps it use current Box APIs.

Keep the metadata template key, folder ID, and enterprise ID handy. The prompt and your `.env` file need them.

<Note>
  Embedded metadata is available for any format Box can already <Link href="/guides/representations/supported-file-types">preview</Link>. The set of attributes depends on the file. Not every image includes every EXIF, JFIF, ICC, or MakerNotes field, and some tools strip this data. `embedded_metadata` is an on-demand [representation](/guides/representations): Box generates it the first time you request it.
</Note>

<AccordionGroup>
  <Accordion title="1. Create the metadata template">
    The metadata template defines the fields you copy from the representation. Create it once, and every file the script processes writes values in this shape.

    <Tip>
      This step requires Admin access.
    </Tip>

    1. Open the [Box Admin Console](https://app.box.com/master) and select **Metadata**.
    2. Select **New** and name it `Image Metadata`.
    3. Add the following fields:

    | Field name | Type | Template key |
    | - | - | - |
    | Date/Time | Date | `datetime` |
    | Camera Make | Text | `cameraMake` |
    | Image Width | Number | `imageWidth` |
    | Image Height | Number | `imageHeight` |
    | ISO | Number | `iso` |
    | Color Profile | Text | `colorProfile` |
    | Rights | Text | `rights` |
    | Creator | Text | `creator` |

    4. Copy the template key from under the **Template Name**. You need it for the prompt and for `.env`. Box also generates a **field key** from each field name (for example, Camera Make becomes `cameraMake`). Use those keys in the script.
    5. Select **Save**.

    <Frame>
      <img alt="Image Metadata template in Box with Date/Time, Camera Make, Image Width, Image Height, ISO, Colour Profile, Content Identifier, Rights, and Creator fields." />
    </Frame>

    For a detailed walkthrough, see [Customizing Metadata Templates](https://docs.box.com/en/box-admin-tools/managing-content/metadata/customizing-metadata-templates).
  </Accordion>

  <Accordion title="2. Create the photos folder">
    Create a dedicated folder in Box for the images you want on the dashboard.

    1. In Box, create a new folder called `Photos`.
    2. Upload previewable image files to the folder.
    3. Note the **folder ID** from the URL. For example, if the URL is `https://app.box.com/folder/123456789`, the folder ID is `123456789`.
    4. **Share the folder with your application's service account.** This is required because CCG applications act as a separate service account user that does not automatically have access to your content.

    <Frame>
      <img alt="Five sample photos in a Box folder, including aerial landscapes, a trophy, and a stadium tunnel, each with a filename and upload date." />
    </Frame>

    <Warning>
      Without this step, all API calls return 404 "Not found" errors.

      To find your service account email, go to the [Developer Console](https://app.box.com/developers/console), open your app, and look under **General Settings** for the **Service Account ID** (it looks like `AutomationUser_xxxxx_xxxxxx@boxdevedition.com`).

      Invite this email as a **collaborator** on the folder with the **Editor** role. Editor access is required because the app needs to write metadata back to files.
    </Warning>
  </Accordion>
</AccordionGroup>

## Build with an agent

Gather these values from [Before you start](#before-you-start):

* **Metadata template key** – from the template you created
* **Photos folder ID** – from the folder URL
* **Enterprise ID** – from the [Developer Console](https://app.box.com/developers/console), using the icon in the top-right

Choose your stack and copy the prompt. It already lists these as prerequisites, so the agent reads them from environment variables instead of trying to create them. Replace the `<TEMPLATE_KEY>`, `<FOLDER_ID>`, and `<ENTERPRISE_ID>` placeholders if you want the agent to pre-fill `.env`. Otherwise, leave them and fill `.env` yourself after scaffolding.

<div>
  <AgentPromptBuilder />

  <div>
    <div>
      ```md Python + Script theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use Python 3.11+ with pip and a virtual environment. Install exactly one Box package: "boxsdk~=10.0" (do NOT also install box-sdk-gen — both ship the box_sdk_gen module and conflict). Import Box APIs with `from box_sdk_gen import ...`. Also install python-dotenv and pytest for tests.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      Mirror the Python in the tutorial for list_representations, fetch_representation (including x_rep_hints, client.make_request for info and content URLs, polling, and download), EMBEDDED_METADATA_FIELD_MAP, and create_file_metadata_by_id. Use client.files.get_file_by_id and client.file_metadata.create_file_metadata_by_id. Do not add other languages or extra Box APIs.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - list_representations, fetch_representation, EMBEDDED_METADATA_FIELD_MAP, and the metadata write path matching the tutorial modules
      - a flat Python layout matching the tutorial (no unnecessary packages)
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Python + FastAPI theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use Python with FastAPI. Target Python 3.11+, use pip and a virtual environment. Install exactly one Box package: "boxsdk~=10.0" (do NOT also install box-sdk-gen — both ship the box_sdk_gen module and conflict). Import Box APIs with `from box_sdk_gen import ...`. Also install fastapi, uvicorn, python-dotenv, and pytest for tests.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's Python samples are a script, not a web server. Copy list_representations, fetch_representation, EMBEDDED_METADATA_FIELD_MAP, and the metadata write from those samples unchanged. Use client.make_request for representation info and content URLs. The Box Python SDK is synchronous — use plain def handlers (or run sync Box calls in a threadpool); do not await sync SDK methods. Still include a way to process BOX_FOLDER_ID without requiring a public URL.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - list_representations, fetch_representation, field map, and metadata write (same Box logic as the tutorial), plus a FastAPI app module with a CLI or POST path that processes BOX_FOLDER_ID
      - an idiomatic FastAPI layout; keep Box representation and metadata modules separate from the HTTP layer
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md TypeScript + Node theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use TypeScript on Node.js 20+. Use npm, box-node-sdk@10 (BoxClient, BoxCcgAuth, CcgConfig, BoxApiError from box-node-sdk), dotenv, tsx (or tsc), and a test runner such as node:test or vitest.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for listing representations, requesting [embedded_metadata], triggering generation on none, polling pending, downloading JSON, mapping the eight template fields, coercing types, and writing enterprise metadata. Adapt to box-node-sdk@10 camelCase (getFileById, makeRequest, getFolderItems, createFileMetadataById). Pass x-rep-hints as headers.xRepHints on getFileById. Use client.makeRequest for representation info and content URLs; binary content is a stream — collect it to a Buffer. Use a commonjs-friendly tsconfig (module commonjs, moduleResolution node, esModuleInterop, strict) and run with npx tsx.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - modules for listing representations, fetching embedded_metadata, mapping fields, writing metadata, and a script entrypoint that processes BOX_FOLDER_ID
      - a flat TypeScript + Node layout; keep Box logic in dedicated modules
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md TypeScript + Fastify theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use TypeScript with Fastify on Node.js 20+. Use npm, box-node-sdk@10 (BoxClient, BoxCcgAuth, CcgConfig, BoxApiError from box-node-sdk), fastify, dotenv, tsx (or tsc), and a test runner such as node:test or vitest.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for representations, [embedded_metadata], field mapping, and metadata write. Adapt to box-node-sdk@10 camelCase (getFileById, makeRequest). Pass x-rep-hints as headers.xRepHints. Binary makeRequest content is a stream — collect it to a Buffer. Fastify is optional HTTP wrapping — still include a way to process BOX_FOLDER_ID without requiring a public URL.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - modules for listing representations, fetching embedded_metadata, mapping fields, and writing metadata (same Box logic as the tutorial), plus a Fastify app with a CLI or POST path that processes BOX_FOLDER_ID
      - an idiomatic Fastify + TypeScript layout; keep Box representation and metadata modules separate from the HTTP layer
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Node + Script theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use Node.js 20+ with JavaScript (not TypeScript). Use npm and exactly one Box package: box-node-sdk@10 (do NOT also install box-typescript-sdk-gen). Import BoxClient, BoxCcgAuth, CcgConfig, and BoxApiError from box-node-sdk. Also install dotenv and a test runner such as node:test.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for listing representations, requesting [embedded_metadata], triggering generation on none, polling pending, downloading JSON, mapping the eight template fields, coercing types, and writing enterprise metadata. Adapt to box-node-sdk@10 camelCase (getFileById, makeRequest). Pass x-rep-hints as headers.xRepHints. Binary makeRequest content is a stream — collect it to a Buffer.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - modules for listing representations, fetching embedded_metadata, mapping fields, writing metadata, and a script entrypoint that processes BOX_FOLDER_ID
      - a flat JavaScript layout; keep Box logic in dedicated modules
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Node + NestJS theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use Node.js 20+ with NestJS. NestJS projects use TypeScript by default. Use npm and exactly one Box package: box-node-sdk@10 (do NOT also install box-typescript-sdk-gen). Import BoxClient, BoxCcgAuth, CcgConfig, and BoxApiError from box-node-sdk. Also install @nestjs/core, @nestjs/common, @nestjs/platform-express, dotenv, and a test runner such as Jest.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for representations, [embedded_metadata], field mapping, and metadata write. Adapt to box-node-sdk@10 camelCase (getFileById, makeRequest). Pass x-rep-hints as headers.xRepHints. Binary makeRequest content is a stream — collect it to a Buffer. NestJS is optional HTTP wrapping — still include a way to process BOX_FOLDER_ID without requiring a public URL.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - a Box client provider, representation provider, metadata provider, and a CLI or controller path that processes BOX_FOLDER_ID
      - an idiomatic NestJS layout (module, providers); keep Box client, representations, and metadata in dedicated providers separate from any HTTP controller
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Java + CLI theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use Java 17+ with a Maven or Gradle CLI application. Use exactly one Box artifact: com.box:box-java-sdk version 10 or later (do NOT also add box-java-sdk-gen). Use BoxClient, BoxCCGAuth, CCGConfig, BoxAPIError, and file/metadata types from that SDK (packages under com.box.sdkgen). Also add a test starter such as JUnit 5.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for listing representations, requesting [embedded_metadata] via x_rep_hints, triggering generation on none, polling pending, downloading JSON, mapping the eight template fields, coercing types, and writing enterprise metadata. Adapt to box-java-sdk v10. Use BoxClient.makeRequest with FetchOptions for the representation info and content URLs.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - a Box client factory, representation helper, field-map/metadata writer, and a main class that processes BOX_FOLDER_ID
      - an idiomatic Java CLI layout; keep Box client, representations, and metadata in dedicated classes separate from main
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Java + Spring Boot theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use Java 17+ with Spring Boot 3. Use Maven or Gradle and exactly one Box artifact: com.box:box-java-sdk version 10 or later (do NOT also add box-java-sdk-gen). Use BoxClient, BoxCCGAuth, CCGConfig, BoxAPIError, and file/metadata types from that SDK (packages under com.box.sdkgen). Also use spring-boot-starter-web and a test starter such as spring-boot-starter-test.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for representations, [embedded_metadata], field mapping, and metadata write. Adapt to box-java-sdk v10. Use BoxClient.makeRequest with FetchOptions for representation info and content URLs. Spring Web is optional HTTP wrapping — still include a way to process BOX_FOLDER_ID without requiring a public URL.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - a Box client configuration/bean, representation service, metadata service, and a CLI or controller path that processes BOX_FOLDER_ID
      - an idiomatic Spring Boot layout; keep Box client, representations, and metadata in dedicated classes separate from the HTTP controller
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md .NET + Console theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use .NET 8+ with a console application. Use NuGet and exactly one Box package: Box.V2.Core version 10 or later (do NOT also install Box.Sdk.Gen — v10 of Box.V2.Core already ships the generated client). Use BoxClient, BoxCcgAuth, CcgConfig, and BoxApiException (or the SDK's API error type) from that package. Also add a test SDK such as xUnit.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for listing representations, requesting [embedded_metadata], triggering generation on none, polling pending, downloading JSON, mapping the eight template fields, coercing types, and writing enterprise metadata. Adapt to Box.V2.Core v10. Use client.MakeRequestAsync with FetchOptions for representation info and content URLs.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - a Box client factory, representation helper, field-map/metadata writer, and Program.cs that processes BOX_FOLDER_ID
      - an idiomatic .NET console layout; keep Box client, representations, and metadata in dedicated classes separate from Program
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md .NET + ASP.NET Core theme={null}
      Build a production-minded script that extracts embedded technical metadata (EXIF and related fields) from previewable files in Box by following this tutorial:
      https://developer.box.com/tutorials/extract-exif-metadata

      Use .NET 8+ with ASP.NET Core. Use NuGet and exactly one Box package: Box.V2.Core version 10 or later (do NOT also install Box.Sdk.Gen — v10 of Box.V2.Core already ships the generated client). Use BoxClient, BoxCcgAuth, CcgConfig, and BoxApiException (or the SDK's API error type) from that package. Also add Microsoft.AspNetCore.App and a test SDK such as xUnit.

      Prerequisites already done in Box (see the tutorial). Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields datetime, cameraMake, imageWidth, imageHeight, iso, colorProfile, rights, creator)
      - Folder ID with previewable images: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box

      The tutorial's samples are Python. Use those as the behavioral spec for representations, [embedded_metadata], field mapping, and metadata write. Adapt to Box.V2.Core v10. Use client.MakeRequestAsync with FetchOptions for representation info and content URLs. ASP.NET Core is optional HTTP wrapping — still include a way to process BOX_FOLDER_ID without requiring a public URL.

      The app must:
      1. Authenticate to Box with the Box core SDK ≥v10 using Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user. Use SDK methods for Box calls. For representation info and content URLs, use the SDK request helper (Python: client.make_request) — do not use raw REST clients such as curl.
      2. Implement list_representations as in the tutorial: client.files.get_file_by_id with fields=["representations"]
         and print each representation type (and dimensions when present).
      3. Implement fetch_representation as in the tutorial:
         - client.files.get_file_by_id with fields=["representations"] and x_rep_hints=rep_hint.
         - If state is none, call client.make_request on the representation info URL from the SDK response to trigger generation, then treat the state as pending.
         - Poll get_file_by_id until success or viewable, or time out (max_wait_seconds=30, poll_interval=3).
         - Replace {+asset_path} in url_template and download with client.make_request (binary, follow redirects).
      4. Call fetch_representation with rep_hint="[embedded_metadata]".
      5. Parse the JSON body. Map fields with EMBEDDED_METADATA_FIELD_MAP exactly as in the tutorial:
         datetime ([0].EXIF.DateTimeOriginal, date),
         cameraMake ([0].EXIF.Make, text),
         imageWidth ([0].File.ImageWidth, number),
         imageHeight ([0].File.ImageHeight, number),
         iso ([0].EXIF.ISO, number),
         colorProfile ([0].ICC_Profile.ProfileDescription, text),
         rights ([0].XMP.Rights, text),
         creator ([0].XMP.Creator, text).
         Missing fields are OK — skip them. If no mapped fields are present, skip the metadata write (do not POST an empty body).
      6. Implement _resolve_path (read a JSON path) and _coerce (convert to date, text, or number)
         exactly as in the tutorial metadata sample.
      7. Write selected values as Box enterprise metadata with create_file_metadata_by_id.
         If the instance already exists (409), JSON-Patch update with op add as in the tutorial.
         Handle write errors per file without aborting the rest of the folder.
      8. Process files in BOX_FOLDER_ID using the extension filter from the tutorial.

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and BOX_FOLDER_ID.

      Create a complete runnable project with:
      - a Box client factory/service, representation service, metadata service, and a CLI or controller path that processes BOX_FOLDER_ID
      - an idiomatic ASP.NET Core layout; keep Box client, representations, and metadata in dedicated services separate from the API controller
      - dependency and run commands
      - .env.example and .gitignore files
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>
  </div>

  <p>
    Review generated code before using it in production. Never paste Box credentials into your
    coding agent.
  </p>
</div>

When the agent finishes, copy `.env.example` to `.env` and fill in your client ID, client secret, enterprise ID, metadata template key, and folder ID. Then skip ahead to [Run and verify](#run-and-verify).

You can also clone a working sample if you prefer to start from running code:

<CardGroup>
  <Card title="Python working sample" href="https://github.com/box-community/extract-exif-metadata" icon="github">
    Clone the sample, add your Box credentials, and run.
  </Card>
</CardGroup>

Prefer to write the code yourself? See [Build by hand](#build-by-hand) below.

## Build by hand

Use this path if you prefer to write the code yourself, or if you need a reference when the agent drifts. Complete [Before you start](#before-you-start) first, then follow the steps in order. The samples use the Box Python SDK v10.

<AccordionGroup>
  <Accordion title="1. Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir extract-exif-metadata && cd extract-exif-metadata
    ```

    2. Install dependencies:

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    pip install boxsdk python-dotenv
    ```

    <Note>
      After activation, your terminal prompt shows `(.venv)` at the beginning. Every time you open a new terminal window or tab, re-activate the virtual environment with `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError`, the venv is usually not activated.
    </Note>

    3. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your actual credentials from the Box Developer Console:

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    BOX_METADATA_TEMPLATE_KEY=your_metadata_template_key
    BOX_FOLDER_ID=your_folder_id
    ```

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>
  </Accordion>

  <Accordion title="2. Authenticate the Box client">
    Create the Box client module in your project directory:

    ```python theme={null}
    # box_client.py
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        BoxCCGAuth,
        CCGConfig,
    )

    load_dotenv()

    def get_box_client() -> BoxClient:
        config = CCGConfig(
            client_id=os.getenv("BOX_CLIENT_ID"),
            client_secret=os.getenv("BOX_CLIENT_SECRET"),
            enterprise_id=os.getenv("BOX_ENTERPRISE_ID"),
        )
        auth = BoxCCGAuth(config=config)
        return BoxClient(auth=auth)
    ```

    <Tip>
      Client Credentials Grant is recommended for server-to-server automations where no end user is present. For other authentication options, see the [authentication overview](/guides/authentication).
    </Tip>
  </Accordion>

  <Accordion title="3. Work with representations">
    Create `representations.py`. `list_representations` prints every representation Box can generate for that file. `fetch_representation` requests a specific one with `x_rep_hints`. Use `[embedded_metadata]`. You can request more than one representation in a single call by combining hints in that value.

    A `none` state means Box has not generated the representation yet. The Box Python SDK does not start or download that representation for you. After `get_file_by_id` returns the info and content URLs, `fetch_representation` uses `client.make_request` so authentication stays on the Box client. It then polls `get_file_by_id` until the state is `success` or `viewable`.

    ```python theme={null}
    # representations.py
    import time

    from box_sdk_gen import BoxClient
    from box_sdk_gen.networking.fetch_options import FetchOptions, ResponseFormat
    from box_sdk_gen.schemas.file_full import FileFullRepresentationsEntriesStatusStateField

    def list_representations(client: BoxClient, file_id: str) -> None:
        """Fetch and print all available representations for a file."""
        file = client.files.get_file_by_id(
            file_id,
            fields=["representations"],
        )
        entries = (
            file.representations.entries
        )

        print("Representations for file", file_id)
        print("-" * 50)
        for rep in entries:
            dims = rep.properties.dimensions if rep.properties and rep.properties.dimensions else ""
            dims_str = f"  |  dimensions: {dims}" if dims else ""
            print(f"  type: {rep.representation}{dims_str}")

    def fetch_representation(
        client: BoxClient,
        file_id: str,
        rep_hint: str,
        asset_path: str = "",
        max_wait_seconds: int = 30,
        poll_interval: int = 3,
    ) -> bytes | None:
        file = client.files.get_file_by_id(
            file_id,
            fields=["representations"],
            x_rep_hints=rep_hint,
        )
        entries = (
            file.representations.entries
        )

        rep = entries[0]
        state = rep.status.state
        state_str = state.value if state else "unknown"
        url_template = rep.content.url_template
        print(f"state: {state_str}  |  url_template: {url_template}")

        if state == FileFullRepresentationsEntriesStatusStateField.NONE:
            print("State is 'none' - triggering generation via info URL...")
            if rep.info and rep.info.url:
                client.make_request(
                    FetchOptions(
                        url=rep.info.url,
                        method="GET",
                        response_format=ResponseFormat.NO_CONTENT,
                    )
                )
            state = FileFullRepresentationsEntriesStatusStateField.PENDING
        elapsed = 0
        while state == FileFullRepresentationsEntriesStatusStateField.PENDING:
            if elapsed >= max_wait_seconds:
                print(f"Timed out after {max_wait_seconds}s waiting for representation.")
                return None
            print(f"  State is 'pending' - waiting {poll_interval}s... (elapsed: {elapsed}s)")
            time.sleep(poll_interval)
            elapsed += poll_interval
            file = client.files.get_file_by_id(
                file_id,
                fields=["representations"],
                x_rep_hints=rep_hint,
            )
            entries = (
                file.representations.entries
            )
            rep = entries[0]
            state = rep.status.state if rep.status else None
        ready_states = {
            FileFullRepresentationsEntriesStatusStateField.SUCCESS,
            FileFullRepresentationsEntriesStatusStateField.VIEWABLE,
        }
        if state not in ready_states:
            print(f"Representation ended in unexpected state: {state}")
            return None
        url_template = rep.content.url_template
        download_url = url_template.replace("{+asset_path}", asset_path)
        response = client.make_request(
            FetchOptions(
                url=download_url,
                method="GET",
                response_format=ResponseFormat.BINARY,
                follow_redirects=True,
            )
        )
        return response.content.read()
    ```

    Example `list_representations` output:

    ```text theme={null}
    Representations for file 2163735367009
    --------------------------------------------------
      type: jpg  |  dimensions: 32x32
      type: jpg  |  dimensions: 94x94
      type: jpg  |  dimensions: 160x160
      type: jpg  |  dimensions: 320x320
      type: jpg  |  dimensions: 1024x1024
      type: png  |  dimensions: 1024x1024
      type: png  |  dimensions: 2048x2048
      type: jpg  |  dimensions: 2048x2048
      type: 3d
      type: embedded_metadata
    ```

    Call `fetch_representation` with `rep_hint="[embedded_metadata]"`.

    Example when generation has not started:

    ```text theme={null}
    state: none  |  url_template: https://dl.boxcloud.com/api/2.0/internal_files/2163735367009/versions/2392182789409/representations/embedded_metadata/content/{+asset_path}
    ```

    The downloaded body is JSON. A JPEG can look like this (many fields omitted):

    ```json theme={null}
    [
      {
        "BoxNormalized": {
          "PageCount": null
        },
        "File": {
          "FileType": "JPEG",
          "FileTypeExtension": "jpg",
          "MIMEType": "image/jpeg"
        },
        "JFIF": {
          "JFIFVersion": 1.01,
          "ResolutionUnit": "inches",
          "XResolution": 300,
          "YResolution": 300
        },
        "EXIF": {
          "Make": "Apple",
          "Model": "iPhone 14",
          "Orientation": "Horizontal (normal)"
        },
        "MakerNotes": {
          "MakerNoteVersion": 15,
          "RunTimeFlags": "Valid",
          "RunTimeValue": 6241807022333
        },
        "MPF": {
          "MPFVersion": "0100",
          "NumberOfImages": 2,
          "MPImageFlags": "(none)"
        },
        "ICC_Profile": {
          "ProfileCMMType": "Apple Computer Inc.",
          "ProfileVersion": "4.0.0"
        },
        "JPEG": {
          "HDRGainCurve": "(Binary data 1392 bytes, use -b option to extract)"
        }
      }
    ]
    ```

    One sample file produced 114 data points. Files differ in which categories and fields they include.
  </Accordion>

  <Accordion title="4. Write metadata back to the file">
    Create `metadata.py`. After `fetch_representation` returns the JSON bytes, this module maps template keys to JSON paths, converts values to the template field types, and writes an enterprise metadata instance.

    ```python theme={null}
    # metadata.py
    import json
    from datetime import datetime, timezone

    from box_sdk_gen import (
        BoxAPIError,
        BoxClient,
        CreateFileMetadataByIdScope,
        UpdateFileMetadataByIdRequestBody,
        UpdateFileMetadataByIdRequestBodyOpField,
        UpdateFileMetadataByIdScope,
    )

    EMBEDDED_METADATA_FIELD_MAP = {
        "datetime": ("[0].EXIF.DateTimeOriginal", "date"),
        "cameraMake": ("[0].EXIF.Make", "text"),
        "imageWidth": ("[0].File.ImageWidth", "number"),
        "imageHeight": ("[0].File.ImageHeight", "number"),
        "iso": ("[0].EXIF.ISO", "number"),
        "colorProfile": ("[0].ICC_Profile.ProfileDescription", "text"),
        "rights": ("[0].XMP.Rights", "text"),
        "creator": ("[0].XMP.Creator", "text"),
    }

    def _coerce(value, field_type: str):
        if field_type == "number":
            return float(value) if "." in str(value) else int(value)
        if field_type == "date":
            try:
                dt = datetime.strptime(str(value), "%Y:%m:%d %H:%M:%S")
                return dt.replace(tzinfo=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
            except ValueError:
                return str(value)
        return str(value)

    def _resolve_path(data, path: str):
        for part in path.split("."):
            if part.startswith("[") and part.endswith("]"):
                try:
                    data = data[int(part[1:-1])]
                except (IndexError, TypeError, ValueError):
                    return None
            else:
                if not isinstance(data, dict):
                    return None
                data = data.get(part)
            if data is None:
                return None
        return data

    def apply_embedded_metadata_to_template(
        client: BoxClient,
        file_id: str,
        embedded_metadata_bytes: bytes,
        template_key: str,
    ) -> None:
        embedded_metadata = json.loads(embedded_metadata_bytes.decode("utf-8"))
        fields = {}
        for template_field, (path, field_type) in EMBEDDED_METADATA_FIELD_MAP.items():
            value = _resolve_path(embedded_metadata, path)
            if value is not None:
                fields[template_field] = _coerce(value, field_type)
        print(f"Extracted {len(fields)} of {len(EMBEDDED_METADATA_FIELD_MAP)} fields:")
        for k, v in fields.items():
            print(f"  {k}: {v!r} ({type(v).__name__})")
        if not fields:
            print(f"No mapped fields on file {file_id}; skipping metadata write")
            return

        try:
            client.file_metadata.create_file_metadata_by_id(
                file_id=file_id,
                scope=CreateFileMetadataByIdScope.ENTERPRISE,
                template_key=template_key,
                request_body=fields,
            )
            print(f"Metadata created: {template_key} on file {file_id}")
        except BoxAPIError as error:
            if error.response_info.status_code != 409:
                raise
            client.file_metadata.update_file_metadata_by_id(
                file_id=file_id,
                scope=UpdateFileMetadataByIdScope.ENTERPRISE,
                template_key=template_key,
                request_body=[
                    UpdateFileMetadataByIdRequestBody(
                        op=UpdateFileMetadataByIdRequestBodyOpField.ADD,
                        path=f"/{key}",
                        value=value,
                    )
                    for key, value in fields.items()
                ],
            )
            print(f"Metadata updated: {template_key} on file {file_id}")
    ```

    <Note>
      Creating metadata only succeeds the first time. If the file already has an instance of the template, Box returns `409 Conflict on Metadata Instance`, so this function falls back to a JSON-Patch update. That keeps the script safe to re-run on a file you already processed.

      Use the `add` operation rather than `replace`. `add` sets a value whether or not the field is already present, so the update still succeeds when a file omits some EXIF fields.
    </Note>

    Missing fields are OK. Skip them. Once metadata is attached, the extracted fields become searchable, filterable, and visible in the Box web app. You can use <Link href="/guides/metadata/queries">metadata queries</Link> to filter by camera make or ISO, or build dashboards in Box Apps.
  </Accordion>

  <Accordion title="5. Process every file in the folder">
    Create `process.py`. This lists image files in `BOX_FOLDER_ID`, fetches `embedded_metadata` for each one, and writes the mapped fields.

    ```python theme={null}
    # process.py
    import os

    from dotenv import load_dotenv

    from box_client import get_box_client
    from metadata import apply_embedded_metadata_to_template
    from representations import fetch_representation

    load_dotenv()

    IMAGE_EXTENSIONS = {".jpg", ".jpeg", ".png", ".tiff", ".tif", ".heic", ".gif", ".webp"}

    def process_folder_images(client, folder_id: str, template_key: str) -> None:
        marker = None
        total = 0
        processed = 0

        while True:
            items = client.folders.get_folder_items(
                folder_id,
                fields=["id", "name", "type"],
                limit=100,
                marker=marker,
                usemarker=True,
            )

            for item in items.entries:
                if item.type != "file":
                    continue
                ext = "." + item.name.rsplit(".", 1)[-1].lower() if "." in item.name else ""
                if ext not in IMAGE_EXTENSIONS:
                    continue

                total += 1
                print(f"\nProcessing [{total}]: {item.name} (id: {item.id})")

                meta_bytes = fetch_representation(
                    client=client,
                    file_id=item.id,
                    rep_hint="[embedded_metadata]",
                    asset_path="",
                )
                if not meta_bytes:
                    continue

                apply_embedded_metadata_to_template(
                    client=client,
                    file_id=item.id,
                    embedded_metadata_bytes=meta_bytes,
                    template_key=template_key,
                )
                processed += 1

            next_marker = getattr(items, "next_marker", None)
            if not next_marker:
                break
            marker = next_marker

        print(f"\nDone. Processed {processed} of {total} image(s) in folder {folder_id}.")

    if __name__ == "__main__":
        client = get_box_client()
        process_folder_images(
            client,
            os.getenv("BOX_FOLDER_ID"),
            os.getenv("BOX_METADATA_TEMPLATE_KEY"),
        )
    ```

    At this point, your project directory should contain the following files:

    ```text theme={null}
    extract-exif-metadata/
    ├── .env
    ├── .venv/
    ├── box_client.py
    ├── metadata.py
    ├── process.py
    └── representations.py
    ```
  </Accordion>
</AccordionGroup>

When you finish scaffolding, continue to [Run and verify](#run-and-verify).

## Run and verify

Run the script against the folder you created in [Before you start](#before-you-start).

1. Make sure you are in the `extract-exif-metadata` directory, then start the script:

   ```bash theme={null}
   cd ~/extract-exif-metadata
   source .venv/bin/activate
   python3 process.py
   ```

2. Check the terminal output. You should see each file processed, the extracted field count, and a confirmation that metadata was created or updated:

   ```text theme={null}
   Processing [1]: DJI_0168.jpg (id: 123456789)
   state: success  |  url_template: https://dl.boxcloud.com/api/2.0/internal_files/...
   Extracted 2 of 8 fields:
     imageWidth: 1128 (int)
     imageHeight: 1200 (int)
   Metadata created: imageMetadata on file 123456789
   ```

3. Open a file in Box and select the **Metadata** tab to verify the values were written correctly.

## Filter in a Box Apps dashboard

Add a Box Apps dashboard that uses the template. You can then see and filter images on the technical metadata you wrote.

<Frame>
  <img alt="Photo App dashboard listing photos with Date/Time, Camera Make, Image Width, Image Height, and ISO columns, filtered by Location Blog." />
</Frame>

You can also generate a summary of image content (objects, locations, people, text, and so on) and store it on the same template so search covers both technical fields and visual content. See <Link href="/guides/box-ai/ai-tutorials/extract-metadata">Extract metadata from a file</Link>. A search like this works across images:

<Frame>
  <img alt="Photo App dashboard filtered by Location Blog and Keywords Anfield, showing three photos with Date/Time, Camera Make, Image Width, and Image Height columns." />
</Frame>

You can also embed the same metadata in a custom page with the Box UI Element <Link href="/guides/embed/ui-elements/explorer-metadata-v2">Content Explorer</Link>.

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your Python virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in **Developer Console** > **Configuration**.
    * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID (found in **Admin Console** > **Account & Billing**, or **Developer Console** > icon in the top-right > **Copy Enterprise ID**).
    * Ensure your app is authorized in the Developer Console.
    * Make sure the app type is Client Credentials Grant.
  </Accordion>

  <Accordion title="404 Not Found">
    The service account does not have access to the file or folder. Invite the service account email (found in **Developer Console** > **General Settings**) as a collaborator with the **Editor** role on the folder containing your image files.
  </Accordion>

  <Accordion title="Timed out after 30s waiting for representation">
    `embedded_metadata` is generated on demand. Wait a few seconds and re-run the script. Confirm the file type is one Box can <Link href="/guides/representations/supported-file-types">preview</Link>.
  </Accordion>

  <Accordion title="Extracted 0 of 8 fields">
    Not every file includes every EXIF, XMP, or ICC field. That is expected. Check the downloaded JSON for the categories that file actually contains, then adjust `EMBEDDED_METADATA_FIELD_MAP` if you need different paths.
  </Accordion>

  <Accordion title="409 Conflict on Metadata Instance">
    The file already has an instance of the template, so creating one fails. This is common when you retest a file that a previous run already processed.

    Add the 409 fallback shown in [Build by hand](#build-by-hand) under **4. Write metadata back to the file** so the script updates the existing instance instead of creating a second one.
  </Accordion>

  <Accordion title="The agent tried to create the template or folder">
    The template, photos folder, and enterprise ID come from [Before you start](#before-you-start). An agent cannot create them. Re-paste the prompt with the prerequisites block intact so the agent reads `BOX_METADATA_TEMPLATE_KEY`, `BOX_FOLDER_ID`, and `BOX_ENTERPRISE_ID` from the environment, or follow [Build by hand](#build-by-hand).
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Invoice intake automation" href={localizeLink("/tutorials/invoice-intake")} icon="file-invoice">
    Run extraction from a webhook so files are tagged as they arrive, instead of on demand.
  </Card>

  <Card title="Content Explorer metadata view" href={localizeLink("/guides/embed/ui-elements/explorer-metadata-v2")} icon="table">
    Embed a filterable metadata dashboard in your own app.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Box Tutorials
Source: https://developer.box.com/tutorials/index

End-to-end tutorials that walk you through building real applications with Box APIs, from first API call to production-ready integration.

## Before you begin

Every tutorial assumes you have:

1. A [Box developer account](https://account.box.com/signup/developer).
2. A Box application configured in the [Developer Console](https://account.box.com/developers/console) - see [Create your first application](/guides/getting-started/first-application).
3. Python 3.11 or higher installed locally.

Each tutorial lists additional prerequisites, such as specific scopes, permissions, and account configuration, at the top of the page.

## Tutorials

<CardGroup>
  <Card title="Invoice intake automation" href={localizeLink("/tutorials/invoice-intake")} icon="file-invoice">
    **Use case:** Automate accounts payable by extracting structured fields from invoice PDFs and writing them back as searchable metadata.

    **APIs:** Box AI Extract, Metadata, Webhooks

    **Time:** \~30 minutes
  </Card>

  <Card title="RFP answer bank" href={localizeLink("/tutorials/sales-rfp-answer-bank")} icon="magnifying-glass">
    **Use case:** Build an AI-powered answer bank that indexes curated content in a Box Hub and answers questions with Box AI. Uses a sales RFP library as the example.

    **APIs:** Hubs, Hub Items, Hub Collaborations, Box AI Ask

    **Time:** \~25 minutes
  </Card>

  <Card title="Secure in-app document review" href="/tutorials/secure-in-app-document-review" icon="eye">
    **Use case:** Let reviewers read and annotate sensitive documents inside your own app - upload, convert, and embed with Box View, then layer Box Content Preview for a richer UI.

    **APIs:** Upload, Box View (expiring embed link), Token exchange, Box Content Preview

    **Time:** \~30 minutes
  </Card>

  <Card title="Supplier agreement extraction" href={localizeLink("/tutorials/supplier-agreements")} icon="file-contract">
    **Use case:** Turn complex supplier agreements into structured procurement data using the `struct` and `table` field types in Box AI structured extraction.

    **APIs:** Box AI Extract, Enhanced Extract Agent

    **Time:** \~20 minutes
  </Card>

  <Card title="Automate new hire onboarding" href={localizeLink("/tutorials/onboarding-workspaces")} icon="user-plus">
    **Use case:** Provision a standardized, governed Box workspace for every new hire automatically when your HR system fires a hire event.

    **APIs:** Users, Groups, Folders, Collaborations

    **Time:** \~30 minutes
  </Card>

  <Card title="Offer letter automation" href={localizeLink("/tutorials/offer-letter-creation")} icon="file-signature">
    **Use case:** Generate offer letters from candidate data with Box Doc Gen, then route them through Box Sign for HR approval and candidate signature.

    **APIs:** Box Doc Gen, Box Sign, Webhooks

    **Time:** \~35 minutes
  </Card>

  <Card title="NDA risk summary" href={localizeLink("/tutorials/nda-risk-summary")} icon="file-shield">
    **Use case:** Extract key clauses from an NDA or MSA, score them into a Deal Risk Summary with confidence scores, and save it back to Box as a companion file.

    **APIs:** Box AI Extract, Uploads

    **Time:** \~20 minutes
  </Card>

  <Card title="Company brain knowledge base" href={localizeLink("/tutorials/company-brain")} icon="brain">
    **Use case:** Turn scattered content into a governed knowledge layer that humans and AI agents share. Review new files with Box AI, publish approved content to domain Hubs, and answer questions grounded in trusted sources.

    **APIs:** Box AI Extract, Metadata, Hubs, Box AI Ask

    **Time:** \~35 minutes
  </Card>

  <Card title="Claims evidence review" href={localizeLink("/tutorials/claims-evidence-review")} icon="clipboard-check">
    **Use case:** Build a claims service that tags selected evidence with a claim ID and starts a Box Automate approval workflow. Box handles the approve or reject tasks; your app chooses the files and starts the review.

    **APIs:** Box Automate (manual start), Metadata

    **Time:** \~15 minutes (prompt-first)
  </Card>

  <Card title="Connect an autonomous agent to Box" href="/tutorials/connect-an-agent-to-box" icon="robot">
    **Use case:** Give a coding or autonomous agent secure, scoped access to a shared Box project folder through the Box CLI or hosted Box MCP server.

    **Tools:** Box CLI, Box MCP, Box AI

    **Time:** \~20 minutes
  </Card>

  <Card title="Document metadata dashboard" href={localizeLink("/tutorials/explorer-metadata-view")} icon="table">
    **Use case:** Embed the enhanced metadata view (v2) of the Box Content Explorer to browse, filter, and edit documents by their metadata, with Box AI reading the field values out of the documents themselves.

    **APIs:** Metadata templates, Box AI Extract, File metadata, Content Explorer (UI Elements)

    **Time:** \~15 minutes
  </Card>

  <Card title="Extract EXIF metadata" href={localizeLink("/tutorials/extract-exif-metadata")} icon="image">
    **Use case:** Pull embedded technical metadata such as EXIF from previewable files and write selected fields to a metadata template so a Box Apps dashboard can filter them.

    **APIs:** File representations (`embedded_metadata`), Metadata

    **Time:** \~20 minutes
  </Card>
</CardGroup>

<Card title="Create a review workflow in Box Automate" href={localizeLink("/tutorials/box-automate-review-workflow")} icon="check-double">
  **Use case:** Build a review workflow in Box Automate that routes files through approval, sends Box notifications, and posts updates to Slack via HTTPS Request outcomes.

  **Tools:** Box Automate, HTTPS Request, Slack API

  **Time:** \~25 minutes
</Card>

## What to expect

Each tutorial follows the same structure:

| Section | What it covers |
| - | - |
| **Use case** | The business problem and why this solution works |
| **What you are building** | Concrete deliverables by the end of the tutorial |
| **Prerequisites** | Account, app, and scope requirements |
| **Step-by-step process** | Guided implementation with tested code examples |
| **Scaling to production** | Patterns for taking the solution beyond a prototype |


# Automate invoice intake with Box AI Extract
Source: https://developer.box.com/tutorials/invoice-intake



When a PDF is uploaded to a designated Box folder, this service extracts the vendor name, invoice number, dates, total, and currency with Box AI, then writes those values back to the file as metadata.

## Before you start

Complete these Box setup steps before you build. You need:

* A <Link href="https://account.box.com/signup/developer">free Box developer account</Link>, or a <Link href="https://www.box.com/pricing">Box Enterprise account</Link> with **Box AI** enabled.
* A Box application configured with **Client Credentials Grant** authentication, authorized in the Admin Console, with these scopes:
  * Read and write all files and folders stored in Box
  * Manage AI
  * Manage webhooks
* A runtime for the stack you choose: Python 3.11+, Node.js 20+, Java 17+, or .NET 8+.
* For the agent path, a coding agent such as Codex, Claude Code, or Cursor. Installing <Link href="/ai/agent-skills">Box Agent Skills</Link> helps it use current Box APIs.

Keep the metadata template key, inbox folder ID, and enterprise ID handy. The prompt and your `.env` file need them.

<AccordionGroup>
  <Accordion title="1. Create the metadata template">
    The metadata template defines the fields Box AI extracts. Create it once, and every invoice processed by the service returns values in this shape.

    <Tip>
      This step requires Admin access. If you do not have access, contact your Box administrator.
    </Tip>

    1. Open the [Box Admin Console](https://app.box.com/master) and select **Metadata**.
    2. In the **Invoices** tab, select **New** and name it `Invoice`.
    3. Add the following fields:

    | Field name | Type | Description |
    | - | - | - |
    | Vendor Name | Text | The name of the vendor or supplier issuing the invoice |
    | Invoice Number | Text | The unique invoice identifier |
    | Invoice Date | Date | The date the invoice was issued |
    | Due Date | Date | The payment due date |
    | Total Amount | Number | The total amount due, including taxes and fees |
    | Currency | Text | The three-letter currency code (for example, USD, EUR, GBP) |

    4. Copy the template key from under the **Template Name**. You need it for the prompt and for `.env`.
    5. Select **Save**.

    For a detailed walkthrough, see <Link href="https://support.box.com/hc/en-us/articles/360044194033-Customizing-Metadata-Templates">Customizing Metadata Templates</Link>.
  </Accordion>

  <Accordion title="2. Create the invoices inbox folder">
    Create a dedicated folder in Box to serve as the invoice drop zone.

    1. In Box, create a new folder called `Invoices Inbox`.
    2. Note the **folder ID** from the URL. For example, if the URL is `https://app.box.com/folder/123456789`, the folder ID is `123456789`.
    3. **Share the folder with your application's service account.** This is required because CCG applications act as a separate service account user that does not automatically have access to your content.

    <Warning>
      **This step is critical.** Without it, all API calls return 404 "Not found" errors.

      To find your service account email: go to the [Developer Console](https://app.box.com/developers/console), open your app, and look under **General Settings** for the **Service Account ID** (it looks like `AutomationUser_xxxxx_xxxxxx@boxdevedition.com`).

      Invite this email as a **collaborator** on the folder with the **Editor** role. Editor access is required because the app needs to write metadata back to files.
    </Warning>
  </Accordion>
</AccordionGroup>

## Build with an agent

Gather these values from [Before you start](#before-you-start):

* **Metadata template key** - from the template you created
* **Invoices Inbox folder ID** - from the folder URL
* **Enterprise ID** - from the [Developer Console](https://app.box.com/developers/console), using the icon in the top-right

Choose your stack and copy the prompt. It already lists these as prerequisites, so the agent reads them from environment variables instead of trying to create them. Replace the `<TEMPLATE_KEY>`, `<FOLDER_ID>`, and `<ENTERPRISE_ID>` placeholders if you want the agent to pre-fill `.env`; otherwise leave them and fill `.env` yourself after scaffolding.

<div>
  <AgentPromptBuilder />

  <div>
    <div>
      ```md Python + Flask theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use Python with Flask. Target Python 3.11+, use pip and a virtual environment. Install exactly one Box package: "boxsdk~=10" (do NOT also install box-sdk-gen — both ship the box_sdk_gen module and conflict). Import Box APIs with `from box_sdk_gen import ...`. Also install flask, python-dotenv, and pytest for tests.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      Mirror the Python tab in the tutorial for Box client, extract, and metadata modules. Use Flask for the webhook server exactly as in the Build by hand path.

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - box_client.py, extract.py, metadata.py, and app.py (POST /webhook) matching the tutorial modules
      - a flat Flask layout matching the tutorial (no unnecessary packages)
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Python + FastAPI theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use Python with FastAPI. Target Python 3.11+, use pip and a virtual environment. Install exactly one Box package: "boxsdk~=10" (do NOT also install box-sdk-gen — both ship the box_sdk_gen module and conflict). Import Box APIs with `from box_sdk_gen import ...`. Also install fastapi, uvicorn, python-dotenv, and pytest for tests.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's Python samples use Flask. Copy the Box client, extract, and metadata modules from those samples unchanged. Adapt only the HTTP layer to FastAPI + uvicorn. The Box Python SDK is synchronous — use plain def route handlers (or run sync Box calls in a threadpool); do not await sync SDK methods.

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - box_client.py, extract.py, metadata.py (same Box logic as the tutorial), and a FastAPI app module with POST /webhook
      - an idiomatic FastAPI layout; keep Box modules separate from the HTTP layer
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md TypeScript + Express theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use TypeScript with Express on Node.js 20+. Use npm, box-node-sdk@10 (BoxClient, BoxCcgAuth, CcgConfig, BoxApiError from box-node-sdk; AiItemBase from box-node-sdk/schemas/aiItemBase), express, dotenv, tsx (or tsc), and a test runner such as node:test or vitest.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      Mirror the TypeScript tab in the tutorial for Box client, extract, metadata, and Express webhook server. Use commonjs-friendly tsconfig (module commonjs, moduleResolution node, esModuleInterop, strict) and run with npx tsx app.ts.

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - boxClient.ts, extract.ts, metadata.ts, and app.ts (POST /webhook) mirroring the tutorial modules
      - a flat Express + TypeScript layout matching the tutorial
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md TypeScript + Fastify theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use TypeScript with Fastify on Node.js 20+. Use npm, box-node-sdk@10 (BoxClient, BoxCcgAuth, CcgConfig, BoxApiError from box-node-sdk; AiItemBase from box-node-sdk/schemas/aiItemBase), fastify, dotenv, tsx (or tsc), and a test runner such as node:test or vitest.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's TypeScript samples use Express. Copy the Box client, extract, and metadata modules from those samples unchanged. Adapt only the HTTP layer to Fastify. Register a JSON body parser / use Fastify's default JSON content-type handling so POST /webhook receives parsed JSON. Keep listen on port 5000 for the local curl test.

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - boxClient.ts, extract.ts, metadata.ts (same Box logic as the tutorial), and a Fastify app module with POST /webhook
      - an idiomatic Fastify + TypeScript layout; keep Box modules separate from the HTTP layer
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Node + Express theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use Node.js 20+ with JavaScript (not TypeScript) and Express. Use npm and exactly one Box package: box-node-sdk@10 (do NOT also install box-typescript-sdk-gen). Import BoxClient, BoxCcgAuth, CcgConfig, and BoxApiError from box-node-sdk, and AiItemBase from box-node-sdk/schemas/aiItemBase. Also install express, dotenv, and a test runner such as node:test.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's Build by hand samples are Python and TypeScript. Use those as the behavioral spec for Box client, extract, metadata, 409 metadata upsert, and webhook handling. Adapt the HTTP layer to Express in JavaScript. Keep listen on port 5000 for the local curl test.

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - boxClient.js, extract.js, metadata.js, and app.js (POST /webhook)
      - a flat Express + JavaScript layout; keep Box modules separate from the HTTP layer
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Node + NestJS theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use Node.js 20+ with NestJS. NestJS projects use TypeScript by default. Use npm and exactly one Box package: box-node-sdk@10 (do NOT also install box-typescript-sdk-gen). Import BoxClient, BoxCcgAuth, CcgConfig, and BoxApiError from box-node-sdk, and AiItemBase from box-node-sdk/schemas/aiItemBase. Also install @nestjs/core, @nestjs/common, @nestjs/platform-express, dotenv, and a test runner such as Jest.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's Build by hand samples are Python and TypeScript Express. Use those as the behavioral spec for Box client, extract, metadata, 409 metadata upsert, and webhook handling. Adapt only the HTTP layer to NestJS. Enable JSON body parsing (NestJS default with the Express adapter). NestJS POST handlers return 201 by default — set @HttpCode(200) on POST /webhook so the local curl test sees 200. For the AiItemBase import from box-node-sdk/schemas/aiItemBase, TypeScript moduleResolution node cannot resolve the SDK package export; use bundler or Node16 so nest build and Jest succeed. Keep listen on port 5000 for the local curl test.

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - a Box client provider, extract provider, metadata provider, and a webhook controller with POST /webhook
      - an idiomatic NestJS layout (module, controller, providers); keep Box client, extract, and metadata in dedicated providers separate from the HTTP controller
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Java + Spring Boot theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use Java 17+ with Spring Boot 3. Use Maven or Gradle and exactly one Box artifact: com.box:box-java-sdk version 10 or later (do NOT also add box-java-sdk-gen). Use BoxClient, BoxCCGAuth, CCGConfig, BoxAPIError, and the generated AI/metadata types from that SDK (packages under com.box.sdkgen). Also use spring-boot-starter-web and a test starter such as spring-boot-starter-test.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's Build by hand samples are Python and TypeScript. Use those as the behavioral spec for CCG enterprise auth, extract_structured with the metadata template (not inline fields), 409 metadata upsert with JSON-Patch op add, and webhook handling. Adapt the HTTP layer to Spring Web (@RestController). Call client.getAi().createAiExtractStructured(...) with an AiExtractStructured.Builder request whose metadataTemplate is an AiExtractStructuredMetadataTemplateField (templateKey + type METADATA_TEMPLATE + scope "enterprise") — not the Python CreateAiExtractStructuredMetadataTemplate name. On 409, catch BoxAPIError and check getResponseInfo().getStatusCode(). For JSON-Patch updates, UpdateFileMetadataByIdRequestBody.Builder.value(...) accepts only String, long, double, List<String>, or MetadataInstanceValue — convert extracted Object values (for example totalAmount) to those overloads; do not pass Object. Keep the server on port 5000 for the local curl test (server.port=5000).

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - a Box client configuration/bean, ExtractService, MetadataService, and a webhook controller with POST /webhook
      - an idiomatic Spring Boot layout; keep Box client configuration, extract, and metadata in dedicated classes separate from the HTTP controller
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md Java + Quarkus theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use Java 17+ with Quarkus. Use Maven or Gradle and exactly one Box artifact: com.box:box-java-sdk version 10 or later (do NOT also add box-java-sdk-gen). Use BoxClient, BoxCCGAuth, CCGConfig, BoxAPIError, and the generated AI/metadata types from that SDK (packages under com.box.sdkgen). Also use quarkus-rest-jackson (or quarkus-resteasy-jackson) and quarkus-junit5 for tests.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's Build by hand samples are Python and TypeScript. Use those as the behavioral spec for CCG enterprise auth, extract_structured with the metadata template (not inline fields), 409 metadata upsert with JSON-Patch op add, and webhook handling. Adapt the HTTP layer to Quarkus REST. Call client.getAi().createAiExtractStructured(...) with an AiExtractStructured.Builder request whose metadataTemplate is an AiExtractStructuredMetadataTemplateField (templateKey + type METADATA_TEMPLATE + scope "enterprise") — not the Python CreateAiExtractStructuredMetadataTemplate name. On 409, catch BoxAPIError and check getResponseInfo().getStatusCode(). For JSON-Patch updates, UpdateFileMetadataByIdRequestBody.Builder.value(...) accepts only String, long, double, List<String>, or MetadataInstanceValue — convert extracted Object values (for example totalAmount) to those overloads; do not pass Object. Keep the server on port 5000 for the local curl test (quarkus.http.port=5000).

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - a Box client producer/bean, ExtractService, MetadataService, and a JAX-RS resource with POST /webhook
      - an idiomatic Quarkus layout; keep Box client, extract, and metadata in dedicated beans/classes separate from the JAX-RS resource
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md .NET + ASP.NET Core theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use .NET 8+ with ASP.NET Core controllers. Use NuGet and exactly one Box package: Box.V2.Core version 10 or later (do NOT also install Box.Sdk.Gen — v10 of Box.V2.Core already ships the generated client). Use BoxClient, BoxCcgAuth, CcgConfig, and BoxApiException (or the SDK's API error type) from that package. Also add Microsoft.AspNetCore.App and a test SDK such as xUnit.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's Build by hand samples are Python and TypeScript. Use those as the behavioral spec for CCG enterprise auth, extract_structured with the metadata template (not inline fields), 409 metadata upsert with JSON-Patch op add, and webhook handling. Adapt the HTTP layer to an ASP.NET Core API controller. Call client.Ai.CreateAiExtractStructuredAsync with a metadata template (TemplateKey + Scope enterprise). Keep listen on port 5000 for the local curl test (urls=http://127.0.0.1:5000).

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - a Box client factory/service, ExtractService, MetadataService, and a webhook controller with POST /webhook
      - an idiomatic ASP.NET Core layout; keep Box client, extract, and metadata in dedicated services separate from the API controller
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>

    <div>
      ```md .NET + Minimal APIs theme={null}
      Build a production-minded invoice intake service by following this Box tutorial:
      https://developer.box.com/tutorials/invoice-intake

      Use .NET 8+ with ASP.NET Core Minimal APIs. Use NuGet and exactly one Box package: Box.V2.Core version 10 or later (do NOT also install Box.Sdk.Gen — v10 of Box.V2.Core already ships the generated client). Use BoxClient, BoxCcgAuth, CcgConfig, and BoxApiException (or the SDK's API error type) from that package. Also add a test SDK such as xUnit.

      Prerequisites already done in Box (see 'Before you start' in the tutorial).
      Do NOT try to create these; read their values from environment variables:
      - Enterprise metadata template key: <TEMPLATE_KEY>
        (fields vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, currency)
      - Invoices Inbox folder ID: <FOLDER_ID>, shared with the app service account as Editor
      - Enterprise ID: <ENTERPRISE_ID>
      - CCG app scopes enabled: Read and write all files and folders stored in Box,
        Manage AI, and Manage webhooks

      The tutorial's Build by hand samples are Python and TypeScript. Use those as the behavioral spec for CCG enterprise auth, extract_structured with the metadata template (not inline fields), 409 metadata upsert with JSON-Patch op add, and webhook handling. Adapt only the HTTP layer to Minimal APIs (MapPost). Call client.Ai.CreateAiExtractStructuredAsync with a metadata template (TemplateKey + Scope enterprise). Keep listen on port 5000 for the local curl test (urls=http://127.0.0.1:5000).

      The app must:
      1. Authenticate to Box with Client Credentials Grant (enterprise / service account).
         Use BOX_ENTERPRISE_ID — do NOT authenticate as a managed user.
      2. Receive Box FILE.UPLOADED webhook events at POST /webhook.
      3. Ignore events for non-PDF files; return 200 with a clear skipped/ignored status.
      4. Call POST /2.0/ai/extract_structured using the invoice metadata template
         (template_key + scope enterprise), not inline fields.
      5. Extract vendorName, invoiceNumber, invoiceDate, dueDate, totalAmount, and currency.
         Some fields may be missing when the PDF omits them — that is OK.
      6. Write the extracted values back to the file as Box enterprise metadata:
         - Try create first.
         - On 409 Conflict (instance already exists), JSON-Patch update with op 'add'
           for each returned field (not 'replace'). Do not fail retests of the same file.
      7. Return clear JSON responses and handle Box API errors safely.
      8. Include a local test path that does not require a public webhook URL
         (curl POST to localhost:5000/webhook with a simulated FILE.UPLOADED payload).

      Read configuration from environment variables:
      BOX_CLIENT_ID, BOX_CLIENT_SECRET, BOX_ENTERPRISE_ID,
      BOX_METADATA_TEMPLATE_KEY, and INVOICES_FOLDER_ID.
      INVOICES_FOLDER_ID is for registering the production webhook only —
      do not require it inside the POST /webhook handler.

      Create a complete runnable project with:
      - a Box client factory, ExtractService, MetadataService, and Program.cs with MapPost("/webhook", ...)
      - an idiomatic Minimal APIs layout (MapPost in Program.cs); keep Box client, extract, and metadata in dedicated classes separate from endpoint mapping
      - dependency and run commands
      - .env.example and .gitignore files
      - brief webhook signature verification guidance (link or comment is enough;
        do not block the local curl test on signature checks)
      - idempotency: the 409 metadata upsert above is required; optionally also
        document skipping a second AI extract when an instance already exists
      - focused unit tests and a README with setup and test steps

      Never hard-code credentials. Add concise comments only where the Box-specific behavior is not obvious. Before writing code, summarize the architecture and list the files you will create.
      ```
    </div>
  </div>

  <p>
    Review generated code before using it in production. Never paste Box credentials into your
    coding agent.
  </p>
</div>

When the agent finishes, copy `.env.example` to `.env` and fill in your client ID, client secret, enterprise ID, metadata template key, and folder ID. Then skip ahead to [Run and verify](#run-and-verify).

Prefer to write the code yourself? See [Build by hand](#build-by-hand) below.

## Build by hand

Use this path if you prefer to write the code yourself, or if you need a reference when the agent drifts. Complete [Before you start](#before-you-start) first, then follow the steps in order. Use the language tabs in each code block to switch between Python and TypeScript.

You can also clone a working sample if you prefer to start from running code:

<CardGroup>
  <Card title="Python working sample" href="https://github.com/box-community/box-automate-invoice-intake" icon="github">
    Clone the Flask app, add your Box credentials, and run.
  </Card>

  <Card title="TypeScript working sample" href="https://github.com/box-community/box-automate-invoice-intake-typescript" icon="github">
    Clone the Express app, add your Box credentials, and run.
  </Card>
</CardGroup>

<AccordionGroup>
  <Accordion title="1. Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir invoice-intake && cd invoice-intake
    ```

    2. Install dependencies for your language:

    <CodeGroup>
      ```bash Python theme={null}
      python3 -m venv .venv
      source .venv/bin/activate
      pip install "boxsdk~=10" flask python-dotenv
      ```

      ```bash TypeScript theme={null}
      npm init -y
      npm install box-node-sdk@10 express dotenv
      npm install -D typescript tsx @types/node @types/express
      npx tsc --init --rootDir . --outDir dist --module commonjs --moduleResolution node --esModuleInterop --strict
      ```
    </CodeGroup>

    <Note>
      **Python:** After activation, your terminal prompt shows `(.venv)` at the beginning. Every time you open a new terminal window or tab, re-activate the virtual environment with `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError`, the venv is usually not activated.

      **TypeScript:** `tsx` runs TypeScript directly during development. You can compile with `npx tsc` for production builds.
    </Note>

    3. Create a `.env` file to store your credentials then add the following content. Replace the placeholder values with your actual credentials from the Box Developer Console:

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    BOX_METADATA_TEMPLATE_KEY=your_metadata_template_key
    INVOICES_FOLDER_ID=your_folder_id
    ```

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>

    <Note>
      **Understanding environment variables:** The `.env` file stores sensitive values (your actual credentials). Your code reads these values by referencing their **names**. When you copy the code in the following steps, keep the quoted variable names exactly as shown. Do not replace them with your actual credentials.
    </Note>
  </Accordion>

  <Accordion title="2. Authenticate the Box client">
    Create the Box client module in your project directory:

    <CodeGroup>
      ```python Python theme={null}
      # box_client.py
      import os
      from dotenv import load_dotenv
      from box_sdk_gen import (
          BoxClient,
          BoxCCGAuth,
          CCGConfig,
      )

      load_dotenv()

      def get_box_client() -> BoxClient:
          config = CCGConfig(
              client_id=os.getenv("BOX_CLIENT_ID"),
              client_secret=os.getenv("BOX_CLIENT_SECRET"),
              enterprise_id=os.getenv("BOX_ENTERPRISE_ID"),
          )
          auth = BoxCCGAuth(config=config)
          return BoxClient(auth=auth)
      ```

      ```typescript TypeScript theme={null}
      // boxClient.ts
      import 'dotenv/config';
      import { BoxClient, BoxCcgAuth, CcgConfig } from 'box-node-sdk';

      export function getBoxClient(): BoxClient {
        const config = new CcgConfig({
          clientId: process.env.BOX_CLIENT_ID!,
          clientSecret: process.env.BOX_CLIENT_SECRET!,
          enterpriseId: process.env.BOX_ENTERPRISE_ID!,
        });
        const auth = new BoxCcgAuth({ config });
        return new BoxClient({ auth });
      }
      ```
    </CodeGroup>

    <Tip>
      Client Credentials Grant is recommended for server-to-server automations where no end user is present. For other authentication options, see the <Link href="/guides/authentication">authentication overview</Link>.
    </Tip>
  </Accordion>

  <Accordion title="3. Build the extraction function">
    Create the extraction module. This is the core of the service. It takes a file ID, calls Box AI to extract fields using your metadata template, and returns the structured result.

    <CodeGroup>
      ```python Python theme={null}
      # extract.py
      import os
      from dotenv import load_dotenv
      from box_sdk_gen import (
          AiItemBase,
          BoxClient,
          CreateAiExtractStructuredMetadataTemplate,
          CreateAiExtractStructuredMetadataTemplateTypeField,
      )

      load_dotenv()

      def extract_invoice_fields(client: BoxClient, file_id: str) -> dict:
          template_key = os.getenv("BOX_METADATA_TEMPLATE_KEY")

          result = client.ai.create_ai_extract_structured(
              items=[AiItemBase(id=file_id)],
              metadata_template=CreateAiExtractStructuredMetadataTemplate(
                  template_key=template_key,
                  type=CreateAiExtractStructuredMetadataTemplateTypeField.METADATA_TEMPLATE,
                  scope="enterprise",
              ),
          )

          return result.to_dict()["answer"]
      ```

      ```typescript TypeScript theme={null}
      // extract.ts
      import 'dotenv/config';
      import { BoxClient } from 'box-node-sdk';
      import { AiItemBase } from 'box-node-sdk/schemas/aiItemBase';

      export async function extractInvoiceFields(
        client: BoxClient,
        fileId: string,
      ): Promise<Record<string, unknown>> {
        const templateKey = process.env.BOX_METADATA_TEMPLATE_KEY!;

        const result = await client.ai.createAiExtractStructured({
          items: [new AiItemBase({ id: fileId })],
          metadataTemplate: {
            templateKey,
            type: 'metadata_template',
            scope: 'enterprise',
          },
        });

        return result.answer as Record<string, unknown>;
      }
      ```
    </CodeGroup>

    The metadata template tells Box AI exactly which fields to look for and what data types to return. This means the response shape is predictable and consistent, regardless of how each vendor formats their invoices.
  </Accordion>

  <Accordion title="4. Write metadata back to the file">
    Create the metadata module. After extraction, this function attaches the extracted values to the file as a metadata instance:

    <CodeGroup>
      ```python Python theme={null}
      # metadata.py
      import os
      from dotenv import load_dotenv
      from box_sdk_gen import (
          BoxAPIError,
          BoxClient,
          CreateFileMetadataByIdScope,
          UpdateFileMetadataByIdRequestBody,
          UpdateFileMetadataByIdRequestBodyOpField,
          UpdateFileMetadataByIdScope,
      )

      load_dotenv()

      def apply_metadata(client: BoxClient, file_id: str, metadata: dict) -> dict:
          template_key = os.getenv("BOX_METADATA_TEMPLATE_KEY")

          try:
              attached = client.file_metadata.create_file_metadata_by_id(
                  file_id=file_id,
                  scope=CreateFileMetadataByIdScope.ENTERPRISE,
                  template_key=template_key,
                  request_body=metadata,
              )
          except BoxAPIError as error:
              if error.response_info.status_code != 409:
                  raise

              attached = client.file_metadata.update_file_metadata_by_id(
                  file_id=file_id,
                  scope=UpdateFileMetadataByIdScope.ENTERPRISE,
                  template_key=template_key,
                  request_body=[
                      UpdateFileMetadataByIdRequestBody(
                          op=UpdateFileMetadataByIdRequestBodyOpField.ADD,
                          path=f"/{key}",
                          value=value,
                      )
                      for key, value in metadata.items()
                  ],
              )

          return attached.to_dict()
      ```

      ```typescript TypeScript theme={null}
      // metadata.ts
      import 'dotenv/config';
      import { BoxApiError, BoxClient } from 'box-node-sdk';

      export async function applyMetadata(
        client: BoxClient,
        fileId: string,
        metadata: Record<string, unknown>,
      ) {
        const templateKey = process.env.BOX_METADATA_TEMPLATE_KEY!;

        try {
          return await client.fileMetadata.createFileMetadataById(
            fileId,
            'enterprise',
            templateKey,
            metadata,
          );
        } catch (error) {
          if (!(error instanceof BoxApiError) || error.responseInfo.statusCode !== 409) {
            throw error;
          }

          return client.fileMetadata.updateFileMetadataById(
            fileId,
            'enterprise',
            templateKey,
            Object.entries(metadata).map(([key, value]) => ({
              op: 'add' as const,
              path: `/${key}`,
              value,
            })),
          );
        }
      }
      ```
    </CodeGroup>

    <Note>
      Creating metadata only succeeds the first time. If the file already has an instance of the template, Box returns `409 Conflict on Metadata Instance`, so this function falls back to a JSON-Patch update. That keeps the service safe to re-run on a file you already processed, which happens with duplicate webhook deliveries and resent invoices.

      Use the `add` operation rather than `replace`. `add` sets a value whether or not the field is already present, so the update still succeeds when Box AI returns fewer fields than the previous run.
    </Note>

    Once metadata is attached, the extracted fields become searchable, filterable, and visible in the Box web app. You can use <Link href="/guides/metadata/queries">metadata queries</Link> to find all invoices above a certain amount, filter by vendor, or build dashboards in Box Apps.
  </Accordion>

  <Accordion title="5. Create the webhook listener">
    Create the HTTP application that receives webhook notifications when new files arrive in the inbox folder:

    <CodeGroup>
      ```python Python theme={null}
      # app.py
      import os
      import json

      from dotenv import load_dotenv
      from flask import Flask, request, jsonify

      from box_client import get_box_client
      from extract import extract_invoice_fields
      from metadata import apply_metadata

      load_dotenv()
      app = Flask(__name__)

      @app.route("/webhook", methods=["POST"])
      def handle_webhook():
          payload = request.get_json()

          if payload.get("trigger") != "FILE.UPLOADED":
              return jsonify({"status": "ignored"}), 200

          file_id = payload["source"]["id"]
          file_name = payload["source"]["name"]

          if not file_name.lower().endswith(".pdf"):
              return jsonify({"status": "skipped, not a PDF"}), 200

          client = get_box_client()

          extracted = extract_invoice_fields(client, file_id)
          print(f"Extracted from {file_name}: {json.dumps(extracted, indent=2)}")

          apply_metadata(client, file_id, extracted)
          print(f"Metadata applied to file {file_id}")

          return jsonify({"status": "processed", "file_id": file_id}), 200

      if __name__ == "__main__":
          app.run(port=5000)
      ```

      ```typescript TypeScript theme={null}
      // app.ts
      import express, { Request, Response } from 'express';
      import { getBoxClient } from './boxClient';
      import { extractInvoiceFields } from './extract';
      import { applyMetadata } from './metadata';

      const app = express();
      app.use(express.json());

      app.post('/webhook', async (req: Request, res: Response) => {
        const payload = req.body;

        if (payload?.trigger !== 'FILE.UPLOADED') {
          res.status(200).json({ status: 'ignored' });
          return;
        }

        const fileId = payload.source.id as string;
        const fileName = payload.source.name as string;

        if (!fileName.toLowerCase().endsWith('.pdf')) {
          res.status(200).json({ status: 'skipped, not a PDF' });
          return;
        }

        const client = getBoxClient();

        const extracted = await extractInvoiceFields(client, fileId);
        console.log(`Extracted from ${fileName}:`, JSON.stringify(extracted, null, 2));

        await applyMetadata(client, fileId, extracted);
        console.log(`Metadata applied to file ${fileId}`);

        res.status(200).json({ status: 'processed', file_id: fileId });
      });

      app.listen(5000, () => {
        console.log('Listening on http://127.0.0.1:5000');
      });
      ```
    </CodeGroup>

    <Note>
      In production, you should verify webhook signatures to confirm that requests originate from Box. See <Link href="/guides/webhooks/v2/signatures-v2">Verify webhook signatures</Link> for implementation details.
    </Note>

    At this point, your project directory should contain the following files:

    <CodeGroup>
      ```text Python theme={null}
      invoice-intake/
      ├── .env
      ├── .venv/
      ├── app.py
      ├── box_client.py
      ├── extract.py
      └── metadata.py
      ```

      ```text TypeScript theme={null}
      invoice-intake/
      ├── .env
      ├── package.json
      ├── tsconfig.json
      ├── node_modules/
      ├── app.ts
      ├── boxClient.ts
      ├── extract.ts
      └── metadata.ts
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

When you finish scaffolding, continue to [Run and verify](#run-and-verify).

## Run and verify

You can test the extraction pipeline locally without setting up a public URL or webhook. This simulates what Box would send when a new file arrives.

<Note>
  This requires **two terminal windows** open at the same time. Terminal 1 runs the server (which must stay running). Terminal 2 sends a test request to it.
</Note>

1. **Terminal 1 - start the server.** Make sure you are in the `invoice-intake` directory, then use the command for your stack:

   <CodeGroup>
     ```bash Python theme={null}
     # Flask
     cd ~/invoice-intake
     source .venv/bin/activate
     python3 app.py

     # FastAPI (idiomatic package layout)
     cd ~/invoice-intake
     source .venv/bin/activate
     uvicorn app.main:app --host 127.0.0.1 --port 5000
     ```

     ```bash TypeScript theme={null}
     # Express (flat tutorial layout)
     cd ~/invoice-intake
     npx tsx app.ts

     # Fastify (idiomatic src/ layout)
     cd ~/invoice-intake
     npm start
     ```

     ```bash Node theme={null}
     # Express
     cd ~/invoice-intake
     node app.js

     # NestJS
     cd ~/invoice-intake
     npm start
     ```

     ```bash Java theme={null}
     # Spring Boot
     cd ~/invoice-intake
     export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"   # if needed
     mvn spring-boot:run

     # Quarkus
     cd ~/invoice-intake
     export PATH="/opt/homebrew/opt/openjdk@17/bin:$PATH"   # if needed
     mvn quarkus:dev
     ```

     ```bash .NET theme={null}
     # ASP.NET Core or Minimal APIs
     # From the web project directory (or pass --project <path-to-csproj>)
     cd ~/invoice-intake
     dotnet run
     ```
   </CodeGroup>

   You should see the server listening on port 5000. Leave this terminal running.

2. **Terminal 2 - send a test request.** Open a new terminal tab or window. Send a simulated webhook payload using curl. Replace `<FILE_ID>` with the **file ID** of the invoice PDF you uploaded to Box.

   <Warning>
     Use the file ID, not the folder ID. The file ID comes from the file's URL: `https://app.box.com/file/123456789` → the file ID is `123456789`. The folder ID comes from a different URL pattern: `https://app.box.com/folder/987654321`.
   </Warning>

   ```bash theme={null}
   curl -X POST http://127.0.0.1:5000/webhook \
     -H "Content-Type: application/json" \
     -d '{
       "trigger": "FILE.UPLOADED",
       "source": {
         "id": "<FILE_ID>",
         "name": "sample-invoice.pdf"
       }
     }'
   ```

3. **Check the result.** Switch back to Terminal 1. You should see the extracted fields printed, followed by a confirmation that metadata was applied:

   ```
   Extracted from sample-invoice.pdf: {
     "vendorName": "ACME Corp",
     "invoiceNumber": "INV-001",
     "invoiceDate": "2025-03-15T00:00:00Z",
     "dueDate": "2025-04-15T00:00:00Z",
     "totalAmount": 1250.00,
     "currency": "USD"
   }
   Metadata applied to file 123456789
   ```

   Open the file in Box and select the **Metadata** tab to verify the values were written correctly.

## Register a webhook for production

The local curl test simulates what Box sends, but for a production deployment you need Box to send real webhook notifications automatically. This requires a publicly accessible HTTPS endpoint:

```bash theme={null}
curl -X POST https://api.box.com/2.0/webhooks \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "target": {
      "id": "<FOLDER_ID>",
      "type": "folder"
    },
    "address": "<webhook_url>",
    "triggers": ["FILE.UPLOADED"]
  }'
```

Replace `<FOLDER_ID>` with your invoices folder ID and update the `address` to your tunnel URL with `/webhook` appended.

Once registered, any PDF uploaded to the folder automatically triggers extraction and metadata application.

## Optional: push totals to an ERP

Once you have structured metadata, pushing data downstream is straightforward. After metadata is applied, start from the Box AI extract object:

```json theme={null}
{
  "vendorName": "ACME Corp",
  "invoiceNumber": "INV-001",
  "invoiceDate": "2025-03-15T00:00:00Z",
  "dueDate": "2025-04-15T00:00:00Z",
  "totalAmount": 1250.00,
  "currency": "USD"
}
```

Map those fields (and the Box file ID, if your ERP needs an external reference) into whatever shape your ERP expects, then POST with your stack's normal HTTP client.

## Scaling to production

<AccordionGroup>
  <Accordion title="Handle duplicate deliveries">
    Box webhook delivery can produce duplicates. The 409 fallback in `apply_metadata` already keeps the write safe, but a duplicate still pays for a second Box AI extraction. To skip that work, check for an existing instance with `GET /2.0/files/:id/metadata/enterprise/:template` at the top of the handler and return early if one is present.

    Only skip when a repeat run is redundant. If vendors resend corrected invoices under the same file ID, let the extraction run so the metadata reflects the latest version.
  </Accordion>

  <Accordion title="Process at scale with event streams">
    For high-volume environments, consider using <Link href="/guides/events/enterprise-events/for-enterprise">enterprise events</Link> instead of webhooks. Enterprise events provide a durable, polling-based stream that is better suited to batch processing thousands of invoices.
  </Accordion>

  <Accordion title="Use the Enhanced Extract Agent for complex invoices">
    If your invoices contain complex layouts, multi-page line items, or non-standard formatting, use the <Link href="/guides/box-ai/quick-start/box-ai-extract-enhanced">Enhanced Extract Agent</Link> for improved accuracy. Add this agent reference to your existing `POST /2.0/ai/extract_structured` call (alongside the metadata template):

    ```json theme={null}
    {
      "ai_agent": {
        "type": "ai_agent_id",
        "id": "enhanced_extract_agent"
      }
    }
    ```

    Pass it the same way your SDK already passes `metadata_template` / `metadataTemplate`. For SDK-specific samples, see the <Link href="/guides/box-ai/quick-start/box-ai-extract-enhanced">Enhanced Extract Agent quick start</Link>.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your Python virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="Cannot find module 'box-node-sdk' or similar">
    From the project directory, run `npm install`. Confirm `box-node-sdk` appears in `package.json` dependencies and that you are using Node.js 20 or higher (`node -v`).
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Configuration.
    * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID (found in Admin Console > Account & Billing, or Developer Console > icon in the top-right > Copy Enterprise ID).
    * Ensure your app is authorized in the Developer Console.
    * Make sure the app type is Client Credentials Grant.
  </Accordion>

  <Accordion title="404 Not Found">
    The service account does not have access to the file or folder. Invite the service account email (found in Developer Console > General Settings) as a collaborator with **Editor** role on the folder containing your invoice files.
  </Accordion>

  <Accordion title="metadata_template must have both scope and template_key">
    The `BOX_METADATA_TEMPLATE_KEY` value in your `.env` file is missing or empty. Add the template key you noted when creating the metadata template in [Before you start](#before-you-start).
  </Accordion>

  <Accordion title="409 Conflict on Metadata Instance">
    The file already has an instance of the template, so creating one fails. This is common when you retest a file that a previous run already processed. Extraction succeeded; only the metadata write failed.

    Add the 409 fallback shown in [Build by hand](#build-by-hand) under **4. Write metadata back to the file** so the service updates the existing instance instead of creating a second one. To retest with a clean file, remove the instance from the file's **Metadata** tab in Box, or delete it through the API:

    ```bash theme={null}
    curl -X DELETE "https://api.box.com/2.0/files/<FILE_ID>/metadata/enterprise/<TEMPLATE_KEY>" \
      -H "Authorization: Bearer <ACCESS_TOKEN>"
    ```
  </Accordion>

  <Accordion title="The agent tried to create the template or folder">
    The template, inbox folder, and enterprise ID come from [Before you start](#before-you-start); an agent cannot create them. Re-paste the prompt with the prerequisites block intact so the agent reads `BOX_METADATA_TEMPLATE_KEY`, `INVOICES_FOLDER_ID`, and `BOX_ENTERPRISE_ID` from the environment, or follow [Build by hand](#build-by-hand).
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Sales RFP answer bank" href={localizeLink("/tutorials/sales-rfp-answer-bank")} icon="magnifying-glass">
    Build an AI-powered knowledge base for sales teams using Box Hubs and Box AI.
  </Card>

  <Card title="Extract API reference" href={localizeLink("/reference/post-ai-extract-structured")} icon="code">
    See the full API specification for structured extraction.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Build an NDA risk summary with Box AI Extract
Source: https://developer.box.com/tutorials/nda-risk-summary

Extract key clauses from an NDA or MSA with Box AI structured extraction, turn them into a Deal Risk Summary as JSON and markdown, and save the summary back to Box as a companion file.

Legal teams review the same handful of clauses in every non-disclosure agreement (NDA) and master service agreement (MSA): what law governs it, how long it lasts, how either side can walk away, how long confidentiality survives, and whether liability is capped. Reading each document by hand is slow, and asking a model open-ended questions ("What are the risky terms in this contract?") returns different answers every time.

This tutorial takes a more structured approach: **extract, don't prompt.** You define a fixed extraction schema, so Box AI returns the same clauses in the same shape for every document. You then turn that predictable output into a *Deal Risk Summary* and save it back to Box as a companion file that reviewers can open next to the original.

<Card title="Clone the working sample" href="https://github.com/box-community/box-nda-risk-summary" icon="github">
  Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
</Card>

## What you are building

By the end of this tutorial, you have a working Python project that:

* Authenticates to Box and reads an NDA stored in a Box folder.
* Defines a clause-extraction schema for governing law, term, termination, confidentiality period, and liability cap.
* Calls the [POST /2.0/ai/extract\_structured](/reference/post-ai-extract-structured) endpoint with confidence scores and source references enabled.
* Applies a simple, transparent rule set to score each clause and assemble a Deal Risk Summary in JSON and markdown.
* Uploads the summary back to Box as a companion file, so the analysis lives alongside the source document.

<Note>
  This tutorial focuses on an NDA, but the same schema and workflow apply to a master service agreement (MSA) or most other commercial contracts. Adjust the fields in `schema.py` to match the clauses you care about.
</Note>

## Why extract instead of prompting

A free-form prompt asks the model to decide *what* to return and *how* to format it, so the response shape drifts between documents and runs. Structured extraction inverts that: you declare the fields, and Box AI fills them in.

| Approach | Output | Best for |
| - | - | - |
| Ad-hoc prompt (`POST /2.0/ai/ask`) | Free-form text that varies per run | Exploratory questions, summaries for a human to read |
| Structured extraction (`POST /2.0/ai/extract_structured`) | A consistent, typed JSON object keyed by your fields | Repeatable pipelines, scoring, and downstream automation |

Because the output is predictable, you can score it with plain code and trust that the summary looks the same for every contract. Enabling **confidence scores** and **source references** on the extraction call also lets you flag clauses that need a human's eyes.

<Warning>
  The risk scoring in this tutorial is illustrative and intended for triage only. It is not legal advice, and it does not replace review by a qualified professional. Treat the summary as a starting point that routes attention, not as a decision.
</Warning>

## Prerequisites

Before you start, make sure you have the following:

* A free <Link href="https://account.box.com/signup/developer">Box developer account</Link>, which gives you access to the Box AI API.
* A Box application configured with **Client Credentials Grant** authentication.
* Python 3.11 or higher.
* An NDA uploaded to Box. You can download a <Link href="/static/quickstarts/extract/files/nda-sample.pdf">sample NDA</Link> and upload it to a Box folder. Note its **file ID** from the URL. For example, if the URL is `https://app.box.com/file/123456789`, the file ID is `123456789`. Because a Client Credentials Grant app authenticates as a separate service account, add that service account as a collaborator with the **Editor** role on the file (or its parent folder) so it can read the NDA. You find the service account email in the **Authenticate the Box client** step.
* A Box folder where the service account can write the summary, with the same service account added as an **Editor** collaborator. Note its **folder ID** from the URL.
* The following scopes enabled on your app:
  * Read and write all files and folders stored in Box
  * Manage AI

## Step-by-step process

This tutorial uses two Box capabilities:

| Component | Purpose | API |
| - | - | - |
| **Box AI Extract** | Pull the five clauses as typed fields, with confidence scores and references | `POST /2.0/ai/extract_structured` |
| **Uploads** | Save the generated summary back to Box as a companion file | `POST https://upload.box.com/api/2.0/files/content` |

This tutorial uses the default Extract Agent to keep the setup simple, since you don't configure an agent. Confidence scoring is available either way: the default Extract Agent runs on Gemini 2.5 Flash and the [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent) runs on Gemini 2.5 Pro. If your NDAs have complex or scanned layouts, see [Scaling to production](#scaling-to-production) for how to switch to the Enhanced Extract Agent without losing confidence scores.

<Tip>
  Prefer not to build the project step by step? Clone the <Link href="https://github.com/box-community/box-nda-risk-summary">sample code</Link> for this tutorial and run it directly.
</Tip>

<Steps>
  <Step title="Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir nda-risk-summary && cd nda-risk-summary
    ```

    2. Create and activate a Python virtual environment:

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    After activation, your terminal prompt shows `(.venv)` at the beginning. This confirms you are working inside the virtual environment.

    <Note>
      Every time you open a new terminal window or tab, re-activate the virtual environment by running `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError` when running commands, it usually means the venv is not activated.
    </Note>

    3. Install the required packages:

    ```bash theme={null}
    pip install boxsdk python-dotenv
    ```

    <Note>
      Installing `boxsdk` gives you the `box_sdk_gen` module used throughout this tutorial. Confidence scores and source references are available directly on the SDK's `create_ai_extract_structured` method through the `include_confidence_score` and `include_reference` parameters.
    </Note>

    4. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your actual credentials from the [Box Developer Console](https://app.box.com/developers/console):

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    NDA_FILE_ID=your_file_id
    OUTPUT_FOLDER_ID=your_folder_id
    ```

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>
  </Step>

  <Step title="Authenticate the Box client">
    In your project, create a file called `box_client.py` and add the following code. It builds an authenticated client that you use to call Box AI and the uploads API through the SDK.

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig

    load_dotenv()

    def get_box_client() -> BoxClient:
        config = CCGConfig(
            client_id=os.getenv("BOX_CLIENT_ID"),
            client_secret=os.getenv("BOX_CLIENT_SECRET"),
            enterprise_id=os.getenv("BOX_ENTERPRISE_ID"),
        )
        auth = BoxCCGAuth(config=config)
        return BoxClient(auth=auth)
    ```

    <Warning>
      A CCG application acts as a separate service account user that does not automatically have access to your content. Invite the service account email (found in the [Developer Console](https://app.box.com/developers/console) under **General Settings**) as a collaborator with the **Editor** role on both the folder that contains your NDA and the output folder. Editor access is required because the app writes the summary file back to Box. Without access, API calls return `404 Not Found`.
    </Warning>
  </Step>

  <Step title="Define the clause schema">
    Create a file called `schema.py` and add the following code. Each field tells Box AI exactly what to look for. The `prompt` on each field adds context that improves accuracy on dense legal language. The fields are `CreateAiExtractStructuredFields` objects that you pass directly to the SDK's extraction call in the next step.

    ```python theme={null}
    from box_sdk_gen import CreateAiExtractStructuredFields

    EXTRACTION_FIELDS = [
        CreateAiExtractStructuredFields(
            key="governing_law",
            display_name="Governing law",
            type="string",
            prompt="The governing law or jurisdiction that applies to the agreement.",
        ),
        CreateAiExtractStructuredFields(
            key="term",
            display_name="Term",
            type="string",
            prompt="The overall duration of the agreement, including any renewal terms.",
        ),
        CreateAiExtractStructuredFields(
            key="termination",
            display_name="Termination",
            type="string",
            prompt="The termination conditions, including any required notice period.",
        ),
        CreateAiExtractStructuredFields(
            key="confidentiality_period",
            display_name="Confidentiality period",
            type="string",
            prompt="How long confidentiality obligations remain in effect after termination.",
        ),
        CreateAiExtractStructuredFields(
            key="liability_cap",
            display_name="Liability cap",
            type="string",
            prompt="The limitation of liability or liability cap, including any amount and currency.",
        ),
    ]
    ```

    <Tip>
      A clear, specific `prompt` and `description` improve both the extracted value and its confidence score.
    </Tip>
  </Step>

  <Step title="Extract the clauses">
    Create a file called `extract.py` and add the following code. It uses the SDK's `create_ai_extract_structured` method to send the schema to Box AI and asks for confidence scores and source references alongside the extracted values.

    ```python theme={null}
    from box_sdk_gen import AiItemBase

    from box_client import get_box_client
    from schema import EXTRACTION_FIELDS

    def extract_clauses(file_id: str) -> dict:
        client = get_box_client()

        response = client.ai.create_ai_extract_structured(
            items=[AiItemBase(id=file_id)],
            fields=EXTRACTION_FIELDS,
            include_confidence_score=True,
            include_reference=True,
        )

        return {
            "answer": response.answer or {},
            "confidence_score": response.confidence_score or {},
            "reference": response.reference or {},
        }
    ```

    The response includes three parts you use in the next step:

    * `answer` holds the extracted value for each field.
    * `confidence_score` holds a `level` (`LOW`, `MEDIUM`, or `HIGH`) and a numeric `score` between 0 and 1 for each field.
    * `reference` holds the source text and its location in the document for each field.

    <Note>
      `reference` returns the exact snippet and location Box AI used for each field. Its contents are passed straight through into your summary file in a later step so a reviewer can trace every value back to the source. For background, see the <Link href="/changelog">Reference in extract</Link> changelog entry.
    </Note>
  </Step>

  <Step title="Score risk and build the summary">
    Create a file called `risk.py` and add the following code. It applies a small, transparent rule set to each clause, assigns a severity, and assembles the Deal Risk Summary as a dictionary. It also renders a markdown version for humans.

    ```python theme={null}
    CLAUSES = [
        "governing_law",
        "term",
        "termination",
        "confidentiality_period",
        "liability_cap",
    ]

    APPROVED_JURISDICTIONS = ["delaware", "new york", "california", "england"]

    SEVERITY_ORDER = {"none": 0, "low": 1, "medium": 2, "high": 3}

    def assess_clause(key: str, value, confidence: dict):
        # A missing clause is the highest risk: it could not be located in the document.
        if not value:
            return "high", "Clause not found. Review the document manually."

        severity, note = "low", "Clause found."

        if key == "liability_cap" and any(
            term in value.lower() for term in ["unlimited", "no cap", "not limited"]
        ):
            severity, note = "high", "Liability appears to be uncapped."
        elif key == "governing_law" and not any(
            j in value.lower() for j in APPROVED_JURISDICTIONS
        ):
            severity, note = "medium", "Governing law is outside the approved list."

        # A low-confidence extraction is never treated as better than medium risk.
        score = (confidence or {}).get("score", 1)
        if score < 0.7 and SEVERITY_ORDER[severity] < SEVERITY_ORDER["medium"]:
            severity = "medium"
            note = f"{note} Low extraction confidence ({score:.2f}); verify against the source."

        return severity, note

    def build_risk_summary(extraction: dict, document: str) -> dict:
        answer = extraction["answer"]
        scores = extraction["confidence_score"]
        references = extraction["reference"]

        findings = []
        for key in CLAUSES:
            value = answer.get(key)
            confidence = scores.get(key)
            severity, note = assess_clause(key, value, confidence)
            findings.append({
                "clause": key,
                "value": value,
                "severity": severity,
                "note": note,
                "confidence": confidence,
                "source": references.get(key),
            })

        overall = max(findings, key=lambda f: SEVERITY_ORDER[f["severity"]])["severity"]
        return {"document": document, "overall_risk": overall, "findings": findings}

    def to_markdown(summary: dict) -> str:
        lines = [
            f"# Deal Risk Summary: {summary['document']}",
            "",
            f"**Overall risk:** {summary['overall_risk'].upper()}",
            "",
            "> Generated automatically for triage only. This is not legal advice.",
            "",
            "| Clause | Value | Risk | Confidence | Notes |",
            "| --- | --- | --- | --- | --- |",
        ]
        for f in summary["findings"]:
            level = f["confidence"]["level"] if f["confidence"] else "N/A"
            value = f["value"] or "_Not found_"
            clause = f["clause"].replace("_", " ").title()
            lines.append(
                f"| {clause} | {value} | {f['severity'].upper()} | {level} | {f['note']} |"
            )
        return "\n".join(lines)
    ```

    <Tip>
      Keep the rules in `assess_clause` obvious and easy to edit. Adjust `APPROVED_JURISDICTIONS`, the confidence threshold, or the clause-specific checks to match your organization's playbook.
    </Tip>
  </Step>

  <Step title="Save the summary back to Box">
    Create a file called `app.py` and add the following code. It runs the extraction, builds the summary, and uploads both the JSON and markdown versions to your output folder as companion files.

    ```python theme={null}
    import io
    import json
    import os

    from dotenv import load_dotenv
    from box_sdk_gen import UploadFileAttributes, UploadFileAttributesParentField

    from box_client import get_box_client
    from extract import extract_clauses
    from risk import build_risk_summary, to_markdown

    load_dotenv()

    def upload_companion_file(client, folder_id: str, name: str, content: str) -> str:
        files = client.uploads.upload_file(
            attributes=UploadFileAttributes(
                name=name,
                parent=UploadFileAttributesParentField(id=folder_id),
            ),
            file=io.BytesIO(content.encode("utf-8")),
        )
        return files.entries[0].id

    if __name__ == "__main__":
        file_id = os.getenv("NDA_FILE_ID")
        folder_id = os.getenv("OUTPUT_FOLDER_ID")

        extraction = extract_clauses(file_id)
        print("Raw extraction:")
        print(json.dumps(extraction, indent=2))

        summary = build_risk_summary(extraction, document=f"NDA-{file_id}")
        markdown = to_markdown(summary)

        print("\nDeal Risk Summary:")
        print(markdown)

        client = get_box_client()
        json_id = upload_companion_file(
            client, folder_id, f"{summary['document']}-risk-summary.json",
            json.dumps(summary, indent=2),
        )
        md_id = upload_companion_file(
            client, folder_id, f"{summary['document']}-risk-summary.md", markdown,
        )

        print(f"\nUploaded JSON summary (file ID {json_id}) and markdown summary (file ID {md_id}).")
    ```

    At this point, your project directory should contain the following files:

    ```
    nda-risk-summary/
    ├── .env
    ├── .venv/
    ├── app.py
    ├── box_client.py
    ├── extract.py
    ├── risk.py
    └── schema.py
    ```

    <Note>
      Uploading the summary as a new, separate file keeps the original NDA untouched. If you would rather version the source document itself, use `client.uploads.upload_file_version(file_id, ...)` instead, but note that replacing a PDF with a markdown or JSON body changes the file's type.
    </Note>
  </Step>

  <Step title="Run the extraction">
    Make sure you are in the `nda-risk-summary` directory with the virtual environment activated, then run the script:

    ```bash theme={null}
    python3 app.py
    ```

    Box AI returns the extracted clauses together with a confidence score for each field. Your raw extraction looks similar to this (the `reference` object is omitted here for brevity):

    ```json theme={null}
    {
      "answer": {
        "governing_law": "State of New York",
        "term": "Two years from the Effective Date",
        "termination": "Either party may terminate with 30 days written notice.",
        "confidentiality_period": "Three years after termination",
        "liability_cap": "Fees paid in the 12 months preceding the claim"
      },
      "confidence_score": {
        "governing_law": { "level": "HIGH", "score": 0.95 },
        "term": { "level": "HIGH", "score": 0.92 },
        "termination": { "level": "MEDIUM", "score": 0.81 },
        "confidentiality_period": { "level": "MEDIUM", "score": 0.78 },
        "liability_cap": { "level": "LOW", "score": 0.64 }
      }
    }
    ```

    The script then prints the Deal Risk Summary. Because the liability cap was extracted with low confidence, it is raised to medium risk, which sets the overall risk for the document:

    ```markdown theme={null}
    # Deal Risk Summary: NDA-123456789

    **Overall risk:** MEDIUM

    > Generated automatically for triage only. This is not legal advice.

    | Clause | Value | Risk | Confidence | Notes |
    | --- | --- | --- | --- | --- |
    | Governing Law | State of New York | LOW | HIGH | Clause found. |
    | Term | Two years from the Effective Date | LOW | HIGH | Clause found. |
    | Termination | Either party may terminate with 30 days written notice. | LOW | MEDIUM | Clause found. |
    | Confidentiality Period | Three years after termination | LOW | MEDIUM | Clause found. |
    | Liability Cap | Fees paid in the 12 months preceding the claim | MEDIUM | LOW | Clause found. Low extraction confidence (0.64); verify against the source. |
    ```

    Finally, open your output folder in Box. You should see two new files: `NDA-123456789-risk-summary.json` and `NDA-123456789-risk-summary.md`, sitting alongside your other content and ready for review.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Configuration.
    * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID.
    * Ensure your app is authorized in the Developer Console and uses Client Credentials Grant.
  </Accordion>

  <Accordion title="404 Not Found">
    The service account does not have access to the file or folder. Invite the service account email (found in Developer Console > General Settings) as a collaborator with the **Editor** role on both the NDA's folder and the output folder.
  </Accordion>

  <Accordion title="confidence_score or reference is empty in the response">
    Confirm your extraction call sets `include_confidence_score` and `include_reference` to `True`, as shown in `extract.py`. Confidence estimation also depends on the model behind the extraction agent.
  </Accordion>

  <Accordion title="409 Item with the same name already exists">
    `app.py` uploads the summary using a deterministic name derived from the file ID (for example, `NDA-123456789-risk-summary.json`), so running the script again against the same output folder tries to create files that are already there. Delete the previous `-risk-summary.json` and `-risk-summary.md` files from the output folder, or point `OUTPUT_FOLDER_ID` at a different folder, before re-running.
  </Accordion>
</AccordionGroup>

## Scaling to production

<AccordionGroup>
  <Accordion title="Trigger the summary automatically on upload">
    Instead of running the script by hand, register a webhook on your NDA folder so every upload triggers extraction and write-back. See <Link href="/tutorials/invoice-intake">Automate invoice intake with Box AI Extract</Link> for an end-to-end webhook pattern, and <Link href="/guides/webhooks/v2/signatures-v2">Verify webhook signatures</Link> to validate incoming requests.
  </Accordion>

  <Accordion title="Route low-confidence clauses to human review">
    Use the confidence score to build a review queue: automatically accept high-confidence clauses and flag anything below your threshold for a person.
  </Accordion>

  <Accordion title="Handle complex or scanned documents">
    For multi-page contracts, dense tables, or scanned PDFs, switch to the <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent">Enhanced Extract Agent</Link> for better accuracy. It runs on Gemini 2.5 Pro, which supports confidence scoring, so you keep confidence scores and references when you switch. Add the agent to your extraction call:

    ```python theme={null}
    from box_sdk_gen import AiAgentReference, AiAgentReferenceTypeField

    response = client.ai.create_ai_extract_structured(
        items=[AiItemBase(id=file_id)],
        fields=EXTRACTION_FIELDS,
        include_confidence_score=True,
        include_reference=True,
        ai_agent=AiAgentReference(
            id="enhanced_extract_agent",
            type=AiAgentReferenceTypeField.AI_AGENT_ID,
        ),
    )
    ```

    You can confirm which model processed a request by checking `ai_agent_info.models` in the response.
  </Accordion>

  <Accordion title="Make summaries searchable with metadata">
    In addition to the companion file, write the top-level clause values back to the NDA as a Box <Link href="/guides/metadata/queries">metadata instance</Link>. You can then filter contracts by governing law, overall risk, or confidentiality period across your whole repository.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Supplier agreement extraction" href="/tutorials/supplier-agreements" icon="file-contract">
    Extract grouped and repeating structured data from a contract using the `struct` and `table` field types.
  </Card>

  <Card title="Extract API reference" href="/reference/post-ai-extract-structured" icon="code">
    See the full API specification for structured extraction.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Automate offer letter creation with Box Doc Gen and Box Sign
Source: https://developer.box.com/tutorials/offer-letter-creation

Build an HR workflow that generates offer letters with Box Doc Gen, routes them through Box Sign for HR approval, and delivers them to candidates for signature.

In modern document workflows, two of the most challenging parts are generating consistently formatted documents and managing e-signature execution at scale. This tutorial demonstrates how to address both challenges by integrating the Box Doc Gen API and the Box Sign API into a single, automated pipeline.

In this scenario, you build an automated pipeline that submits candidate data and gets a signed PDF back with no manual steps in between. Once you pass the candidate and offer details, the solution calls the Box Doc Gen API to merge that data into an offer letter template. When the PDF is ready, a Box webhook notifies the app which PDF file has been generated. This initiates a Box Sign request for that generated offer letter, which routes it through HR approval and candidate signature.

The code is minimal by design. The goal is to show the application pattern clearly so you
can extend it into a larger platform workflow, swap in your own templates, or add more
signers and approval steps. When your HR system sends candidate and offer details, the service:

1. Calls Box Doc Gen to merge the data into an offer letter template.
2. Listens for a Doc Gen completion webhook and records the generated PDF.
3. Creates a Box Sign request so an HR approver reviews the letter before the candidate signs.

<Card title="Clone the working sample" href="https://github.com/box-community/offer-letter-workflow" icon="github">
  Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
</Card>

## What you are building

By the end of this tutorial, you have a working Node.js service that:

* Accepts offer data from an applicant tracking system (ATS) or HR webhook.
* Validates the payload and calls Box Doc Gen to merge data into an offer letter template.
* Listens for a Doc Gen completion webhook and records the generated PDF file ID.
* Creates a Box Sign request with an HR approver and the candidate as signers.
* Exposes endpoints to trigger generation, send for signature, and check offer letter status.

<Note>
  This sample is designed to be triggered by an ATS such as Greenhouse, but the same pattern applies to Workday Recruiting, SAP SuccessFactors, or any HR system that can send a webhook and expose offer data through an API.
</Note>

## Prerequisites

Before you start, make sure you have the following:

* Node.js 18 or higher.
* A Box Enterprise Advanced account with <Link href="/guides/docgen/docgen-getting-started">Box Doc Gen</Link> entitlement and <Link href="/guides/box-sign">Box Sign</Link> enabled in the Admin Console. Box Doc Gen is not available on free developer accounts.
* A Box application configured with **Client Credentials Grant** authentication, authorized in the Admin Console. See <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link> for setup details.
* The Box enterprise ID for your account (`BOX_ENTERPRISE_ID`). The Client Credentials Grant app authenticates as the enterprise service account. Find it in the Developer Console under your app's **General Settings**, or in the Admin Console.

## Step-by-step process

This solution uses three Box Platform capabilities:

| Component | Purpose | API |
| - | - | - |
| **Box Doc Gen** | Merge candidate and offer data into a PDF from a template | `POST /2.0/docgen_batches` |
| **Webhooks** | Detect when document generation completes | Doc Gen webhook event (`DOCGEN_DOCUMENT_GENERATION_SUCCEEDED`) |
| **Box Sign** | Route the PDF through HR approval and candidate signature | `POST /2.0/sign_requests` |

<Steps>
  <Step title="Enable Box Doc Gen and Box Sign">
    Go to the Admin Console and navigate to the Enterprise Settings tab. Enable Box Doc Gen in the **Content & Sharing** tab and Box Sign in the **Box Sign** tab for selected users or all enterprise users.
  </Step>

  <Step title="Create Box folders">
    Create three folders in Box:

    1. `Offer Letter Template`
    2. `Generated Offer Letters`
    3. `Signed Offer Letters`

    Copy each folder ID from the Box web app URL (for example, `https://app.box.com/folder/123456789` → `123456789`). You need these values for the project variables `BOX_DOCGEN_DESTINATION_FOLDER_ID` and `BOX_SIGN_PARENT_FOLDER_ID`.

    Collaborate the app's service account into the template, generated-offer, and signed-offer folders with **Editor** access. Service accounts do not automatically have access to user-owned content. You can find the service account address (`AutomationUser_...@boxdevedition.com`) in the Developer Console under your app's **General Settings**.
  </Step>

  <Step title="Create an offer letter template">
    Use a preexisting Box Doc Gen template in the Box web app:

    1. Open the **Automate** tab in Box.
    2. Navigate to the **Doc Gen** tab.
    3. Select the **Employee Offer Letter** template.
    4. Select a destination folder for the template and generated documents.
    5. Select **Generate Document**, then save the **template file ID** from the page or from the URL.

    To match the sample template, the ATS payload must include the fields the `validateOffer` function checks in a later step: `id`, `country`, `contractDate`, `deliveryTerms`, `companyName`, `baseSalary`, `salaryDetails`, `salaryModel`, `employee.address`, `employee.dob`, `employee.email`, `employee.name`, `company.address`, `company.designatedSigner`, `company.name`, `company.designation`, `company.department`, `position`, `department`, and `startDate`.
  </Step>

  <Step title="Create and configure your Box application">
    Create a **Custom App** with **Server Authentication (Client Credentials Grant)** in the <Link href="https://app.box.com/developers/console">Box Developer Console</Link>.

    1. Enable the **Read all files and folders**, **Write all files and folders**, **Manage Doc Gen**, **Manage signature requests**, and **Manage webhooks** scopes.
    2. Save your changes and authorize the app in the Developer Console in **App Details** section under **Status**.
  </Step>

  <Step title="Set up the development environment">
    Build the project from scratch so you understand what each file does. The rest of this tutorial walks through every file.

    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir offer-letter-workflow && cd offer-letter-workflow
    ```

    2. Initialize `package.json` and enable ES modules. The service uses `import`/`export` syntax, so Node needs `"type": "module"` to run the files:

    ```bash theme={null}
    npm init -y
    npm pkg set type=module
    ```

    3. Install the required packages:

    ```bash theme={null}
    npm install box-node-sdk@^10 dotenv express
    ```

    4. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your credentials and folder IDs from the [Box Developer Console](https://app.box.com/developers/console):

    ```bash theme={null}
    PORT=8000
    APP_SHARED_SECRET=replace-me
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    BOX_DOCGEN_TEMPLATE_FILE_ID=your_template_file_id
    BOX_DOCGEN_DESTINATION_FOLDER_ID=your_generated_docs_folder_id
    BOX_SIGN_PARENT_FOLDER_ID=your_signed_docs_folder_id
    HR_APPROVER_EMAIL=hr.approver@example.com
    PUBLIC_BASE_URL=https://your-tunnel.example.com
    ```

    For local development, expose your server with a tunnel (for example, ngrok) and set `PUBLIC_BASE_URL` to the tunnel URL. In production, verify webhook signatures. See <Link href="/guides/webhooks/v2/signatures-v2">verify webhook signatures</Link>.
  </Step>

  <Step title="Create configuration and storage helpers">
    In your project, create a `config.js` file and add the following code. It loads environment variables used throughout the service:

    ```javascript theme={null}
    import "dotenv/config";
    const required = [
      "BOX_CLIENT_ID",
      "BOX_CLIENT_SECRET",
      "BOX_ENTERPRISE_ID",
      "BOX_DOCGEN_TEMPLATE_FILE_ID",
      "BOX_DOCGEN_DESTINATION_FOLDER_ID",
      "BOX_SIGN_PARENT_FOLDER_ID",
    ];

    export function readConfig() {
      const missing = required.filter((name) => !process.env[name]);
      if (missing.length > 0) {
        throw new Error(`Set required environment variables: ${missing.join(", ")}`);
      }

      return {
        port: Number(process.env.PORT || 8000),
        sharedSecret: process.env.APP_SHARED_SECRET,
        boxClientId: process.env.BOX_CLIENT_ID,
        boxClientSecret: process.env.BOX_CLIENT_SECRET,
        boxEnterpriseId: process.env.BOX_ENTERPRISE_ID,
        docgenTemplateFileId: process.env.BOX_DOCGEN_TEMPLATE_FILE_ID,
        docgenDestinationFolderId: process.env.BOX_DOCGEN_DESTINATION_FOLDER_ID,
        signParentFolderId: process.env.BOX_SIGN_PARENT_FOLDER_ID,
        hrApproverEmail: process.env.HR_APPROVER_EMAIL,
        publicBaseUrl: process.env.PUBLIC_BASE_URL,
      };
    }
    ```

    Create `store.js` with a simple in-memory store for the demo. Replace this with a database before you deploy to production.

    ```javascript theme={null}
    const offers = new Map();

    export function createOfferRecord(offer, docgenBatch) {
      const id = offer.id || docgenBatch.id;
      const record = {
        id,
        offer,
        docgenBatchId: docgenBatch.id,
        generatedFileId: null,
        signRequestId: null,
        status: "docgen_started",
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
      };

      offers.set(id, record);
      return record;
    }

    export function findOffer(id) {
      return offers.get(id);
    }

    export function findOfferByBatchId(batchId) {
      return [...offers.values()].find((offer) => offer.docgenBatchId === batchId);
    }

    export function findOfferByGeneratedFileName(fileName) {
      return [...offers.values()].find((record) => {
        const expectedName = `${record.offer.employee.name} - Offer Letter`;
        return fileName === expectedName || fileName === `${expectedName}.pdf`;
      });
    }

    export function listOffers() {
      return [...offers.values()];
    }

    export function updateOffer(id, changes) {
      const record = findOffer(id);
      if (!record) return null;

      const next = {
        ...record,
        ...changes,
        updatedAt: new Date().toISOString(),
      };
      offers.set(id, next);
      return next;
    }
    ```

    Create `box-client.js` and add a function that creates a Box client authenticated with Client Credentials Grant:

    ```javascript theme={null}
    import { BoxClient, BoxCcgAuth, CcgConfig } from "box-node-sdk";

    export function createBoxClient(config) {
      const ccgConfig = new CcgConfig({
        clientId: config.boxClientId,
        clientSecret: config.boxClientSecret,
        enterpriseId: config.boxEnterpriseId,
      });

      return new BoxClient({
        auth: new BoxCcgAuth({ config: ccgConfig }),
      });
    }
    ```

    <Note>
      The app calls Box APIs with the permissions of the service account.
    </Note>
  </Step>

  <Step title="Validate offer data">
    Create `offer-letter-data.js` with functions that validate incoming offer payloads before you call Doc Gen. The `buildOfferLetterData` function is a pass-through hook you can extend to map or transform fields before Doc Gen merges them into the template.

    ```javascript theme={null}
    export function buildOfferLetterData(offer) {
      return offer;
    }

    export function validateOffer(offer) {
      const required = [
        "id",
        "country",
        "contractDate",
        "deliveryTerms",
        "companyName",
        "baseSalary",
        "salaryDetails",
        "salaryModel",
        "employee.address",
        "employee.dob",
        "employee.email",
        "employee.name",
        "company.address",
        "company.designatedSigner",
        "company.name",
        "company.designation",
        "company.department",
        "position",
        "department",
        "startDate",
      ];

      const missing = required.filter((field) => !readPath(offer, field));
      if (missing.length > 0) {
        throw new Error(`Missing offer fields: ${missing.join(", ")}`);
      }

      if (!Array.isArray(offer.salaryDetails) || offer.salaryDetails.length === 0) {
        throw new Error("salaryDetails must be a non-empty array.");
      }

      if (!offer.employee.email.includes("@")) {
        throw new Error("employee.email must be a valid email address.");
      }
    }

    function readPath(value, path) {
      return path.split(".").reduce((current, key) => current?.[key], value);
    }
    ```
  </Step>

  <Step title="Generate offer letters with Box Doc Gen">
    Create `box-docgen.js` with functions that start document generation and parse webhook payloads:

    ```javascript theme={null}
    import { buildOfferLetterData } from "./offer-letter-data.js";

    export async function generateOfferLetter(client, config, offer) {
      return client.docgen.createDocgenBatchV2025R0({
        file: {
          id: config.docgenTemplateFileId,
          type: "file",
        },
        inputSource: "api",
        destinationFolder: {
          id: config.docgenDestinationFolderId,
          type: "folder",
        },
        outputType: "pdf",
        documentGenerationData: [
          {
            generatedFileName: `${offer.employee.name} - Offer Letter`,
            userInput: buildOfferLetterData(offer),
          },
        ],
      });
    }

    export function readDocgenWebhookInfo(event) {
      const info = [event.additional_info, event.additionalInfo].flat()[0] || {};
      const source = event.source || {};

      return {
        batchId: info.batch_id || info.batchId,
        generatedFileId: info.generated_file_id || info.generatedFileId || source.id,
        generatedFileName: source.name,
      };
    }
    ```

    See <Link href="/guides/docgen/generate-document">generate documents</Link> for additional API options.
  </Step>

  <Step title="Send offer letters for signature with Box Sign">
    Create `box-sign.js` with functions that collaborate the HR approver on the generated file and create a Box Sign request. In this example, the HR team member acts as an approver and reviews the documents, so they can double-check the offer details. Once this is approved in Box, the candidate receives the offer letter in their mailbox, with a custom email message valid for 14 days:

    ```javascript theme={null}
    function isAlreadyCollaboratedError(error) {
      return error.responseInfo?.statusCode === 409;
    }

    async function collaborateApproverOnFile(client, fileId, approverEmail) {
      try {
        return await client.userCollaborations.createCollaboration(
          {
            item: {
              id: fileId,
              type: "file",
            },
            accessibleBy: {
              type: "user",
              login: approverEmail,
            },
            role: "viewer",
            isAccessOnly: true,
          },
          {
            queryParams: {
              notify: false,
            },
          },
        );
      } catch (error) {
        if (isAlreadyCollaboratedError(error)) return null;
        throw error;
      }
    }

    export async function sendOfferLetterForSignature(client, config, offerRecord) {
      const signers = [];

      if (config.hrApproverEmail) {
        await collaborateApproverOnFile(
          client,
          offerRecord.generatedFileId,
          config.hrApproverEmail,
        );

        signers.push({
          email: config.hrApproverEmail,
          role: "approver",
          order: 1,
        });
      }

      signers.push({
        email: offerRecord.offer.employee.email,
        role: "signer",
        order: config.hrApproverEmail ? 2 : 1,
      });

      return client.signRequests.createSignRequest({
        sourceFiles: [
          {
            id: offerRecord.generatedFileId,
            type: "file",
          },
        ],
        parentFolder: {
          id: config.signParentFolderId,
          type: "folder",
        },
        signers,
        name: `${offerRecord.offer.employee.name} - Offer Letter`,
        emailSubject: `Offer letter for ${offerRecord.offer.position}`,
        emailMessage: "Please review and sign your offer letter.",
        areRemindersEnabled: true,
        daysValid: 14,
        externalId: offerRecord.id,
      });
    }

    export async function getSignRequest(client, signRequestId) {
      return client.signRequests.getSignRequestById(signRequestId);
    }
    ```

    Box Sign also supports phone verification, password protection, and other advanced security options. See <Link href="/guides/box-sign/create-sign-request">create Box Sign request</Link> for the full parameter list.
  </Step>

  <Step title="Build the Express server">
    Create `server.js` to orchestrate the workflow. The server loads the Box configuration from environment variables, and creates a Box SDK client. It then exposes the REST endpoints:

    ```javascript theme={null}
    import "dotenv/config";
    import express from "express";
    import { createBoxClient } from "./box-client.js";
    import { generateOfferLetter, readDocgenWebhookInfo } from "./box-docgen.js";
    import { getSignRequest, sendOfferLetterForSignature } from "./box-sign.js";
    import { readConfig } from "./config.js";
    import { validateOffer } from "./offer-letter-data.js";
    import {
      createOfferRecord,
      findOffer,
      findOfferByBatchId,
      findOfferByGeneratedFileName,
      listOffers,
      updateOffer,
    } from "./store.js";

    const config = readConfig();
    const client = createBoxClient(config);
    const app = express();

    app.use(express.json());
    // Define a function to require a shared secret for the /offer-letters endpoint.
    // This is a simple way to protect the endpoint from unauthorized access.
    // In production, use a more secure authentication method.
    function requireSharedSecret(request, response, next) {
      if (!config.sharedSecret) return next();
      if (request.headers["x-shared-secret"] === config.sharedSecret) return next();
      return response.status(401).json({ error: "Invalid shared secret." });
    }
    // The server.js file includes the following routes.
    app.get("/", (_request, response) => {
      response.json({
        name: "Box Offer Letter Demo",
        routes: [
          "POST /offer-letters",
          "GET /offer-letters",
          "POST /box/webhooks",
          "POST /offer-letters/:id/send-for-signature",
          "GET /offer-letters/:id/sign-request",
        ],
      });
    });
    // POST /offer-letters accepts offer data, validates it, calls Box Doc Gen to generate
    // the offer letter PDF, and stores an in-memory record with the Doc Gen batch ID.
    app.post("/offer-letters", requireSharedSecret, async (request, response, next) => {
      try {
        const offer = request.body.offer || request.body;
        validateOffer(offer);

        const batch = await generateOfferLetter(client, config, offer);
        const record = createOfferRecord(offer, batch);

        response.status(202).json({
          offerId: record.id,
          docgenBatchId: record.docgenBatchId,
          status: record.status,
        });
      } catch (error) {
        next(error);
      }
    });
    // GET /offer-letters lists all in-memory offer records and their statuses.
    app.get("/offer-letters", (_request, response) => {
      response.json({ entries: listOffers() });
    });
    // POST /box/webhooks handles the Doc Gen completion webhook. It reads the batch ID,
    // generated file ID, and generated file name from the webhook payload, and updates
    // the in-memory offer record with the generated file ID and status.
    async function handleDocgenWebhook(request, response, next) {
      try {
        const { batchId, generatedFileId, generatedFileName } = readDocgenWebhookInfo(
          request.body,
        );

        if (!generatedFileId) {
          return response
            .status(202)
            .json({ handled: false, reason: "No generated file ID found." });
        }

        const record = batchId
          ? findOfferByBatchId(batchId)
          : findOfferByGeneratedFileName(generatedFileName);

        if (!record) {
          return response
            .status(202)
            .json({ handled: false, reason: "Unknown generated offer letter." });
        }

        const updated = updateOffer(record.id, {
          generatedFileId,
          status: "ready_for_signature",
        });

        return response.json({ handled: true, offer: updated });
      } catch (error) {
        return next(error);
      }
    }

    app.post("/box/webhooks", handleDocgenWebhook);
    // POST /offer-letters/:id/send-for-signature creates a Box Sign request for the offer
    // letter. It first checks whether the offer letter PDF is ready, and then calls the
    // sendOfferLetterForSignature function to create the Box Sign request.
    app.post("/offer-letters/:id/send-for-signature", requireSharedSecret, async (request, response, next) => {
      try {
        const record = findOffer(request.params.id);
        if (!record) return response.status(404).json({ error: "Offer not found." });
        if (!record.generatedFileId) {
          return response.status(409).json({
            error: "Offer letter PDF is not ready yet. Wait for the Doc Gen webhook.",
          });
        }

        const signRequest = await sendOfferLetterForSignature(client, config, record);
        const updated = updateOffer(record.id, {
          signRequestId: signRequest.id,
          status: "signature_sent",
        });

        return response.status(201).json({
          offer: updated,
          signRequest: {
            id: signRequest.id,
            status: signRequest.status,
            prepareUrl: signRequest.prepareUrl,
          },
        });
      } catch (error) {
        return next(error);
      }
    });
    // GET /offer-letters/:id/sign-request returns the latest Box Sign status for an offer.
    app.get("/offer-letters/:id/sign-request", async (request, response, next) => {
      try {
        const record = findOffer(request.params.id);
        if (!record) return response.status(404).json({ error: "Offer not found." });
        if (!record.signRequestId) {
          return response
            .status(409)
            .json({ error: "No Box Sign request for this offer yet." });
        }

        const signRequest = await getSignRequest(client, record.signRequestId);

        return response.json({
          id: signRequest.id,
          status: signRequest.status,
          signers: signRequest.signers,
          signFiles: signRequest.signFiles,
        });
      } catch (error) {
        return next(error);
      }
    });
    // Finally, start the app.
    app.use((error, _request, response, _next) => {
      response.status(error.statusCode || 500).json({
        error: error.message,
      });
    });

    app.listen(config.port, () => {
      console.log(`Box Offer Letter Demo running at http://localhost:${config.port}`);
      if (config.publicBaseUrl) {
        console.log(`Webhook URL: ${config.publicBaseUrl}/box/webhooks`);
      }
    });
    ```

    <Note>
      Protect key routes with the shared secret in production, and verify webhook signatures before you process Doc Gen events. The in-memory `store.js` module is for demos only — replace it with a database for production before you deploy.
    </Note>

    At this point, your project directory should contain the following files:

    ```
    offer-letter-workflow/
    ├── .env
    ├── box-client.js
    ├── box-docgen.js
    ├── box-sign.js
    ├── config.js
    ├── offer-letter-data.js
    ├── package.json
    ├── server.js
    └── store.js
    ```
  </Step>

  <Step title="Configure the Doc Gen webhook">
    Register the webhook on the **template file**, not the destination folder. The `DOCGEN_DOCUMENT_GENERATION_SUCCEEDED` trigger is file-only; registering it on a folder returns a `400 invalid_parameter` error. For more options, see <Link href="/guides/docgen/mark-template">mark file as Box Doc Gen template</Link>.

    Configure a V2 Box webhook for your app:

    1. Define the URL where webhook payloads are sent.
    2. Select the Box Doc Gen template document as the trigger.
    3. Enable the **Document Generation Succeeded** trigger (`DOCGEN_DOCUMENT_GENERATION_SUCCEEDED`).

    See <Link href="/guides/webhooks/v2/create-v2">add webhooks</Link> for the full walkthrough.

    Or register the webhook with the Box CLI. Replace `$BOX_ACCESS_TOKEN` with a valid access token from your CCG-authenticated client:

    ```bash theme={null}
    box request /webhooks \
      -X POST \
      --token "$BOX_ACCESS_TOKEN" \
      --body '{
        "target": {
          "type": "file",
          "id": "BOX_DOCGEN_TEMPLATE_FILE_ID"
        },
        "address": "https://APP_URL/box/webhooks",
        "triggers": ["DOCGEN_DOCUMENT_GENERATION_SUCCEEDED"]
      }'
    ```
  </Step>

  <Step title="Test the application">
    Start the server:

    ```bash theme={null}
    node server.js
    ```

    Confirm the server is running:

    ```bash theme={null}
    curl http://localhost:8000
    ```

    Send a test offer payload. Update the shared secret and port to match your `.env` file, then run:

    ```bash theme={null}
    curl -X POST http://localhost:8000/offer-letters \
      -H "content-type: application/json" \
      -H "x-shared-secret: replace-me" \
      -d '{
        "country": "US",
        "contractDate": "18-08-2025",
        "deliveryTerms": "30 days",
        "companyName": "Xyz Inc",
        "baseSalary": 280000,
        "employee": {
          "address": "Sample Street, Sample City, SA-456",
          "dob": "12-12-1993",
          "email": "max.exampleman@example.com",
          "name": "Max Exampleman"
        },
        "salaryDetails": [
          {
            "component": "Base Salary",
            "value": 280000
          },
          {
            "component": "Payment terms",
            "value": "monthly"
          },
          {
            "component": "Stock options",
            "value": "1300 options (vesting over 4 years)"
          }
        ],
        "salaryModel": "per year",
        "company": {
          "address": "Example Street, Example City, EX-456",
          "designatedSigner": "John Doe",
          "name": "Acme Inc",
          "designation": "VP",
          "department": "Procurement"
        },
        "id": "12305",
        "position": "Manager",
        "department": "Procurement",
        "startDate": "18-08-2025"
      }'
    ```

    Example response:

    ```json theme={null}
    {
      "offerId": "12305",
      "docgenBatchId": "123456",
      "status": "docgen_started"
    }
    ```

    Open the **Generated Offer Letters** folder in Box. After Doc Gen finishes, the PDF appears there and Box sends the webhook to your app.

    **Simulate the webhook locally** if you do not have a public URL:

    ```bash theme={null}
    curl -X POST http://localhost:8000/box/webhooks \
      -H "content-type: application/json" \
      -d '{
        "trigger": "DOCGEN_DOCUMENT_GENERATION_SUCCEEDED",
        "additional_info": {
          "batch_id": "DOCGEN_BATCH_ID_FROM_PREVIOUS_STEP",
          "generated_file_id": "GENERATED_PDF_FILE_ID"
        }
      }'
    ```

    List in-memory offers:

    ```bash theme={null}
    curl http://localhost:8000/offer-letters
    ```

    Send the offer for signature:

    ```bash theme={null}
    curl -X POST http://localhost:8000/offer-letters/12305/send-for-signature \
      -H "x-shared-secret: replace-me"
    ```

    Check Box Sign status:

    ```bash theme={null}
    curl http://localhost:8000/offer-letters/12305/sign-request
    ```

    Common Box Sign statuses include `created`, `sent`, `viewed`, `signed`, `declined`, and `expired`.

    **Check the result:**

    * `GET /offer-letters` lists all in-memory offer records and their statuses.
    * `GET /offer-letters/:id/sign-request` returns the latest Box Sign status for an offer.
    * The HR approver receives the document first. After approval, the candidate receives the offer letter by email.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized or invalid access token">
    Confirm `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET`, and `BOX_ENTERPRISE_ID` are correct in your `.env` file. Verify the app uses Client Credentials Grant and is authorized in the Admin Console. See <Link href="/guides/authentication/client-credentials">Client Credentials Grant</Link>.
  </Accordion>

  <Accordion title="404 Not Found when generating documents">
    The service account does not have access to the template file or destination folder. Confirm the service account is collaborated into the template and folders with Editor access, and that the template file ID and folder IDs are correct.
  </Accordion>

  <Accordion title="Offer letter PDF is not ready yet (409)">
    The Doc Gen webhook has not arrived yet. Confirm your webhook is registered on the template file with the `DOCGEN_DOCUMENT_GENERATION_SUCCEEDED` trigger, and that your server is reachable at the configured URL.
  </Accordion>

  <Accordion title="Missing offer fields validation error">
    The offer payload is missing required fields for the Doc Gen template. Compare your payload against the `required` array in `validateOffer` and make sure nested fields such as `employee.email` are present.
  </Accordion>

  <Accordion title="Doc Gen or Box Sign authorization errors">
    Confirm the app uses Client Credentials Grant, the app has read/write, Doc Gen, and Sign scopes, and the service account can access the template file, write to the generated-offers folder, and write to the signed-offers folder. Confirm Doc Gen and Box Sign are enabled for the account in the Admin Console.
  </Accordion>

  <Accordion title="The candidate does not receive a signing email">
    Check `employee.email` in the offer payload. This value is used as the Box Sign recipient.
  </Accordion>

  <Accordion title="Missing required environment variables">
    Confirm `.env` includes `BOX_CLIENT_ID`, `BOX_CLIENT_SECRET`, `BOX_ENTERPRISE_ID`, `BOX_DOCGEN_TEMPLATE_FILE_ID`, `BOX_DOCGEN_DESTINATION_FOLDER_ID`, and `BOX_SIGN_PARENT_FOLDER_ID`.
  </Accordion>
</AccordionGroup>

## Other use cases

The same Box Doc Gen and Box Sign pattern applies to other workflows that need both document generation and approval or signature:

| Team | Example workflow |
| - | - |
| **Sales** | Generate quotes, order forms, or sales contracts, then route them for customer signature |
| **Legal** | Create NDAs, MSAs, or engagement letters, then send them through legal approval and counterparty signature |
| **HR** | Prepare promotion letters, stock agreements, or employee contracts, then collect internal approval and employee signature |
| **Procurement** | Generate vendor agreements, RFP responses, or work orders, then route them for supplier signature |
| **Finance** | Generate investor reports, QBR packets, or tax documents, then route them for review and secure distribution |

## Scaling to production

<AccordionGroup>
  <Accordion title="Replace in-memory storage">
    The demo `store.js` module loses data on restart. Persist offer records in a database so you can correlate Doc Gen batch IDs, generated file IDs, and Box Sign request IDs across restarts and retries.
  </Accordion>

  <Accordion title="Verify webhook signatures">
    In production, validate that Doc Gen webhook payloads originate from Box before you update offer records. See <Link href="/guides/webhooks/v2/signatures-v2">verify webhook signatures</Link>.
  </Accordion>

  <Accordion title="Reauthorize after configuration changes">
    If you change scopes or the access level on the CCG app, an administrator must reauthorize the app in the Admin Console under **Integrations > Platform Apps** before API calls succeed again.
  </Accordion>

  <Accordion title="Customize Box Sign workflow">
    Add multiple approvers, in-person signing, password protection, or phone verification by extending the `signers` array and other Box Sign request parameters. See <Link href="/guides/box-sign/create-sign-request">create Box Sign request</Link>.
  </Accordion>

  <Accordion title="Harden webhook and API handling">
    Make webhook handling idempotent because delivery can produce duplicates. Add retries for Box API calls, protect routes with stronger auth than a shared secret, and avoid logging access tokens, employee personal data, compensation details, or signed-document links.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Generate documents with Box Doc Gen" href={localizeLink("/guides/docgen/generate-document")} icon="file-lines">
    Learn how to generate documents with Box Doc Gen.
  </Card>

  <Card title="Create Box Sign request" href={localizeLink("/guides/box-sign/create-sign-request")} icon="signature">
    Explore advanced Sign request options, including multi-signer flows and security settings.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Automate new hire onboarding with Box APIs
Source: https://developer.box.com/tutorials/onboarding-workspaces

Build a middleware service that listens for HR hiring events and provisions a standardized, governed Box workspace for every new hire using the Users, Groups, Folders, and Collaboration APIs.

When a new employee joins, someone usually has to click through the Box web app to create their folders, share the right resources, and add them to the correct teams. That manual work is slow, inconsistent, and easy to get wrong. Two hires in the same role can end up with different folder structures and different access - a governance and audit problem waiting to happen.

This tutorial builds a middleware service that removes that manual work. When your HR system fires a `hired` event, the service authenticates to Box, provisions a standardized personal folder tree for the new hire, grants the right groups access at the right levels, and optionally invites the new hire to their workspace. Every new hire automatically gets an identical, governed structure.

<Card title="Clone the working sample" href="https://github.com/box-community/automate-new-hire-onboarding" icon="github">
  Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
</Card>

## What you are building

By the end of this tutorial, you have a working Python service that:

* Receives an HR `hired` event through a webhook endpoint.
* Resolves (or creates) the governance groups that control access, such as IT and HR.
* Builds a standardized personal folder tree for the new hire using the Folders API.
* Grants each governance group access at the correct folder level using the Collaboration API.
* Optionally invites the new hire to their workspace so they have access on day one.
* Runs idempotently, so replaying the same event never creates duplicate folders or collaborations.

## Prerequisites

Before you start, make sure you have the following:

* A free <Link href="https://account.box.com/signup/n/developer">Box developer account</Link>, or a Box account with administrator access.
* A Box application configured with **Client Credentials Grant** authentication. Free developer accounts authorize Platform Apps automatically; on managed accounts, an administrator must authorize the app in the Admin Console.
* Python 3.11 or higher.
* The following scopes enabled on your app:
  * Read and write all files and folders stored in Box
  * Manage groups
  * Manage users
* The app's **App Access Level** set to **App + Enterprise Access** (on the **Configuration** tab). The default **App Access Only** limits the service account to its own content and cannot create or manage enterprise users and groups.
* Your Box enterprise ID (found in the [Developer Console](https://app.box.com/developers/console) by clicking your profile icon, or in the Admin Console under **Account & Billing**).

<Note>
  Creating and managing groups and users requires admin privileges. When you use Client Credentials Grant with an `enterprise_id`, the app acts as the enterprise service account. This service account can only manage enterprise users and groups when the app's **App Access Level** is set to **App + Enterprise Access**. After you enable the **Manage groups** and **Manage users** scopes and change the access level, an administrator must reauthorize the app in the Admin Console under **Integrations > Platform Apps** for those changes to take effect.
</Note>

## Step-by-step process

This solution combines four Box capabilities:

| Component | Purpose | API |
| - | - | - |
| **Groups** | Resolve or create the governance groups that control access | `POST /2.0/groups`, `GET /2.0/groups` |
| **Folders** | Build the standardized personal folder tree | `POST /2.0/folders` |
| **Collaborations** | Grant groups and the new hire access at the right levels | `POST /2.0/collaborations` |
| **Users** | Optionally add the new hire to enterprise groups (see [Scaling to production](#scaling-to-production)) | `POST /2.0/group_memberships` |

<Info>
  Box collaborations cascade. A collaboration added to a parent folder automatically grants the same access to everything inside it. This tutorial uses that behavior deliberately: broad access is granted high in the tree, and narrower access is granted only on the specific subfolders that need it.
</Info>

<Steps>
  <Step title="Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir onboarding-workspace && cd onboarding-workspace
    ```

    2. Create and activate a Python virtual environment:

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    After activation, your terminal prompt shows `(.venv)` at the beginning. This confirms you are working inside the virtual environment.

    <Note>
      Every time you open a new terminal window or tab, you must re-activate the virtual environment by running `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError` when running commands, it usually means the venv is not activated.
    </Note>

    3. Install the required packages:

    ```bash theme={null}
    pip install boxsdk flask python-dotenv
    ```

    4. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your actual credentials from the Box Developer Console:

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    ONBOARDING_ROOT_FOLDER_ID=0
    ```

    `ONBOARDING_ROOT_FOLDER_ID` is the folder where each new hire's workspace is created. Leave it as `0` to create workspaces in the service account's root, or set it to the ID of a dedicated `New Hires` folder.

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>

    <Note>
      **Understanding environment variables:** The `.env` file stores sensitive values (your actual credentials). Your Python code reads these values by referencing their **names** using `os.getenv("VARIABLE_NAME")`. For example, `os.getenv("BOX_CLIENT_ID")` looks up the value stored next to `BOX_CLIENT_ID=` in your `.env` file. When you copy the code in the following steps, keep the quoted variable names exactly as shown. Do not replace them with your actual credentials.
    </Note>
  </Step>

  <Step title="Authenticate the Box client">
    Create a file called `box_client.py` in your project directory and paste the following code:

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        BoxCCGAuth,
        CCGConfig,
    )

    load_dotenv()

    def get_box_client() -> BoxClient:
        config = CCGConfig(
            client_id=os.getenv("BOX_CLIENT_ID"),
            client_secret=os.getenv("BOX_CLIENT_SECRET"),
            enterprise_id=os.getenv("BOX_ENTERPRISE_ID"),
        )
        auth = BoxCCGAuth(config=config)
        return BoxClient(auth=auth)
    ```

    <Tip>
      Client Credentials Grant is recommended for server-to-server automations where no end user is present. If your organization requires JWT, swap `CCGConfig`/`BoxCCGAuth` for `JWTConfig`/`BoxJWTAuth`; the rest of the code in this tutorial is unchanged. For a comparison of both, see the <Link href="/guides/authentication">authentication overview</Link>.
    </Tip>
  </Step>

  <Step title="Define the workspace template">
    The heart of a governed onboarding process is a single, declarative definition of what every new hire's workspace looks like and who can access each part of it. Create a file called `config.py` and paste the following code:

    ```python theme={null}
    # Maps a logical role key to the actual Box group name.
    # Edit the names to match the groups in your enterprise.
    GOVERNANCE_GROUPS = {
        "IT": "IT Onboarding",
        "HR": "HR Onboarding",
        "All Employees": "All Employees",
    }

    # The standardized folder tree created for every new hire.
    # `collaborators` grants a governance group access at that exact level.
    # Because collaborations cascade, access granted on a folder also
    # applies to everything nested inside it.
    WORKSPACE_TEMPLATE = {
        "name": "Onboarding",
        "collaborators": [],
        "children": [
            {"name": "Personal", "collaborators": [], "children": []},
            {
                "name": "IT Setup",
                "collaborators": [{"group": "IT", "role": "editor"}],
                "children": [],
            },
            {
                "name": "HR Documents",
                "collaborators": [{"group": "HR", "role": "editor"}],
                "children": [],
            },
            {
                "name": "Policies & Templates",
                "collaborators": [{"group": "All Employees", "role": "viewer"}],
                "children": [],
            },
            {"name": "Team Resources", "collaborators": [], "children": []},
        ],
    }
    ```

    <Tip>
      Keeping the structure and access rules in one template is what makes onboarding *consistent* and *governed*. To change how every future hire is set up, you edit this file - not your provisioning logic.
    </Tip>
  </Step>

  <Step title="Resolve the governance groups">
    Before you can share folders with a group, you need its group ID. Create a file called `groups.py` and paste the following code. It creates each governance group if it does not exist, and looks up the existing group if it does:

    ```python theme={null}
    from box_sdk_gen import BoxClient, BoxAPIError

    from config import GOVERNANCE_GROUPS

    def get_or_create_group(client: BoxClient, name: str) -> str:
        try:
            group = client.groups.create_group(
                name,
                description="Governance group managed by onboarding automation.",
            )
            print(f"Created group '{group.name}' ({group.id})")
            return group.id
        except BoxAPIError as error:
            if error.response_info.status_code != 409:
                raise
            for group in client.groups.get_groups(filter_term=name).entries:
                if group.name == name:
                    print(f"Using existing group '{group.name}' ({group.id})")
                    return group.id
            raise

    def resolve_governance_groups(client: BoxClient) -> dict:
        """Return a map of logical group key -> Box group ID."""
        return {
            key: get_or_create_group(client, name)
            for key, name in GOVERNANCE_GROUPS.items()
        }
    ```

    A group name must be unique in the enterprise, so Box returns `409 Conflict` if the group already exists. Catching that status and falling back to a lookup makes the function safe to run repeatedly.
  </Step>

  <Step title="Build the workspace and apply collaborations">
    Create a file called `workspace.py` and paste the following code. It recursively creates each folder in the template and, at every level, shares the folder with the groups defined for that node:

    ```python theme={null}
    from box_sdk_gen import (
        BoxClient,
        BoxAPIError,
        CreateFolderParent,
        CreateCollaborationItem,
        CreateCollaborationItemTypeField,
        CreateCollaborationAccessibleBy,
        CreateCollaborationAccessibleByTypeField,
        CreateCollaborationRole,
    )

    ROLE_MAP = {
        "editor": CreateCollaborationRole.EDITOR,
        "viewer": CreateCollaborationRole.VIEWER,
        "uploader": CreateCollaborationRole.UPLOADER,
        "co-owner": CreateCollaborationRole.CO_OWNER,
    }

    def is_already_collaborator(error: BoxAPIError) -> bool:
        # Box reports an existing collaborator differently for groups and users:
        # a group returns 409 with code "conflict", while a user can return
        # "user_already_collaborator". Match on both so re-runs are safe.
        body = error.response_info.body
        message = body.get("message", "").lower()
        return (
            body.get("code") == "user_already_collaborator"
            or "already a collaborator" in message
        )

    def create_folder(client: BoxClient, name: str, parent_id: str) -> str:
        try:
            folder = client.folders.create_folder(
                name, CreateFolderParent(id=parent_id)
            )
            return folder.id
        except BoxAPIError as error:
            # 409 means a folder with this name already exists under the parent.
            # Reuse it so re-running the service never creates duplicates.
            if error.response_info.status_code != 409:
                raise
            conflicts = error.response_info.body.get("context_info", {}).get(
                "conflicts", []
            )
            return conflicts[0]["id"]

    def add_group_collaboration(
        client: BoxClient, folder_id: str, group_id: str, role: str
    ):
        try:
            client.user_collaborations.create_collaboration(
                item=CreateCollaborationItem(
                    type=CreateCollaborationItemTypeField.FOLDER, id=folder_id
                ),
                accessible_by=CreateCollaborationAccessibleBy(
                    type=CreateCollaborationAccessibleByTypeField.GROUP, id=group_id
                ),
                role=ROLE_MAP[role],
            )
        except BoxAPIError as error:
            # Ignore if the group is already a collaborator on this folder.
            if not is_already_collaborator(error):
                raise

    def build_workspace(
        client: BoxClient, node: dict, parent_id: str, group_ids: dict
    ) -> str:
        folder_id = create_folder(client, node["name"], parent_id)

        for collaborator in node.get("collaborators", []):
            group_id = group_ids[collaborator["group"]]
            add_group_collaboration(
                client, folder_id, group_id, collaborator["role"]
            )
            print(
                f"  Shared '{node['name']}' with "
                f"{collaborator['group']} ({collaborator['role']})"
            )

        for child in node.get("children", []):
            build_workspace(client, child, folder_id, group_ids)

        return folder_id
    ```

    Because `build_workspace` walks the template recursively, the same code handles a flat structure or a deeply nested one. To change the tree, you only edit the template in `config.py`.
  </Step>

  <Step title="Orchestrate onboarding">
    Create a file called `onboarding.py` and paste the following code. This ties the pieces together: it resolves the groups, builds the workspace for a specific hire, and optionally invites the new hire to their workspace root:

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        BoxAPIError,
        CreateCollaborationItem,
        CreateCollaborationItemTypeField,
        CreateCollaborationAccessibleBy,
        CreateCollaborationAccessibleByTypeField,
        CreateCollaborationRole,
    )

    from box_client import get_box_client
    from config import WORKSPACE_TEMPLATE
    from groups import resolve_governance_groups
    from workspace import build_workspace, is_already_collaborator

    load_dotenv()

    def invite_new_hire(client: BoxClient, folder_id: str, login: str):
        """Give the new hire access to their workspace root.

        Co-owner is used when the service account owns the folder. Otherwise we
        fall back to editor, because only owners and co-owners can grant co-owner.
        """
        me = client.users.get_user_me()
        folder = client.folders.get_folder_by_id(folder_id, fields=["owned_by"])
        if folder.owned_by and folder.owned_by.id == me.id:
            role = CreateCollaborationRole.CO_OWNER
        else:
            role = CreateCollaborationRole.EDITOR

        try:
            client.user_collaborations.create_collaboration(
                item=CreateCollaborationItem(
                    type=CreateCollaborationItemTypeField.FOLDER, id=folder_id
                ),
                accessible_by=CreateCollaborationAccessibleBy(
                    type=CreateCollaborationAccessibleByTypeField.USER, login=login
                ),
                role=role,
            )
            print(f"Invited {login} to workspace {folder_id} as {role.value}")
        except BoxAPIError as error:
            if not is_already_collaborator(error):
                raise

    def onboard_new_hire(hire: dict) -> str:
        client = get_box_client()

        group_ids = resolve_governance_groups(client)

        template = dict(WORKSPACE_TEMPLATE)
        template["name"] = f"{hire['name']} - Onboarding"

        parent_id = os.getenv("ONBOARDING_ROOT_FOLDER_ID", "0")
        workspace_id = build_workspace(client, template, parent_id, group_ids)

        if hire.get("email"):
            invite_new_hire(client, workspace_id, hire["email"])

        print(f"Workspace ready for {hire['name']} (ID: {workspace_id})")
        return workspace_id

    if __name__ == "__main__":
        # Simulate a hire event for a quick local test.
        onboard_new_hire({"name": "Jordan Rivera", "email": None})
    ```

    Inviting the new hire at the workspace root means they can see every folder inside it, while the group collaborations on subfolders continue to govern who else has access. `invite_new_hire` grants **co-owner** when the service account owns the workspace folder, and falls back to **editor** otherwise - because only an owner or co-owner can grant the co-owner role. If you point `ONBOARDING_ROOT_FOLDER_ID` at a folder owned by another user, the workspace folders are owned by that user, so the fallback prevents a `403`. Leave `email` as `None` to provision the structure without inviting anyone yet - useful when the hire's Box account does not exist on their start date.
  </Step>

  <Step title="Create the hire event listener">
    Create a file called `app.py` and paste the following code. This Flask application receives `hired` events from your HR system and provisions a workspace for each one:

    ```python theme={null}
    from dotenv import load_dotenv
    from flask import Flask, request, jsonify

    from onboarding import onboard_new_hire

    load_dotenv()
    app = Flask(__name__)

    @app.route("/hire", methods=["POST"])
    def handle_hire_event():
        event = request.get_json()

        if event.get("event") != "employee.hired":
            return jsonify({"status": "ignored"}), 200

        employee = event["employee"]
        hire = {
            "name": employee["full_name"],
            "email": employee.get("work_email"),
        }

        workspace_id = onboard_new_hire(hire)

        return jsonify({"status": "provisioned", "workspace_id": workspace_id}), 200

    if __name__ == "__main__":
        app.run(port=5000)
    ```

    <Note>
      In production, you should verify that incoming requests genuinely originate from your HR system, typically by validating a signature or shared secret on each request. Never provision resources from an unauthenticated public endpoint.
    </Note>

    At this point, your project directory should contain the following files:

    ```
    onboarding-workspace/
    ├── .env
    ├── .venv/
    ├── app.py
    ├── box_client.py
    ├── config.py
    ├── groups.py
    ├── onboarding.py
    └── workspace.py
    ```
  </Step>

  <Step title="Test the integration">
    You can test the full provisioning flow locally without connecting a real HR system. This step simulates the event your HR system would send when a new hire is added.

    <Note>
      This step requires **two terminal windows** open at the same time. Terminal 1 runs the Flask server (which must stay running). Terminal 2 sends a test request to it.
    </Note>

    **Terminal 1 - start the server:**

    Make sure you are in the `onboarding-workspace` directory and the virtual environment is activated:

    ```bash theme={null}
    cd ~/onboarding-workspace
    source .venv/bin/activate
    python3 app.py
    ```

    You should see:

    ```
    * Running on http://127.0.0.1:5000
    ```

    Leave this terminal running.

    **Terminal 2 - send a test hire event:**

    Open a new terminal tab or window. Send a simulated HR event using curl. Replace the email with a valid address to test the invite, or remove `work_email` to skip it:

    ```bash theme={null}
    curl -X POST http://127.0.0.1:5000/hire \
      -H "Content-Type: application/json" \
      -d '{
        "event": "employee.hired",
        "employee": {
          "full_name": "Jordan Rivera",
          "work_email": "jordan.rivera@example.com"
        }
      }'
    ```

    **Check the result:**

    Switch back to Terminal 1. You should see output confirming the groups, folders, and collaborations were created:

    ```
    Created group 'IT Onboarding' (12345678)
    Created group 'HR Onboarding' (12345679)
    Created group 'All Employees' (12345680)
      Shared 'IT Setup' with IT (editor)
      Shared 'HR Documents' with HR (editor)
      Shared 'Policies & Templates' with All Employees (viewer)
    Invited jordan.rivera@example.com to workspace 98765432
    Workspace ready for Jordan Rivera (ID: 98765432)
    ```

    **Verify in Box:**

    The workspace is owned by the app's <Link href="/guides/getting-started/users#service-account">Service Account</Link>, not by your personal or admin login. The folder is created in the Service Account's own root so it does **not** appear in your **All Files** in the Box web app unless you were added as a collaborator. This is expected. Verify the result one of these ways:

    * **Query the API as the Service Account (recommended).** This uses the same identity that created the workspace. List the workspace's contents and confirm each subfolder and its collaborators:

    ```python theme={null}
    from box_client import get_box_client

    client = get_box_client()

    # Replace with the workspace_id returned by the service.
    workspace_id = "98765432"

    for folder in client.folders.get_folder_items(workspace_id).entries:
        print(folder.type, folder.id, folder.name)
        collaborations = client.list_collaborations.get_folder_collaborations(folder.id)
        for collaboration in collaborations.entries:
            print(f"  {collaboration.accessible_by.name} - {collaboration.role.value}")
    ```

    * **Open it in the Box web app.** You only see the folder here if you are a collaborator on it. If you passed your own email as the new hire, open the [Box web app](https://app.box.com), find `Jordan Rivera - Onboarding` (it appears as a shared folder), open a subfolder, click **Sharing**, and check the collaborator list. If no one was invited, the folder is visible only to the Service Account.

    * **Preview it in Content Manager.** Navigate to the **Admin Console** > **Content** > **Content Manager**, then select the relevant user. You are able to view the shared folder.

    <Tip>
      To make workspaces appear in a real, admin-visible location instead of the Service Account's root, create a dedicated **New Hires** folder owned by an admin, add the Service Account as a co-owner collaborator on it, and set `ONBOARDING_ROOT_FOLDER_ID` to that folder's ID. New workspaces are then owned by that admin and show up in their **All Files**.
    </Tip>

    **Run it again:**

    Send the same curl request a second time. The service completes without errors and without creating duplicate folders, groups, or collaborations. This idempotency is what makes it safe to retry failed or replayed events in production.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Configuration.
    * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID (found in Developer Console > General Settings, or Admin Console > Account & Billing).
    * Ensure your app is authorized in the Developer Console and uses Client Credentials Grant.
  </Accordion>

  <Accordion title="403 Forbidden or 'access_denied_insufficient_permissions'">
    The app is missing the scopes or access level required to manage groups, users, or content:

    * Set the **App Access Level** to **App + Enterprise Access** in Developer Console > Configuration. The default **App Access Only** cannot create or manage enterprise users and groups, which returns a `403`.
    * Enable **Read and write all files and folders**, **Manage groups**, and **Manage users** in Developer Console > Configuration > Application Scopes.
    * After changing the access level or scopes, an administrator must reauthorize the app in the Admin Console under **Integrations > Platform Apps**. These changes do not take effect until the app is reauthorized.
  </Accordion>

  <Accordion title="Users or groups are not created and creation returns 403">
    Creating enterprise users and groups requires administrative privileges *and* enterprise access. Confirm the app's **App Access Level** is set to **App + Enterprise Access** (the default **App Access Only** returns a `403` for these operations), that the **Manage groups** and **Manage users** scopes are enabled, and that an enterprise admin reauthorized the app after those changes.
  </Accordion>

  <Accordion title="A folder or collaboration already exists (409 Conflict)">
    This is expected on re-runs and is handled for you. `create_folder` reuses the existing folder returned in the conflict response, and `is_already_collaborator` detects an existing collaborator so the collaboration helpers skip it. Note that Box reports this differently for groups (`409` with code `conflict` and the message "Group is already a collaborator") and users (`user_already_collaborator`), which is why the helper checks both. If you see an unhandled 409, confirm you copied the `try`/`except` blocks and the `is_already_collaborator` helper exactly as shown.
  </Accordion>

  <Accordion title="The new hire invite fails or stays pending">
    If the email does not belong to an existing Box user, the collaboration is created in a `pending` state until they accept the invitation. To provision managed accounts for new hires as part of this flow, see <Link href="/guides/users/create-managed-user">Create a managed user</Link>.
  </Accordion>
</AccordionGroup>

## Scaling to production

<AccordionGroup>
  <Accordion title="Add the new hire to enterprise groups">
    Sharing folders with groups is only half of a governance model. You can also add the new hire *into* groups so they automatically inherit every collaboration those groups already hold across Box. Use the Memberships API:

    ```python theme={null}
    from box_sdk_gen import (
        BoxClient,
        CreateGroupMembershipUser,
        CreateGroupMembershipGroup,
    )

    def add_user_to_group(client: BoxClient, user_id: str, group_id: str):
        client.memberships.create_group_membership(
            CreateGroupMembershipUser(id=user_id),
            CreateGroupMembershipGroup(id=group_id),
        )
    ```

    A common pattern is to add every new hire to an `All Employees` group so org-wide shares reach them on day one. See <Link href="/guides/collaborations/groups">Sharing with groups</Link>.

    <Note>
      Adding a user who is already a member returns a `409` `BoxAPIError`. To keep this step safe to re-run like the rest of the service, wrap the call in the same `try`/`except` pattern used in `workspace.py` and ignore the conflict.
    </Note>
  </Accordion>

  <Accordion title="Give the new hire access to an onboarding Hub">
    Beyond folders, you can give each new hire access to a <Link href="/guides/hubs-api">Box Hub</Link> - a curated content portal for onboarding materials, policies, and FAQs that is integrated with Box AI, so the hire can ask natural-language questions across its content. A common pattern is to maintain one shared "New Hire" Hub and add each hire (or the `All Employees` group) as a collaborator during provisioning.

    Add the following helper to `workspace.py`. Unlike a folder, a hub returns a generic `409 Conflict` (not the `already a collaborator` body that `is_already_collaborator` matches) when the collaborator already exists, so the helper treats any `409` as an idempotent skip - keeping it safe to re-run:

    ```python theme={null}
    from box_sdk_gen import (
        CreateHubCollaborationV2025R0Hub,
        CreateHubCollaborationV2025R0AccessibleBy,
    )

    def add_hub_collaborator(
        client: BoxClient, hub_id: str, login: str, role: str = "viewer"
    ):
        try:
            client.hub_collaborations.create_hub_collaboration_v2025_r0(
                CreateHubCollaborationV2025R0Hub(id=hub_id),
                CreateHubCollaborationV2025R0AccessibleBy(type="user", login=login),
                role,
            )
        except BoxAPIError as error:
            # A hub returns a generic 409 "conflict" (not the folder-style
            # "already a collaborator" body) when the collaborator already
            # exists, so treat any 409 here as the idempotent skip case.
            if error.response_info.status_code != 409:
                raise
    ```

    Store the Hub's ID in your `.env` as `ONBOARDING_HUB_ID`, then call the helper from `onboard_new_hire` when the hire has an email:

    ```python theme={null}
    hub_id = os.getenv("ONBOARDING_HUB_ID")
    if hub_id and hire.get("email"):
        add_hub_collaborator(client, hub_id, hire["email"])
    ```

    To grant access at the group level instead, pass `CreateHubCollaborationV2025R0AccessibleBy(type="group", id=group_id)`. Valid roles are `viewer`, `editor`, and `co-owner`.

    <Note>
      Box Hubs must be <Link href="https://support.box.com/hc/en-us/articles/25822332454547-Configuring-Box-Hubs">enabled for your account</Link> before these calls succeed. The `*_v2025_r0` SDK methods target the `2025.0` API version, which the Hubs endpoints require.

      The identity running the service - the Service Account when you use Client Credentials Grant - must **own or co-own the Hub** to manage its collaborations. If it does not, Box returns `404 Not Found` with the message `Authorization Failed`, because it cannot see the Hub. The simplest approach is to have the Service Account create the Hub (via <Link href="/guides/hubs-api/hubs/create-hub">Create a hub</Link>) so it owns it, or add the Service Account as a co-owner of an existing Hub. To manage roles and removals, see <Link href="/guides/hubs-api/hubs-collaborations/hub-collaborations">Manage hub collaborations</Link>.
    </Note>
  </Accordion>

  <Accordion title="Apply governance policies to the workspace">
    Layer additional controls on the provisioned tree. Attach a <Link href="/guides/metadata/index">metadata</Link> instance to tag each workspace with the hire's department and start date, and apply <Link href="/guides/retention-policies">retention policies</Link> so onboarding documents are archived or deleted on a schedule. Metadata also makes workspaces searchable and reportable across the enterprise.
  </Accordion>

  <Accordion title="Secure the event endpoint">
    Treat the `/hire` endpoint as privileged. Require a shared secret or signature on every request from your HR system, restrict inbound traffic to known sources, and run the service behind HTTPS. Reject any request you cannot authenticate before it reaches your provisioning code.
  </Accordion>

  <Accordion title="Make provisioning resilient">
    HR integrations can deliver events more than once or out of order. The idempotent helpers in this tutorial already prevent duplicates, but for high volume you should also queue events, retry transient failures with backoff, and log each provisioning run so you have an audit trail of who was onboarded and when.
  </Accordion>

  <Accordion title="Pair onboarding with deprovisioning">
    A complete lifecycle needs an offboarding counterpart. When your HR system fires a termination event, transfer the departing employee's content and remove their access. See <Link href="/guides/users/deprovision/index">Deprovision users</Link> and <Link href="/guides/users/deprovision/transfer-folders">Transfer files and folders</Link>.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Provision users and content" href={localizeLink("/guides/users/provision/index")} icon="users">
    Explore Box's end-to-end patterns for provisioning users, groups, and shared folder structures.
  </Card>

  <Card title="Collaborations API reference" href={localizeLink("/reference/post-collaborations")} icon="code">
    See the full API specification for creating collaborations.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Build an answer bank with Box Hubs and AI
Source: https://developer.box.com/tutorials/sales-rfp-answer-bank

Build an AI-powered answer bank that indexes curated content in a Box Hub and answers questions with Box AI. This walkthrough uses a sales RFP library as the example.

This tutorial builds a self-service RFP answer bank: you index approved sales content in a Box Hub, embed the hub in your CRM, and let reps ask Box AI for answers grounded in that permission-controlled content.

The same hub-and-Ask pattern applies to any access-controlled knowledge base. See <Link href="/guides/hubs-api/access-controlled-knowledge-base">Turn an enterprise document repository into an access-controlled AI knowledge base</Link>.

<Card title="Clone the working sample" href="https://github.com/box-community/sales-rfp-answer-bank" icon="github">
  Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
</Card>

## What you are building

By the end of this tutorial, you have a working integration that:

* Provisions a Sales Hub programmatically using the Box Hubs API.
* Populates the hub with curated folders containing approved RFP content.
* Embeds the hub's AI chat interface in your CRM.
* Queries the hub using Box AI to answer sales questions grounded in approved content.

## Prerequisites

Before you start, make sure you have the following:

* A <Link href="https://account.box.com/signup/developer">free Box developer account</Link>, or a <Link href="https://www.box.com/pricing">Box Enterprise account</Link> with **Box AI** and **Box Hubs** enabled. See <Link href="https://support.box.com/hc/en-us/articles/25822332454547-Configuring-Box-Hubs">Configuring Box Hubs</Link>.
* A Box application configured with **Client Credentials Grant** authentication and **Generate User Access Tokens** enabled.
* Python 3.11 or higher.
* The following scopes enabled on your app:
  * Read and write all files and folders stored in Box
  * Manage AI
* Your Box user ID (found in the Admin Console under **Users**).

## Step-by-step process

This solution combines three Box capabilities:

| Component | Purpose | API |
| - | - | - |
| **Hubs** | Index curated content into a searchable, permission-inheriting portal | `POST /2.0/hubs` |
| **Hub items** | Add folders and files to the hub | `POST /2.0/hubs/:id/manage_items` |
| **Box AI** | Answer natural language questions grounded in hub content | `POST /2.0/ai/ask` |

<Info>
  Box Hubs inherit permissions from the underlying source files. Reps only see answers derived from content they already have access to in Box. No separate access control layer is required.
</Info>

<Steps>
  <Step title="Organize your RFP content in Box">
    Before building the integration, organize your approved sales content. A clean folder structure improves both Box AI answer quality and content governance.

    Create a folder structure in Box similar to the following, or [copy this shared folder](https://previewteam.app.box.com/s/qq7uws38kuo3fl81fzmjjbgrkemprqlk) to your Box account. It contains sample files for each subfolder listed below.

    ```
    Sales Content/
    ├── RFP Responses/
    │   ├── 2025-Q1-Acme-RFP-Response.pdf
    │   ├── 2024-Q4-Enterprise-Security-RFP.docx
    │   └── 2024-Q3-Healthcare-Compliance-RFP.pdf
    ├── Proposals/
    │   ├── Enterprise-Platform-Proposal-Template.docx
    │   └── Mid-Market-Proposal-Template.docx
    ├── Competitive Intelligence/
    │   ├── Competitor-Comparison-Matrix.xlsx
    │   └── Win-Loss-Analysis-Q1-2025.pdf
    └── Pricing/
        ├── Enterprise-Pricing-Guide.pdf
        └── Volume-Discount-Schedule.xlsx
    ```

    Note the folder IDs for the top-level `Sales Content` folder and each subfolder. You use these when adding items to the hub.

    <Warning>
      **Ensure the authenticated user has access to this content.** Since this tutorial uses CCG with a `user_id`, the client acts as that specific user. The user must have at least **Viewer** access to all folders you plan to add to the hub. If you are using a service account (`enterprise_id` instead of `user_id`), you must invite the service account email as a collaborator on the folders.

      To find your service account email: go to the [Developer Console](https://app.box.com/developers/console), open your app, and look under **App Details** for the **Service Account ID** (it looks like `AutomationUser_xxxxx_xxxxxx@boxdevedition.com`).
    </Warning>

    <Tip>
      Keep the content curated and current. The quality of Box AI answers depends directly on the quality of the source material. Remove outdated proposals and archive superseded pricing guides.
    </Tip>
  </Step>

  <Step title="Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir sales-rfp-hub && cd sales-rfp-hub
    ```

    2. Create and activate a Python virtual environment:

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    After activation, your terminal prompt shows `(.venv)` at the beginning. This confirms you are working inside the virtual environment.

    <Note>
      Every time you open a new terminal window or tab, you must re-activate the virtual environment by running `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError` when running commands, it usually means the venv is not activated.
    </Note>

    3. Install the required packages:

    ```bash theme={null}
    pip install boxsdk python-dotenv
    ```

    4. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your actual credentials from the Box Developer Console:

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_USER_ID=your_box_user_id
    SALES_CONTENT_FOLDER_ID=your_sales_content_folder_id
    ```

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>

    <Note>
      **Understanding environment variables:** The `.env` file stores sensitive values (your actual credentials). Your Python code reads these values by referencing their **names** using `os.getenv("VARIABLE_NAME")`. For example, `os.getenv("BOX_CLIENT_ID")` looks up the value stored next to `BOX_CLIENT_ID=` in your `.env` file. When you copy the code in the following steps, keep the quoted variable names exactly as shown. Do not replace them with your actual credentials.
    </Note>
  </Step>

  <Step title="Authenticate the Box client">
    Create a new file called `box_client.py` in your project directory. Open the file and paste the following code:

    ```python theme={null}
    import os
    from box_sdk_gen import (
        BoxClient,
        BoxCCGAuth,
        CCGConfig,
    )

    def get_box_client() -> BoxClient:
        config = CCGConfig(
            client_id=os.getenv("BOX_CLIENT_ID"),
            client_secret=os.getenv("BOX_CLIENT_SECRET"),
            user_id=os.getenv("BOX_USER_ID"),
        )
        auth = BoxCCGAuth(config=config)
        return BoxClient(auth=auth)
    ```

    <Note>
      This tutorial uses `user_id` (not `enterprise_id`) to authenticate as a specific Box user. This means the client acts with that user's permissions and can access content the user has been invited to. Find your user ID in the Admin Console under **Users**, or by clicking your avatar in the Box web app and checking the URL.
    </Note>

    <Tip>
      Client Credentials Grant is recommended for server-to-server automations where no end user is present. Make sure **Generate User Access Tokens** is enabled in your app's configuration. For other authentication options, see the <Link href="/guides/authentication">authentication overview</Link>.
    </Tip>
  </Step>

  <Step title="Provision the Sales Hub">
    Create a file called `create_hub.py`. This script creates a new hub and populates it with your sales content folders:

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        FolderReferenceV2025R0,
        HubItemOperationV2025R0,
        HubItemOperationV2025R0ActionField,
    )

    from box_client import get_box_client

    load_dotenv()

    def create_sales_hub(client: BoxClient) -> str:
        hub = client.hubs.create_hub_v2025_r0(
            "Sales RFP Answer Bank",
            description=(
                "Curated library of approved proposals, RFP responses, "
                "competitive intelligence, and pricing materials for the sales team."
            ),
        )

        print(f"Created hub: {hub.title} (ID: {hub.id})")
        return hub.id

    def add_content_to_hub(
        client: BoxClient, hub_id: str, folder_id: str
    ):
        client.hub_items.manage_hub_items_v2025_r0(
            hub_id,
            operations=[
                HubItemOperationV2025R0(
                    action=HubItemOperationV2025R0ActionField.ADD,
                    item=FolderReferenceV2025R0(id=folder_id),
                )
            ],
        )
        print(f"Added folder {folder_id} to hub {hub_id}")

    def main():
        client = get_box_client()

        hub_id = create_sales_hub(client)

        sales_folder_id = os.getenv("SALES_CONTENT_FOLDER_ID")
        add_content_to_hub(client, hub_id, sales_folder_id)

        print(f"\nSales Hub ready. Hub ID: {hub_id}")
        print("Share this hub with your sales team or embed it in your CRM.")

    if __name__ == "__main__":
        main()
    ```

    Run the script:

    ```bash theme={null}
    python create_hub.py
    ```

    You should see output confirming the hub was created and content was added. Save the hub ID printed in the output. You need it in the following steps.

    <Note>
      Adding a top-level folder automatically indexes all files within it, including subfolders. When new files are added to those folders in Box, the hub content updates automatically.
    </Note>
  </Step>

  <Step title="Manage hub access">
    Control who can access the Sales Hub by adding collaborations. This ensures only the right people can query the content.

    Create a file called `manage_access.py`:

    ```python theme={null}
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        CreateHubCollaborationV2025R0Hub,
        CreateHubCollaborationV2025R0AccessibleBy,
    )

    from box_client import get_box_client

    load_dotenv()

    def add_hub_collaborator(
        client: BoxClient,
        hub_id: str,
        user_email: str,
        role: str = "viewer",
    ):
        collaboration = client.hub_collaborations.create_hub_collaboration_v2025_r0(
            CreateHubCollaborationV2025R0Hub(id=hub_id),
            CreateHubCollaborationV2025R0AccessibleBy(
                type="user", login=user_email
            ),
            role,
        )
        print(f"Added {user_email} as {role} to hub {hub_id}")
        return collaboration

    def main():
        client = get_box_client()

        hub_id = "YOUR_HUB_ID"  # Replace with the hub ID from Step 4

        sales_reps = [
            "rep1@example.com",
            "rep2@example.com",
        ]

        for email in sales_reps:
            add_hub_collaborator(client, hub_id, email, role="viewer")

    if __name__ == "__main__":
        main()
    ```

    <Tip>
      Use the `viewer` role for sales reps who only need to query content, and `editor` for sales managers who curate the library. For details on all available roles, see <Link href="/guides/hubs-api/hubs-collaborations/hub-collaborations">Manage hub collaborations</Link>.
    </Tip>
  </Step>

  <Step title="Query the hub with Box AI">
    The most powerful part of this integration is letting reps ask natural language questions against the curated content. Create a file called `query_hub.py`:

    ```python theme={null}
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        CreateAiAskMode,
        AiItemAsk,
    )

    from box_client import get_box_client

    load_dotenv()

    def ask_sales_question(
        client: BoxClient, hub_id: str, question: str
    ) -> str:
        response = client.ai.create_ai_ask(
            mode=CreateAiAskMode.SINGLE_ITEM_QA,
            prompt=question,
            items=[
                AiItemAsk(
                    type="hubs",
                    id=hub_id,
                )
            ],
        )

        return response.answer

    def main():
        client = get_box_client()

        hub_id = "YOUR_HUB_ID"  # Replace with the hub ID from Step 4

        questions = [
            "What is our standard SLA for enterprise support?",
            "How do we handle data residency requirements for EU customers?",
            "What security certifications do we hold?",
            "What discount tiers are available for 500+ seat deals?",
        ]

        for question in questions:
            print(f"\nQ: {question}")
            answer = ask_sales_question(client, hub_id, question)
            print(f"A: {answer}")

    if __name__ == "__main__":
        main()
    ```

    Run:

    ```bash theme={null}
    python query_hub.py
    ```

    Box AI searches the hub's indexed content and returns answers grounded in your approved materials. Because hubs inherit Box permissions, the AI only references documents the querying user has access to.

    At this point, your project directory should contain the following files:

    ```
    sales-rfp-hub/
    ├── .env
    ├── .venv/
    ├── box_client.py
    ├── create_hub.py
    ├── manage_access.py
    └── query_hub.py
    ```
  </Step>

  <Step title="Test the integration">
    Before moving to production, verify each component works correctly.

    <Note>
      Make sure you are in the `sales-rfp-hub` directory and the virtual environment is activated before running any commands:

      ```bash theme={null}
      cd ~/sales-rfp-hub
      source .venv/bin/activate
      ```
    </Note>

    **1. Verify authentication:**

    Run a quick check to confirm your credentials are valid:

    ```bash theme={null}
    python -c "from box_client import get_box_client; client = get_box_client(); user = client.users.get_user_me(); print(f'Authenticated as: {user.name} ({user.login})')"
    ```

    You should see your Box user's name and email. If you see `invalid_client`, check your `.env` credentials.

    **2. Create the hub and add content:**

    ```bash theme={null}
    python create_hub.py
    ```

    You should see:

    ```
    Created hub: Sales RFP Answer Bank (ID: 12345678)
    Added folder 987654321 to hub 12345678

    Sales Hub ready. Hub ID: 12345678
    ```

    Copy the hub ID from the output. Open `query_hub.py` and `manage_access.py` and replace `YOUR_HUB_ID` with this value.

    <Warning>
      After creating the hub and adding content, allow **a few minutes** for Box to index the files before running queries. Queries against a newly created hub may return empty or incomplete results until indexing completes.
    </Warning>

    **3. Query the hub:**

    ```bash theme={null}
    python query_hub.py
    ```

    You should see questions printed followed by answers drawn from your sales content. If answers are empty or generic, verify that:

    * The hub ID is correct.
    * The content folder contains documents (not just subfolders).
    * Enough time has passed for indexing to complete.

    **4. Verify in Box:**

    Open the [Box web app](https://app.box.com) and navigate to **Hubs** in the left sidebar. Your "Sales RFP Answer Bank" hub should appear with the content folders listed.
  </Step>

  <Step title="Keep the hub current">
    <Info>
      This step provides reference patterns for keeping your hub up to date. You don't need to run these now. Integrate them into your application code when your sales content changes.
    </Info>

    A stale answer bank is worse than no answer bank. Automate content freshness by updating hub items when your sales content changes.

    ```python theme={null}
    from box_sdk_gen import (
        BoxClient,
        FolderReferenceV2025R0,
        HubItemOperationV2025R0,
        HubItemOperationV2025R0ActionField,
    )

    def refresh_hub_content(
        client: BoxClient, hub_id: str, new_folder_id: str
    ):
        """Add a new content folder to the hub."""
        client.hub_items.manage_hub_items_v2025_r0(
            hub_id,
            operations=[
                HubItemOperationV2025R0(
                    action=HubItemOperationV2025R0ActionField.ADD,
                    item=FolderReferenceV2025R0(id=new_folder_id),
                )
            ],
        )
        print(f"Added folder {new_folder_id} to hub {hub_id}")

    def remove_outdated_content(
        client: BoxClient, hub_id: str, old_folder_id: str
    ):
        """Remove a folder from the hub."""
        client.hub_items.manage_hub_items_v2025_r0(
            hub_id,
            operations=[
                HubItemOperationV2025R0(
                    action=HubItemOperationV2025R0ActionField.REMOVE,
                    item=FolderReferenceV2025R0(id=old_folder_id),
                )
            ],
        )
        print(f"Removed folder {old_folder_id} from hub {hub_id}")
    ```

    <Tip>
      Pair this with a quarterly content review process. Sales reviews the hub contents, archives outdated materials, and adds new approved content. The hub reindexes automatically.
    </Tip>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Platform Apps > App > Configuration.
    * Confirm `BOX_USER_ID` is a valid Box user ID (numeric, found in Admin Console > Users).
    * Ensure your app is authorized in the Developer Console.
    * Confirm the app type is Client Credentials Grant with **Generate User Access Tokens** enabled.
  </Accordion>

  <Accordion title="403 Forbidden or 'access_denied_insufficient_permissions'">
    The authenticated user does not have the required scopes or permissions:

    * Verify that **Read all files and folders** and **Write all files and folders** scopes are enabled on your app.
    * Confirm the **Manage AI** scope is enabled (required for Box AI queries).
    * If using a service account, ensure it has been invited as a collaborator on the content folders.
  </Accordion>

  <Accordion title="404 Not Found when creating the hub or adding items">
    The folder ID is incorrect or the authenticated user does not have access to it. Double-check:

    * The folder ID in your `.env` file matches the URL in Box (`https://app.box.com/folder/123456789` means the folder ID is `123456789`).
    * The user specified in `BOX_USER_ID` has at least **Viewer** access to the folder.
  </Accordion>

  <Accordion title="Box AI returns empty or irrelevant answers">
    This usually means the hub content has not finished indexing, or the content is not suitable for the question:

    * Wait a few minutes after adding content before querying. Indexing is not instantaneous.
    * Verify the hub contains files (not just empty folders) by checking in the Box web app under **Hubs**.
    * Ensure your documents contain text content (scanned image PDFs without OCR are not searchable).
    * Try asking a question that directly relates to content you know exists in the hub.
  </Accordion>

  <Accordion title="Hub not visible in Box web app">
    The hub may have been created successfully but the current user does not have collaboration access. Run `manage_access.py` to add yourself or check the hub owner. Alternatively, verify Box Hubs is enabled for your account. On a managed account, check with your Box administrator.
  </Accordion>
</AccordionGroup>

## Embed the hub in your CRM

You can embed the hub's AI chat interface directly into your CRM (such as Salesforce, HubSpot, or a custom internal tool), giving reps a focused chatbot experience powered by the hub's content. Box supports two embed modes for hub AI chat: a chat button and a chat widget.

For the full list of embed parameters and options, see <Link href="/guides/embed/box-embed/#box-hubs-ai-chat-embedding">Box Hubs AI Chat embedding</Link>.

<Info>
  Users accessing the embedded hub authenticate through their existing Box session. If they are already signed in to Box (common with SSO-enabled enterprises), the chat loads seamlessly with no additional login prompt. Users need at least Viewer permissions on the hub.
</Info>

## Scaling to production

<AccordionGroup>
  <Accordion title="Automate hub provisioning for multiple teams">
    If you have separate sales teams (by region, vertical, or product line), you can provision a dedicated hub for each. First, update `create_sales_hub` in `create_hub.py` to accept an optional `title` parameter instead of the hardcoded value. Then loop over your teams:

    ```python theme={null}
    teams = {
        "EMEA": "EMEA_FOLDER_ID",
        "APAC": "APAC_FOLDER_ID",
        "Americas": "AMERICAS_FOLDER_ID",
    }

    for team, folder_id in teams.items():
        hub_id = create_sales_hub(client, title=f"Sales RFP Bank — {team}")
        add_content_to_hub(client, hub_id, folder_id)
    ```
  </Accordion>

  <Accordion title="Build a conversational RFP assistant">
    The `POST /2.0/ai/ask` endpoint accepts a `dialogue_history` parameter that carries previous Q\&A pairs. Maintain a list of exchanges and pass it with each request so reps can ask follow-ups like "Can you elaborate on the data residency point?" without losing context.

    Add the following to `query_hub.py`, or create a new script with the same imports and client setup:

    ```python theme={null}
    from datetime import datetime, timezone
    from box_sdk_gen import AiDialogueHistory

    history = []

    while True:
        question = input("Q: ")
        response = client.ai.create_ai_ask(
            mode=CreateAiAskMode.SINGLE_ITEM_QA,
            prompt=question,
            items=[AiItemAsk(type="hubs", id=hub_id)],
            dialogue_history=history,
        )
        print(f"A: {response.answer}")
        history.append(
            AiDialogueHistory(
                prompt=question,
                answer=response.answer,
                created_at=datetime.now(timezone.utc).isoformat(),
            )
        )
    ```
  </Accordion>

  <Accordion title="Track usage and measure impact">
    Use <Link href="/guides/events/enterprise-events/for-enterprise">enterprise events</Link> to monitor how often the hub is queried and which content is accessed most frequently. This data helps sales prioritize content curation and measure the ROI of the answer bank.
  </Accordion>

  <Accordion title="Enforce content governance">
    Combine hubs with <Link href="/guides/retention-policies">retention policies</Link> to automatically archive or delete outdated sales materials. Use <Link href="/guides/metadata/index">metadata</Link> to tag content with review dates and ownership.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Invoice intake automation" href={localizeLink("/tutorials/invoice-intake")} icon="file-invoice">
    Automate accounts payable with Box AI Extract and metadata.
  </Card>

  <Card title="Box Hubs API reference" href={localizeLink("/guides/hubs-api/index")} icon="server">
    See the full Hubs API guide for advanced hub management.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Build secure in-app document review with Box View
Source: https://developer.box.com/tutorials/secure-in-app-document-review

Upload documents to Box, embed a secure expiring preview in your own app, and add in-context annotations with Box Content Preview.

This tutorial builds a loan review workbench that uploads borrower documents to Box and renders them for review inside your own app, so reviewers never leave your interface to read a sensitive document.

When you need a richer experience (in-context markup, a metadata and activity sidebar, or Box AI Q\&A), layer <Link href="/guides/embed/ui-elements/preview">Box Content Preview</Link> on the same underlying files in Box.

<Card title="Clone the working sample" href="https://github.com/box-community/box-secure-doc-review" icon="github">
  Prefer to start from running code? The complete app built in this tutorial is on GitHub. Clone it, add your Box credentials, and run.
</Card>

## What you are building

By the end of this tutorial, you have a working integration that:

* Uploads borrower documents to Box using the upload API, triggering automatic conversion for preview.
* Generates a short-lived, expiring embed URL for any uploaded file.
* Renders the document inside an `<iframe>` in your workbench.
* Mints downscoped, file-scoped tokens so the browser only ever holds a least-privilege credential.
* Upgrades the bare iframe to Box Content Preview so reviewers can annotate in context and use a richer review UI.

<Accordion
  title="Watch the upload and embed flow"
  icon={
<svg width="18" height="18" viewBox="0 0 24 24" aria-hidden="true">
  <circle cx="12" cy="12" r="10" fill="#0061D5" />
  <circle cx="12" cy="8" r="1.25" fill="#FFFFFF" />
  <rect x="10.75" y="10.5" width="2.5" height="7" rx="1.25" fill="#FFFFFF" />
</svg>
}
>
  A `curl` upload returns a file ID, then opening `http://127.0.0.1:5000/review/<file_id>` in the browser renders the sample document inside your workbench.

  <video>
    Your browser does not support embedded video. Follow the step-by-step instructions below to test the flow locally.
  </video>
</Accordion>

## Prerequisites

Before you start, make sure you have the following:

* A <Link href="https://account.box.com/signup/developer">free Box developer account</Link>, or a Box account with access to the Developer Console and admin rights to authorize a Platform App. Free developer accounts include the Box AI API used by the optional Q\&A layer; on other accounts, make sure Box AI is enabled. Consumer/Individual accounts do not support this tutorial.
* A Box <Link href="/guides/embed/box-view/setup">Platform App configured for Box View</Link> with **Client Credentials Grant (CCG)** authentication and **Application Access** set to **App Access Only**. This makes the app's Service Account the owner of every uploaded document.
* Python 3.11 or higher.
* The following scope enabled on your app:
  * Read and write all files and folders stored in Box
* The exact origin that serves your workbench front end (for example, `http://127.0.0.1:5000`) added to the **CORS allow-list** in the <Link href="https://cloud.app.box.com/developers/console">Developer Console</Link>. **This is required for the <Link href="/tutorials/secure-in-app-document-review#add-in-context-annotations-with-box-content-preview">Box Content Preview annotation step</Link>**. Content Preview fails with a `403` until the origin is allow-listed.
* Your Box enterprise ID (found in the Developer Console under the account icon, **Copy Enterprise ID**).

<Note>
  This tutorial uses CCG authenticating as the **Service Account** (`enterprise_id`). Because the Service Account owns the files it uploads, no collaboration invites are required to preview them - a key simplification compared to integrations that operate on existing enterprise content.
</Note>

## How it works

Box View follows a three-stage flow:

1. **Upload.** Your backend uploads the borrower document to Box over the secure upload API. Content is stored with virus scanning and 256-bit encryption.
2. **Conversion.** On upload, Box automatically converts the file into HTML5-compatible assets that render crisply and responsively. Conversion happens once per file and the assets persist for as long as the file is stored.
3. **Embed.** Your backend requests an `expiring_embed_link` for the file and returns it to the front end, which places it in an `<iframe>`.

This solution uses three Box capabilities:

| Component | Purpose | API |
| - | - | - |
| **Upload API** | Store the borrower's tax return or statement in Box | `POST /2.0/files/content` |
| **Expiring embed link** | Generate a short-lived preview URL for the `<iframe>` | `GET /2.0/files/:id?fields=expiring_embed_link` |
| **Token exchange (downscope)** | Mint a least-privilege, file-scoped token for Box Content Preview and annotations | `POST /oauth2/token` |

<Warning>
  The expiring embed link is valid for **about one minute** and is meant to be dropped into an `<iframe>` immediately after it is generated. Always generate it server-side, on demand, when the reviewer opens a document - never store it or send it ahead of time.
</Warning>

## Step-by-step process

<Steps>
  <Step title="Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir loan-review && cd loan-review
    ```

    2. Create and activate a Python virtual environment:

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    After activation, your terminal prompt shows `(.venv)` at the beginning. This confirms you are working inside the virtual environment.

    <Note>
      Every time you open a new terminal window or tab, you must re-activate the virtual environment by running `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError` when running commands, it usually means the venv is not activated.
    </Note>

    3. Install the required packages:

    ```bash theme={null}
    pip install boxsdk flask python-dotenv
    ```

    4. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your actual credentials from the Box Developer Console:

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    LOAN_DOCS_FOLDER_ID=0
    ```

    <Note>
      `LOAN_DOCS_FOLDER_ID` defaults to `0`, the Service Account's root folder. That is fine for getting started. For a real deployment, create a dedicated folder (for example, one folder per loan application) and use its ID so documents stay organized.
    </Note>

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>

    <Note>
      **Understanding environment variables:** The `.env` file stores sensitive values (your actual credentials). Your Python code reads these values by referencing their **names** using `os.getenv("VARIABLE_NAME")`. For example, `os.getenv("BOX_CLIENT_ID")` looks up the value stored next to `BOX_CLIENT_ID=` in your `.env` file. When you copy the code in the following steps, keep the quoted variable names exactly as shown. Do not replace them with your actual credentials.
    </Note>
  </Step>

  <Step title="Authenticate the Box client">
    Create a new file called `box_client.py` in your project directory. Open the file and paste the following code:

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        BoxCCGAuth,
        CCGConfig,
    )

    load_dotenv()

    def get_box_client() -> BoxClient:
        config = CCGConfig(
            client_id=os.getenv("BOX_CLIENT_ID"),
            client_secret=os.getenv("BOX_CLIENT_SECRET"),
            enterprise_id=os.getenv("BOX_ENTERPRISE_ID"),
        )
        auth = BoxCCGAuth(config=config)
        return BoxClient(auth=auth)
    ```

    <Tip>
      Client Credentials Grant is recommended for server-to-server Box View use cases where the application's Service Account owns the content. For other authentication options, see the <Link href="/guides/authentication">authentication overview</Link>.
    </Tip>
  </Step>

  <Step title="Upload a borrower document">
    Create a new file called `upload.py`. This function uploads a document to the loan documents folder and returns the new file ID. Uploading a document automatically triggers conversion, so the file is ready to preview moments later.

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import (
        BoxClient,
        UploadFileAttributes,
        UploadFileAttributesParentField,
    )

    load_dotenv()

    def upload_document(client: BoxClient, file_path: str) -> str:
        folder_id = os.getenv("LOAN_DOCS_FOLDER_ID", "0")
        file_name = os.path.basename(file_path)

        with open(file_path, "rb") as file_stream:
            uploaded = client.uploads.upload_file(
                UploadFileAttributes(
                    name=file_name,
                    parent=UploadFileAttributesParentField(id=folder_id),
                ),
                file_stream,
            )

        file_id = uploaded.entries[0].id
        print(f"Uploaded {file_name} -> file ID {file_id}")
        return file_id
    ```

    <Note>
      For most document and image types, conversion is triggered automatically on upload. For video and 3D files, conversion is triggered on first preview instead. Either way, conversion runs only once per file and no explicit action is required from your code.
    </Note>
  </Step>

  <Step title="Generate the preview embed URL">
    Create a new file called `preview.py`. The `get_embed_url` function asks Box for the file's `expiring_embed_link` and returns the URL your front end will place in an `<iframe>`.

    ```python theme={null}
    from box_sdk_gen import BoxClient

    def get_embed_url(client: BoxClient, file_id: str) -> str:
        file = client.files.get_file_by_id(
            file_id,
            fields=["expiring_embed_link"],
        )

        if not file.expiring_embed_link:
            raise RuntimeError(
                "No embed link returned. The file may still be converting, "
                "or preview is not available for this file type."
            )

        return file.expiring_embed_link.url
    ```

    <Warning>
      Request `expiring_embed_link` only through the `fields` parameter, and use it right away. The link expires after about one minute by design - this is what keeps the embed secure.
    </Warning>
  </Step>

  <Step title="Mint a downscoped token for the browser">
    The bare iframe never needs a token, but Box Content Preview (added later) runs in the browser and does. Add a function to `preview.py` that exchanges the full Service Account token for a **downscoped**, file-scoped token. This token can only do what the scopes allow, on a single file, and is short-lived - safe to send to the browser.

    ```python theme={null}
    from box_sdk_gen import BoxClient

    PREVIEW_SCOPES = [
        "base_preview",
        "item_preview",
        "annotation_edit",
        "annotation_view_all",
        "item_download",
    ]

    def get_downscoped_token(client: BoxClient, file_id: str) -> dict:
        token = client.auth.downscope_token(
            PREVIEW_SCOPES,
            resource=f"https://api.box.com/2.0/files/{file_id}",
        )
        return {
            "access_token": token.access_token,
            "expires_in": token.expires_in,
        }
    ```

    The scopes map directly to review capabilities:

    | Scope | What it allows |
    | - | - |
    | `base_preview` | Preview the file in Box Content Preview |
    | `item_preview` | Preview the file (expiring embed link) |
    | `annotation_edit` | Create, edit, and delete the reviewer's own annotations |
    | `annotation_view_all` | View annotations from all reviewers on the file |
    | `item_download` | Enable text selection and highlight annotations (and download/print) |

    <Warning>
      Never expose your client secret or a full access token in client-side code. Always downscope before sending a token to the browser. See <Link href="/guides/embed/box-view/best-practices#downscope-tokens">Box View best practices</Link>.
    </Warning>
  </Step>

  <Step title="Expose the backend endpoints">
    Create a new file called `app.py`. This Flask application is the backend your loan workbench calls. It exposes one endpoint to upload a document, one to fetch a fresh embed URL on demand, and one to mint a downscoped token.

    ```python theme={null}
    import os
    import tempfile

    from dotenv import load_dotenv
    from flask import Flask, request, jsonify, send_file

    from box_client import get_box_client
    from upload import upload_document
    from preview import get_embed_url, get_downscoped_token

    load_dotenv()
    app = Flask(__name__)

    @app.route("/api/documents", methods=["POST"])
    def upload():
        if "file" not in request.files:
            return jsonify({"error": "no file provided"}), 400

        incoming = request.files["file"]
        with tempfile.NamedTemporaryFile(
            delete=False, suffix=f"_{incoming.filename}"
        ) as tmp:
            incoming.save(tmp.name)
            temp_path = tmp.name

        try:
            client = get_box_client()
            file_id = upload_document(client, temp_path)
        finally:
            os.remove(temp_path)

        return jsonify({"file_id": file_id}), 201

    @app.route("/api/documents/<file_id>/embed", methods=["GET"])
    def embed(file_id):
        client = get_box_client()
        embed_url = get_embed_url(client, file_id)
        return jsonify({"embed_url": embed_url}), 200

    @app.route("/api/documents/<file_id>/token", methods=["GET"])
    def token(file_id):
        client = get_box_client()
        return jsonify(get_downscoped_token(client, file_id)), 200

    @app.route("/review/<file_id>")
    def review_page(file_id):
        return send_file("review.html")

    if __name__ == "__main__":
        app.run(port=5000, debug=True)
    ```

    <Note>
      The `/embed` endpoint creates the link fresh on every request. Because the link expires in about a minute, the front end should call this endpoint at the moment the reviewer opens a document, not ahead of time.
    </Note>

    <Warning>
      **Restart Flask whenever you add or change a route.** Flask loads your code once at startup, so a newly added route (like `/review/<file_id>`) returns `404 Not Found` until you stop the server with `Ctrl+C` and run `python app.py` again. Setting `debug=True` enables the auto-reloader so subsequent edits reload automatically - but the very first run after adding a route still requires a manual restart. Do not use `debug=True` in production.
    </Warning>

    <Warning>
      The `/review/<file_id>` route serves the review page **from the same origin as the backend** so the page's relative `fetch("/api/...")` calls reach your API. Do not open `review.html` by double-clicking it - opening it over the `file://` protocol means the relative `fetch` has no server to call, the iframe `src` is never set, and you see only the page header. You build `review.html` in the next step.
    </Warning>

    At this point, your project directory should contain the following files:

    ```
    loan-review/
    ├── .env
    ├── .venv/
    ├── app.py
    ├── box_client.py
    ├── preview.py
    └── upload.py
    ```
  </Step>

  <Step title="Render the document in an iframe">
    With the backend in place, the front end is simple: fetch the embed URL, then set it as the `src` of an `<iframe>`. This is the secure, in-app review surface - the reviewer never leaves your workbench.

    Create a file called `review.html` in the project root (next to `app.py`, so the `/review/<file_id>` route can serve it). The page reads the file ID from its own URL path, so you never hardcode it.

    ```html theme={null}
    <!DOCTYPE html>
    <html lang="en-US">
      <head>
        <meta charset="utf-8" />
        <title>Loan document review</title>
        <style>
          body { margin: 0; font-family: system-ui, sans-serif; }
          header { padding: 12px 20px; background: #f5f6f8; border-bottom: 1px solid #e0e0e0; }
          iframe { width: 100%; height: calc(100vh - 50px); border: 0; }
        </style>
      </head>
      <body>
        <header><strong>Loan application 4815</strong> &middot; Borrower tax return</header>
        <iframe id="doc" title="Borrower document"></iframe>

        <script>
          // The file ID is the last segment of the URL, e.g. /review/1234567890
          const fileId = window.location.pathname.split("/").pop();

          async function loadPreview() {
            const res = await fetch(`/api/documents/${fileId}/embed`);
            const { embed_url } = await res.json();
            document.getElementById("doc").src = embed_url;
          }

          loadPreview();
        </script>
      </body>
    </html>
    ```

    <Warning>
      Always reach this page through the backend at `http://127.0.0.1:5000/review/<file_id>` - never by double-clicking `review.html`. A double-clicked file opens over `file://`, where the relative `fetch("/api/...")` has no server to reach. The iframe `src` is then never set and you see only the header. The page and the API must share an origin.
    </Warning>

    <Tip>
      In production, the workbench app and the Box-facing backend typically live behind the same gateway (same origin), or you proxy `/api/*` to the backend, so these relative `fetch` calls resolve.
    </Tip>
  </Step>

  <Step title="Test the upload and embed flow">
    You can exercise the whole pipeline from the command line before wiring it into a UI.

    <Note>
      Make sure you are in the `loan-review` directory and the virtual environment is activated before running any commands:

      ```bash theme={null}
      cd ~/loan-review
      source .venv/bin/activate
      ```
    </Note>

    **1. Start the backend:**

    ```bash theme={null}
    python app.py
    ```

    You should see `Running on http://127.0.0.1:5000`. Leave this terminal running.

    **2. Upload a document.** In a second terminal, upload a sample tax return or statement (any PDF works):

    ```bash theme={null}
    curl -X POST http://127.0.0.1:5000/api/documents \
      -F "file=@sample-tax-return.pdf"
    ```

    You should get back a file ID:

    ```json theme={null}
    { "file_id": "1234567890" }
    ```

    **3. Fetch an embed URL** for that file ID:

    ```bash theme={null}
    curl http://127.0.0.1:5000/api/documents/1234567890/embed
    ```

    ```json theme={null}
    { "embed_url": "https://app.box.com/preview/expiring_embed/gvoct6FE!YT_X1Lau..." }
    ```

    **4. View it in the iframe.** With the backend still running, open the review page through the server, using your file ID as the last path segment:

    ```
    http://127.0.0.1:5000/review/1234567890
    ```

    The document renders inside the iframe. If instead you see only the `Loan application 4815` header, you most likely opened `review.html` by double-clicking it (the `file://` protocol) - open it through the URL above instead. As a separate sanity check, pasting the embed URL from step 3 directly into the browser within a minute also renders the document, proving conversion succeeded.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > your app > Configuration.
    * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID (Developer Console > account icon > Copy Enterprise ID).
    * Ensure the app type is Client Credentials Grant and the app has been authorized.
  </Accordion>

  <Accordion title="unauthorized_client">
    The app has not been authorized by an admin yet. In the Developer Console, open the **Authorization** tab, click **Review and Submit**, and have your Box admin approve it in the Admin Console. See <Link href="/guides/authorization/platform-app-approval">Platform App approval</Link>.
  </Accordion>

  <Accordion title="No embed link returned / null expiring_embed_link">
    Conversion may still be in progress, or the file type does not support preview. Wait a few seconds after upload and retry. Confirm the uploaded file is a supported type - see the <Link href="/guides/representations/supported-file-types">supported file types</Link>.
  </Accordion>

  <Accordion title="404 Not Found when opening /review/<file_id>">
    Flask does not have the `/review/<file_id>` route registered. This almost always means you added the route but did not restart the server - Flask loads your code once at startup. Stop the server with `Ctrl+C` and run `python app.py` again. Also confirm `send_file` is imported (`from flask import Flask, request, jsonify, send_file`) and that the route exists in `app.py`. Running with `debug=True` enables auto-reload for future edits.
  </Accordion>

  <Accordion title="The page shows only the header, not the document">
    You opened `review.html` directly (over the `file://` protocol) instead of through the backend. The page's relative `fetch("/api/documents/.../embed")` call only works when the page is served from the same origin as the API. Start the backend and open `http://127.0.0.1:5000/review/<file_id>` instead of double-clicking the file. Open your browser's developer console to confirm - you will see the failed `fetch` request.
  </Accordion>

  <Accordion title="The iframe is blank or shows 'This shared file is no longer available'">
    The embed link has expired. Embed links last about one minute. Generate the link immediately before setting the iframe `src`, and request a new one each time the reviewer opens the document.
  </Accordion>

  <Accordion title="The annotate page returns 403 (Forbidden) even though the review page works">
    This is almost always a **CORS allow-list** issue. The iframe review page loads a Box-hosted URL and never calls the Box API from your origin, so it works without CORS. Box Content Preview, however, calls `api.box.com` **directly from the browser** - in your developer console you will see repeated `GET https://api.box.com/2.0/files/<id>?fields=...` requests returning `403`, thrown from `preview.js`.

    Fixes, in order:

    * Add the **exact** origin you open the page from to the CORS allow-list (Developer Console > your app > **Configuration** > **CORS Domains**), including scheme and port - for example `http://127.0.0.1:5000`. Remember that `127.0.0.1` and `localhost` are different origins; add whichever you use. Save and wait a minute or two, then restart and reload.
    * If it still `403`s, the downscoped token lacks permissions: confirm the **Read and write all files and folders** scope is enabled and that you **re-authorized** the app in the Admin Console afterward.
    * Confirm the file ID in the `/annotate/<file_id>` URL matches the file the token was minted for - the token is downscoped to a single file, so a mismatched ID also returns `403`.
  </Accordion>
</AccordionGroup>

## Add in-context annotations with Box Content Preview

The iframe embed is perfect for fast, read-only review. To let reviewers **mark up documents in context** - highlight a suspicious figure on a tax return, drop a point comment on a missing signature - render the same file with the <Link href="/guides/embed/ui-elements/preview">Box Content Preview</Link> UI Element instead of the bare iframe. Content Preview powers preview in the Box web app itself and runs entirely client-side, so annotations stay inside your workbench.

Content Preview needs a token in the browser. You already built the `/token` endpoint that returns a downscoped, file-scoped token with annotation scopes, so the front end never sees a full-privilege credential.

<Warning>
  **You must add your serving origin to the CORS allow-list before this step will work.** Box Content Preview makes API calls **directly from the browser to `api.box.com`**. Box rejects those calls with a `403 (Forbidden)` unless the page's origin is on your app's CORS allow-list (Developer Console > your app > **Configuration** > **CORS Domains**).

  Add the **exact** origin you open the page from, including the scheme and port - for example `http://127.0.0.1:5000`. Note that `http://127.0.0.1:5000` and `http://localhost:5000` are **different origins**: allow-list whichever you actually browse to (or add both). Changes can take a minute or two to take effect.
</Warning>

Create a file called `annotate.html` in the project root, then add a route in `app.py` to serve it from the same origin as the API - just like the iframe page:

```python theme={null}
@app.route("/annotate/<file_id>")
def annotate_page(file_id):
    return send_file("annotate.html")
```

```html theme={null}
<!DOCTYPE html>
<html lang="en-US">
  <head>
    <meta charset="utf-8" />
    <title>Loan document review</title>
    <link
      rel="stylesheet"
      href="https://cdn01.boxcdn.net/platform/preview/3.0.0/en-US/preview.css"
    />
    <script src="https://cdn01.boxcdn.net/platform/preview/3.0.0/en-US/preview.js"></script>
    <style>
      .preview-container { height: 100vh; width: 100%; }
    </style>
  </head>
  <body>
    <div class="preview-container"></div>

    <script>
      // The file ID is the last segment of the URL, e.g. /annotate/1234567890
      const fileId = window.location.pathname.split("/").pop();

      async function loadPreview() {
        const res = await fetch(`/api/documents/${fileId}/token`);
        const { access_token } = await res.json();

        const preview = new Box.Preview();
        preview.show(fileId, access_token, {
          container: ".preview-container",
          showAnnotations: true,
        });
      }

      loadPreview();
    </script>
  </body>
</html>
```

Open it the same way you opened the iframe page - through the backend, at `http://127.0.0.1:5000/annotate/<file_id>`, not by double-clicking the file.

When `showAnnotations` is `true` and the token carries the annotation scopes, reviewers see annotation controls in the preview header. Annotations are stored against the file in Box, so a second reviewer opening the same document sees the first reviewer's notes (granted `annotation_view_all`).

<Note>
  Box Annotations support **highlight comment**, **highlight only**, **draw**, and **point** annotation types. Point annotations work on both documents and images; highlight and draw annotations are document-only. Highlight annotations also require the `item_download` scope so the text layer is available. See the <Link href="/guides/embed/ui-elements/annotations">Annotations guide</Link> for the full matrix and for enabling real-time V4 annotations.
</Note>

<Warning>
  If the preview still returns a `403` **after** you have allow-listed the origin, the downscoped token is missing permissions. Confirm the **Read and write all files and folders** scope is enabled on your app, and that you **re-authorized** the app in the Admin Console after enabling it - CCG scope changes do not take effect until the app is re-approved. See the <Link href="/guides/embed/ui-elements/scopes">dedicated scopes</Link> guide.
</Warning>

## Layer a richer review UI

Once you are running Box Content Preview, you can progressively enrich the reviewer experience on the very same files - no re-upload, no second copy of the document.

<AccordionGroup>
  <Accordion title="Add a metadata and activity sidebar">
    Use the Content Preview element's sidebar to show file details, versions, and an activity feed alongside the document, so reviewers can see the document's history and discuss it without leaving the page. Enable annotations in the activity feed and the document view together for a connected review workflow. See <Link href="/guides/embed/ui-elements/sidebar">Content Sidebar</Link>.
  </Accordion>

  <Accordion title="Answer questions with Box AI in the previewer">
    Box AI for UI Elements adds document Q\&A and summaries directly in the Content Preview header. A reviewer can ask "What is the borrower's reported annual income?" and get a cited answer grounded in the document. Pass `hasHeader: true` and `contentAnswersProps` to `preview.show()`. See <Link href="/guides/embed/ui-elements/preview#box-ai-for-ui-elements">Box AI for UI Elements</Link>.
  </Accordion>

  <Accordion title="Review a full application as a collection">
    A loan application is rarely one file. Pass a `collection` of file IDs to `preview.show()` so reviewers can page through the tax return, W-2, and bank statements with navigation arrows inside one previewer.

    ```js theme={null}
    preview.show(fileId, access_token, {
      container: ".preview-container",
      collection: ["1234567890", "1234567891", "1234567892"],
      showAnnotations: true,
    });
    ```

    Mint the downscoped token with a resource and scopes that cover each file in the collection.
  </Accordion>

  <Accordion title="Tailor capabilities with scopes">
    Match the token's scopes to the reviewer's role. A junior reviewer might get `base_preview` + `annotation_view_self` + `annotation_edit` (sees only their own notes), while a senior underwriter gets `annotation_view_all`. After a decision is locked, drop the edit scopes to make the document effectively read-only. See <Link href="/guides/embed/ui-elements/preview#scopes">Content Preview scopes</Link>.
  </Accordion>
</AccordionGroup>

## Scaling to production

<AccordionGroup>
  <Accordion title="Organize documents per application">
    Instead of uploading everything to the Service Account root, create a folder per loan application and pass its ID as the upload parent. This keeps documents grouped, makes cleanup simple, and lets you apply <Link href="/guides/retention-policies/index">retention policies</Link> at the folder level for compliance.
  </Accordion>

  <Accordion title="Refresh tokens and embed links on demand">
    Embed links expire in about a minute and downscoped tokens are short-lived by design. Generate both server-side at the moment they are needed. For Content Preview, pass a <Link href="/guides/embed/ui-elements/preview#token-generator-function">token generator function</Link> instead of a static string so the previewer can fetch a fresh token whenever it needs one.
  </Accordion>

  <Accordion title="Keep credentials server-side">
    The client secret, enterprise ID, and full access token must never reach the browser. Store them in environment variables or a secrets manager, keep **Application Access** set to **App Access Only**, and restrict the CORS allow-list to the exact domains that run Box Content Preview. See <Link href="/guides/embed/box-view/best-practices">Box View best practices</Link>.
  </Accordion>

  <Accordion title="Audit the review with enterprise events">
    Use <Link href="/guides/events/enterprise-events/for-enterprise">enterprise events</Link> to track previews, downloads, and annotation activity across every loan document. This gives compliance teams an audit trail of who reviewed what, and when - without instrumenting your own app.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Invoice intake automation" href="/tutorials/invoice-intake" icon="file-invoice">
    Automate accounts payable with Box AI Extract and metadata.
  </Card>

  <Card title="Box View overview" href="/guides/embed/box-view/index" icon="eye">
    Learn how upload, conversion, and embed fit together.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Turn supplier agreements into structured procurement data with Box AI
Source: https://developer.box.com/tutorials/supplier-agreements

Extract grouped vendor details and repeating delivery schedules from supplier agreements using the struct and table field types in Box AI structured extraction.

Enterprise procurement documents rarely contain just a few flat fields. A single supplier agreement can include vendor contact details, delivery milestones, ship-to locations, and payment terms across paragraphs and tables.

This tutorial shows you how to turn that complexity into clean, structured output. You use the `struct` and `table` field types in Box AI structured extraction to define a schema that matches the shape of the document, then call the extract endpoint with the [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent) to return data that is ready for downstream systems, automations, and Box metadata.

## What you are building

By the end of this tutorial, you have a working Python project that:

* Authenticates to Box and reads a supplier agreement stored in a Box folder.
* Defines an extraction schema that uses a `struct` field for grouped vendor details and a `table` field for a repeating delivery schedule.
* Calls the [POST /2.0/ai/extract\_structured](/reference/post-ai-extract-structured) endpoint with the [Enhanced Extract Agent](/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent).
* Maps the response into a procurement record that you can push to an ERP, procurement platform, or project tracker.

## Why struct and table

The [POST /2.0/ai/extract\_structured](/reference/post-ai-extract-structured) endpoint supports two complex field types in addition to scalar types such as `string`, `float`, `date`, `enum`, and `multiSelect`:

| Field type | Returns | Use it for |
| - | - | - |
| `struct` | A single nested JSON object | Related values that belong together, such as a vendor's legal name, address, and contact details. |
| `table` | An array of JSON objects with the same schema | Repeating rows, such as delivery milestones, line items, or payment schedules. |

These types let you mirror how the data is actually used. Instead of parsing one long vendor block or collapsing a delivery schedule into a single string after extraction, you map the result directly into a supplier master record or procurement workflow.

<Tip>
  For a full reference of both field types and their supported sub-field types, see <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured#struct-and-table-field-types">struct and table field types</Link>.
</Tip>

## Prerequisites

Before you start, make sure you have the following:

* A free <Link href="https://account.box.com/signup/developer">Box developer account</Link>, which gives you access to the Box AI API.
* A Box application configured with **Client Credentials Grant** authentication.
* Python 3.11 or higher.
* A supplier agreement uploaded to Box. You can download a <Link href="/static/quickstarts/extract/files/supplier-agreement-sample.pdf">sample supplier agreement</Link> and upload it to a Box folder. Note its **file ID** from the URL. For example, if the URL is `https://app.box.com/file/123456789`, the file ID is `123456789`.
* The following scopes enabled on your app:
  * Read and write all files and folders stored in Box
  * Manage AI

## Step-by-step process

This tutorial uses one Box capability and one Box AI agent:

| Component | Purpose | API |
| - | - | - |
| **Box AI Extract** | Pull grouped and repeating structured data from the agreement | `POST /2.0/ai/extract_structured` |
| **Enhanced Extract Agent** | Improve accuracy for nested and repeating fields | `ai_agent.id = enhanced_extract_agent` |

The Enhanced Extract Agent is a predefined Box AI agent, so you do not create or configure it yourself. You reference it by its ID (`enhanced_extract_agent`) in the `ai_agent` parameter of your extraction request, which you build in the **Build the extraction function** step below. To learn more, see the <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured#enhanced-extract-agent">Enhanced Extract Agent</Link> reference.

<Steps>
  <Step title="Set up the development environment">
    1. Open your terminal and create a new project directory:

    ```bash theme={null}
    mkdir supplier-extraction && cd supplier-extraction
    ```

    2. Create and activate a Python virtual environment:

    ```bash theme={null}
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    After activation, your terminal prompt shows `(.venv)` at the beginning. This confirms you are working inside the virtual environment.

    <Note>
      Every time you open a new terminal window or tab, re-activate the virtual environment by running `source .venv/bin/activate` from the project directory. If you see `ModuleNotFoundError` when running commands, it usually means the venv is not activated.
    </Note>

    3. Install the required packages:

    ```bash theme={null}
    pip install boxsdk python-dotenv
    ```

    4. Create a `.env` file to store your credentials, then add the following content. Replace the placeholder values with your actual credentials from the Box Developer Console:

    ```bash theme={null}
    BOX_CLIENT_ID=your_client_id
    BOX_CLIENT_SECRET=your_client_secret
    BOX_ENTERPRISE_ID=your_enterprise_id
    AGREEMENT_FILE_ID=your_file_id
    ```

    <Warning>
      Never commit `.env` files to version control. Add `.env` to your `.gitignore`.
    </Warning>
  </Step>

  <Step title="Authenticate the Box client">
    Create a file called `box_client.py` and add the following code. It builds an authenticated client that you use to call Box AI through the SDK.

    ```python theme={null}
    import os
    from dotenv import load_dotenv
    from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig

    load_dotenv()

    def get_box_client() -> BoxClient:
        config = CCGConfig(
            client_id=os.getenv("BOX_CLIENT_ID"),
            client_secret=os.getenv("BOX_CLIENT_SECRET"),
            enterprise_id=os.getenv("BOX_ENTERPRISE_ID"),
        )
        auth = BoxCCGAuth(config=config)
        return BoxClient(auth=auth)
    ```

    <Tip>
      Client Credentials Grant is recommended for server-to-server automations where no end user is present. For other authentication options, see the <Link href="/guides/authentication">authentication overview</Link>.
    </Tip>

    <Warning>
      A CCG application acts as a separate service account user that does not automatically have access to your content. Invite the service account email (found in the [Developer Console](https://app.box.com/developers/console) under **General Settings**) as a collaborator on the folder that contains your agreement. Without access, API calls return `404 Not found`.
    </Warning>
  </Step>

  <Step title="Define the extraction schema">
    Create a file called `schema.py` and add the following code. The schema describes the agreement using two complex fields:

    * `vendor` is a `struct` field that groups related vendor details into one nested object.
    * `delivery_schedule` is a `table` field that returns one row per milestone.

    Each complex field requires a `fields` array that defines its sub-fields. Sub-fields support scalar types only. Nested `struct` or `table` types are not allowed.

    ```python theme={null}
    from box_sdk_gen import CreateAiExtractStructuredFields

    EXTRACTION_FIELDS = [
        CreateAiExtractStructuredFields(
            key="agreement_effective_date",
            display_name="Effective date",
            type="date",
            prompt="The date the agreement takes effect.",
        ),
        CreateAiExtractStructuredFields(
            key="payment_terms",
            display_name="Payment terms",
            type="string",
            prompt="The payment terms, for example Net 30.",
        ),
        CreateAiExtractStructuredFields(
            key="vendor",
            display_name="Vendor",
            type="struct",
            prompt="The vendor or supplier issuing the agreement.",
            fields=[
                CreateAiExtractStructuredFields(key="legal_name", type="string", display_name="Legal name"),
                CreateAiExtractStructuredFields(key="address", type="string", display_name="Address"),
                CreateAiExtractStructuredFields(key="country", type="string", display_name="Country"),
                CreateAiExtractStructuredFields(key="contact_person", type="string", display_name="Contact person"),
                CreateAiExtractStructuredFields(key="email", type="string", display_name="Email"),
                CreateAiExtractStructuredFields(key="phone", type="string", display_name="Phone"),
            ],
        ),
        CreateAiExtractStructuredFields(
            key="delivery_schedule",
            display_name="Delivery schedule",
            type="table",
            prompt="Each delivery milestone defined in the agreement.",
            fields=[
                CreateAiExtractStructuredFields(key="phase", type="string", display_name="Phase"),
                CreateAiExtractStructuredFields(key="items", type="string", display_name="Items"),
                CreateAiExtractStructuredFields(key="delivery_date", type="date", display_name="Delivery date"),
                CreateAiExtractStructuredFields(key="destination", type="string", display_name="Destination"),
                CreateAiExtractStructuredFields(key="status", type="string", display_name="Status"),
            ],
        ),
    ]
    ```

    <Tip>
      Table extraction is not limited to visually formatted tables. The `table` type extracts repeating data whether it appears as a grid, key-value pairs, a form layout, or plain prose.
    </Tip>
  </Step>

  <Step title="Build the extraction function">
    Create a file called `extract.py` and add the following code. It uses the SDK's `create_ai_extract_structured` method to send the schema to Box AI and specifies the Enhanced Extract Agent, which improves accuracy for nested and repeating fields.

    ```python theme={null}
    from box_sdk_gen import AiItemBase, AiAgentReference, AiAgentReferenceTypeField
    from box_client import get_box_client
    from schema import EXTRACTION_FIELDS

    def extract_agreement(file_id: str) -> dict:
        client = get_box_client()

        response = client.ai.create_ai_extract_structured(
            items=[AiItemBase(id=file_id)],
            fields=EXTRACTION_FIELDS,
            ai_agent=AiAgentReference(
                id="enhanced_extract_agent",
                type=AiAgentReferenceTypeField.AI_AGENT_ID,
            ),
        )

        return response.to_dict()["answer"]
    ```

    <Note>
      The Enhanced Extract Agent is not strictly required, but it improves results for richer schemas and complex document layouts, especially when nested and repeating fields are involved.
    </Note>
  </Step>

  <Step title="Map the structured output">
    Create a file called `app.py` and add the following code. Box AI returns the `vendor` field as a nested object and the `delivery_schedule` field as a list of rows. This script runs the extraction and maps the result into a flat record that is ready for a downstream system.

    ```python theme={null}
    import json
    import os
    from dotenv import load_dotenv
    from extract import extract_agreement

    load_dotenv()

    def to_procurement_record(answer: dict) -> dict:
        vendor = answer.get("vendor", {})
        schedule = answer.get("delivery_schedule", [])

        return {
            "vendor_name": vendor.get("legal_name"),
            "vendor_country": vendor.get("country"),
            "vendor_contact": vendor.get("contact_person"),
            "vendor_email": vendor.get("email"),
            "payment_terms": answer.get("payment_terms"),
            "effective_date": answer.get("agreement_effective_date"),
            "milestones": [
                {
                    "phase": row.get("phase"),
                    "due": row.get("delivery_date"),
                    "destination": row.get("destination"),
                    "status": row.get("status"),
                }
                for row in schedule
            ],
        }

    if __name__ == "__main__":
        file_id = os.getenv("AGREEMENT_FILE_ID")

        answer = extract_agreement(file_id)
        print("Raw extraction:")
        print(json.dumps(answer, indent=2))

        record = to_procurement_record(answer)
        print("\nProcurement record:")
        print(json.dumps(record, indent=2))
    ```

    At this point, your project directory should contain the following files:

    ```
    supplier-extraction/
    ├── .env
    ├── .venv/
    ├── app.py
    ├── box_client.py
    ├── extract.py
    └── schema.py
    ```
  </Step>

  <Step title="Run the extraction">
    Make sure you are in the `supplier-extraction` directory with the virtual environment activated, then run the script:

    ```bash theme={null}
    python3 app.py
    ```

    Box AI returns the `struct` field as a single nested object and the `table` field as a list of objects. Your output looks similar to this:

    ```json theme={null}
    {
      "agreement_effective_date": "2026-06-01",
      "payment_terms": "Net 45",
      "vendor": {
        "legal_name": "Nexus Industrial Solutions Ltd.",
        "address": "47 Canary Wharf, Level 12, London, E14 5AB",
        "country": "United Kingdom",
        "contact_person": "Oliver Hartmann",
        "email": "o.hartmann@nexusindustrial.co.uk",
        "phone": "+44 20 7946 0832"
      },
      "delivery_schedule": [
        {
          "phase": "Phase 1 - Infrastructure",
          "items": "Server Racks (qty 6), UPS (qty 3)",
          "delivery_date": "2026-07-15",
          "destination": "Chicago, IL",
          "status": "Scheduled"
        },
        {
          "phase": "Phase 2 - Networking",
          "items": "48-Port Switches (all), Fibre Cables (all)",
          "delivery_date": "2026-08-01",
          "destination": "Chicago, IL",
          "status": "Scheduled"
        },
        {
          "phase": "Phase 3 - Security",
          "items": "NGFW Cluster (all), Remaining Racks",
          "delivery_date": "2026-08-20",
          "destination": "San Francisco, CA",
          "status": "Pending"
        },
        {
          "phase": "Phase 4 - Services",
          "items": "Installation, Training",
          "delivery_date": "2026-09-01",
          "destination": "San Francisco, CA",
          "status": "Pending"
        }
      ]
    }
    ```

    The script then prints the mapped procurement record, which you can send to your ERP, procurement platform, or project tracker.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="ModuleNotFoundError: No module named '...'">
    Your virtual environment is not activated. Run `source .venv/bin/activate` from the project directory before running any `python3` commands. Each new terminal tab needs its own activation.
  </Accordion>

  <Accordion title="invalid_client: The client credentials are invalid">
    Check your `.env` file:

    * Verify `BOX_CLIENT_ID` and `BOX_CLIENT_SECRET` match the values in Developer Console > Configuration.
    * Confirm `BOX_ENTERPRISE_ID` is your enterprise ID.
    * Ensure your app is authorized in the Developer Console and uses Client Credentials Grant.
  </Accordion>

  <Accordion title="404 Not Found">
    The service account does not have access to the file. Invite the service account email (found in Developer Console > General Settings) as a collaborator on the folder that contains your agreement.
  </Accordion>

  <Accordion title="Sub-field values come back empty or merged">
    Nested `struct` and `table` types are not supported as sub-fields, and a `struct` or `table` field must include a `fields` array. Confirm your sub-fields use only scalar types, and add a `prompt` to the complex field to clarify what to extract.
  </Accordion>
</AccordionGroup>

## Scaling to production

<AccordionGroup>
  <Accordion title="Write results back to Box metadata">
    To make agreements searchable and routable inside Box, write the flattened top-level values back to the file as a metadata instance, then use <Link href="/guides/metadata/queries">metadata queries</Link> to filter by vendor, country, or effective date. See <Link href="/tutorials/invoice-intake">Automate invoice intake with Box AI Extract</Link> for an end-to-end metadata write-back pattern.
  </Accordion>

  <Accordion title="Trigger extraction automatically">
    Instead of running the script manually, register a webhook on your agreements folder so each upload triggers extraction. See <Link href="/guides/webhooks/v2/signatures-v2">Verify webhook signatures</Link> to validate incoming requests in production.
  </Accordion>

  <Accordion title="Tune accuracy for complex layouts">
    Add a field-level `prompt` to guide extraction, and keep the Enhanced Extract Agent for multi-page agreements with dense tables. For consistent schemas across many documents, define the fields in a <Link href="/guides/box-ai/ai-tutorials/extract-metadata-structured#use-metadata-template">metadata template</Link> instead of inline.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Invoice intake automation" href="/tutorials/invoice-intake" icon="file-invoice">
    Watch a folder for new invoices, extract fields, and write them back as searchable metadata.
  </Card>

  <Card title="Extract API reference" href="/reference/post-ai-extract-structured" icon="code">
    See the full API specification for structured extraction.
  </Card>
</CardGroup>

<RelatedLinks title="RELATED GUIDES" />


# Archives resources
Source: https://developer.box.com/reference/v2025.0/archives-resources



A set of endpoints used to manage archives.

## Archive

An archive is a folder dedicated to storing content that is redundant, outdated, or trivial. Content in an archive is not accessible to its owner and collaborators. To use this feature, you must request GCM scope for your Box application.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represents an archive. |
  | `type` | `enum<string>` | Yes | The value is always `archive`. Available options: `archive`. |
  | `name` | `string` | Yes | The name of the archive. The following restrictions to the archive name apply: names containing non-printable ASCII characters, forward and backward slashes (`/`, `\`), names with trailing spaces, and names `.` and `..` are not allowed. |
  | `size` | `integer` | Yes | The size of the archive in bytes. |
  | `description` | `string` | No | The description of the archive. Can be `null`. |
  | `owned_by` | `object` | No | The part of an archive API response that describes the user who owns the archive. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "archive",
    "name": "Archive",
    "size": 123456789,
    "description": "This is an archive for important documents.",
    "owned_by": {
      "id": "12345",
      "type": "user"
    }
  }
  ```
</Accordion>

## Archives

A list of archives.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Archive](#archive) | No | A list in which each entry represents an archive object. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "archive",
        "name": "Archive",
        "size": 123456789,
        "description": "This is an archive for important documents.",
        "owned_by": {
          "id": "12345",
          "type": "user"
        }
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Box Doc Gen resources
Source: https://developer.box.com/reference/v2025.0/docgen-resources



Doc Gen is used to automatically generate documents.

## Box Doc Gen batch (Base)

The basic representation of a Box Doc Gen batch object. A Box Doc Gen batch contains one or more Box Doc Gen jobs.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represents a Box Doc Gen batch. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_batch`. Available options: `docgen_batch`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_batch"
  }
  ```
</Accordion>

## Box Doc Gen job

A standard representation of a Box Doc Gen job.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Doc Gen job. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_job`. Available options: `docgen_job`. |
  | `batch` | [Box Doc Gen batch (Base)](#box-doc-gen-batch-base) | Yes | Box Doc Gen batch that the job belongs to. |
  | `template_file` | `File reference` | Yes | Box Doc Gen template used in the job. |
  | `template_file_version` | `File version (Base)` | Yes | File version of a template. |
  | `output_file` | `File reference` | No | The output file of the job. This property is `null` until the job is completed. Can be `null`. |
  | `output_file_version` | `File version (Base)` | No | File version of the output file. This property is `null` until the job is completed. Can be `null`. |
  | `status` | `enum<string>` | Yes | Status of the job. Available options: `submitted`, `completed`, `failed`, `completed_with_error`, `pending`. |
  | `output_type` | `string` | Yes | Type of the generated file. |
  | `failures` | `object` | No | Errors and warnings that occurred during document generation. Can be `null`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_job",
    "batch": {
      "id": "12345",
      "type": "docgen_batch"
    },
    "template_file": {
      "type": "file",
      "id": "42037322"
    },
    "template_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "output_file": {
      "type": "file",
      "id": "42037322"
    },
    "output_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "status": "completed",
    "output_type": "docx",
    "failures": {
      "errors": [
        "The tag 'customer_name' was not provided in the input data."
      ],
      "warnings": [
        "The tag 'optional_field' was provided but not used in the template."
      ]
    }
  }
  ```
</Accordion>

## Box Doc Gen job (Base)

The basic representation of a Box Doc Gen job.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Doc Gen job. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_job`. Available options: `docgen_job`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_job"
  }
  ```
</Accordion>

## Box Doc Gen job (Full)

A full representation of a Box Doc Gen job.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Doc Gen job. |
  | `type` | `enum<string>` | Yes | The value will always be `docgen_job`. Available options: `docgen_job`. |
  | `batch` | [Box Doc Gen batch (Base)](#box-doc-gen-batch-base) | Yes | Box Doc Gen batch that the job belongs to. |
  | `template_file` | `File reference` | Yes | Box Doc Gen template used in the job. |
  | `template_file_version` | `File version (Base)` | Yes | File version of a template. |
  | `output_file` | `File reference` | No | The output file of the job. This property is `null` until the job is completed. Can be `null`. |
  | `output_file_version` | `File version (Base)` | No | File version of the output file. This property is `null` until the job is completed. Can be `null`. |
  | `status` | `enum<string>` | Yes | Status of the job. Available options: `submitted`, `completed`, `failed`, `completed_with_error`, `pending`. |
  | `output_type` | `string` | Yes | Type of the generated file. |
  | `failures` | `object` | No | Errors and warnings that occurred during document generation. Can be `null`. |
  | `created_at` | `string` | No | Time of job creation. Read-only. |
  | `created_by` | `User (Base)` | Yes | User who created the job. |
  | `enterprise` | `Enterprise reference` | Yes | ID of the enterprise. |
  | `source` | `string` | Yes | Source of the request. Read-only. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "docgen_job",
    "batch": {
      "id": "12345",
      "type": "docgen_batch"
    },
    "template_file": {
      "type": "file",
      "id": "42037322"
    },
    "template_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "output_file": {
      "type": "file",
      "id": "42037322"
    },
    "output_file_version": {
      "id": "12345",
      "type": "file_version"
    },
    "status": "completed",
    "output_type": "docx",
    "failures": {
      "errors": [
        "The tag 'customer_name' was not provided in the input data."
      ],
      "warnings": [
        "The tag 'optional_field' was provided but not used in the template."
      ]
    },
    "created_at": "2022-05-11T10:56:11-07:00",
    "created_by": {
      "id": "11446498",
      "type": "user"
    },
    "enterprise": {
      "id": "1910967",
      "type": "enterprise"
    },
    "source": "api"
  }
  ```
</Accordion>

## Box Doc Gen jobs

A list of Box Doc Gen jobs with a standard set of parameters.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen job](#box-doc-gen-job) | No | List of jobs. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345",
        "type": "docgen_job",
        "batch": {
          "id": "12345",
          "type": "docgen_batch"
        },
        "template_file": {
          "type": "file",
          "id": "42037322"
        },
        "template_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "output_file": {
          "type": "file",
          "id": "42037322"
        },
        "output_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "status": "completed",
        "output_type": "docx",
        "failures": {
          "errors": [
            "The tag 'customer_name' was not provided in the input data."
          ],
          "warnings": [
            "The tag 'optional_field' was provided but not used in the template."
          ]
        }
      }
    ]
  }
  ```
</Accordion>

## Box Doc Gen jobs (Full)

A list of Box Doc Gen jobs with a full set of parameters.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen job (Full)](#box-doc-gen-job-full) | No | List of jobs. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "id": "12345",
        "type": "docgen_job",
        "batch": {
          "id": "12345",
          "type": "docgen_batch"
        },
        "template_file": {
          "type": "file",
          "id": "42037322"
        },
        "template_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "output_file": {
          "type": "file",
          "id": "42037322"
        },
        "output_file_version": {
          "id": "12345",
          "type": "file_version"
        },
        "status": "completed",
        "output_type": "docx",
        "failures": {
          "errors": [
            "The tag 'customer_name' was not provided in the input data."
          ],
          "warnings": [
            "The tag 'optional_field' was provided but not used in the template."
          ]
        },
        "created_at": "2022-05-11T10:56:11-07:00",
        "created_by": {
          "id": "11446498",
          "type": "user"
        },
        "enterprise": {
          "id": "1910967",
          "type": "enterprise"
        },
        "source": "api"
      }
    ]
  }
  ```
</Accordion>


# Box Doc Gen templates resources
Source: https://developer.box.com/reference/v2025.0/docgen-template-resources



Doc Gen templates are used as input to generate documents.

## Box Doc Gen tags

A list of Box Doc Gen tags.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen template tag](#box-doc-gen-template-tag) | No | List of tags. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "tag_content": "{{item.name}}",
        "tag_type": "text",
        "json_paths": [
          "products",
          "products.name"
        ]
      }
    ]
  }
  ```
</Accordion>

## Box Doc Gen tags processing message

A message informing the user that document tags are still being processed.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `message` | `string` | Yes | A message informing the user that document tags are still being processed. Read-only. |

  ```json Example theme={null}
  {
    "message": "Processing tags for this file."
  }
  ```
</Accordion>

## Box Doc Gen template

A Box Doc Gen template object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `file` | `File reference` | No | Enable the file to generate a document from. |
  | `file_name` | `string` | No | The name of the template. Can be `null`. |

  ```json Example theme={null}
  {
    "file": {
      "type": "file",
      "id": "42037322"
    },
    "file_name": "Official contract"
  }
  ```
</Accordion>

## Box Doc Gen template tag

A Box Doc Gen template tag object.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `tag_content` | `string` | Yes | The content of the tag. Read-only. |
  | `tag_type` | `enum<string>` | Yes | Type of the tag. Available options: `text`, `arithmetic`, `conditional`, `for-loop`, `table-loop`, `image`. Read-only. |
  | `json_paths` | array of `string` | Yes | List of the paths. Read-only. |

  ```json Example theme={null}
  {
    "tag_content": "{{item.name}}",
    "tag_type": "text",
    "json_paths": [
      "products",
      "products.name"
    ]
  }
  ```
</Accordion>

## Box Doc Gen templates

List of Box Doc Gen templates.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |
  | `prev_marker` | `string` | No | The marker for the start of the previous page of results. Can be `null`. |
  | `entries` | array of [Box Doc Gen template](#box-doc-gen-template) | No | A list of templates. |

  ```json Example theme={null}
  {
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii",
    "prev_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVih",
    "entries": [
      {
        "file": {
          "type": "file",
          "id": "42037322"
        },
        "file_name": "Official contract"
      }
    ]
  }
  ```
</Accordion>


# Enterprise Configurations resources
Source: https://developer.box.com/reference/v2025.0/enterprise-configurations-resources



Enterprise configurations admins interact with to drive Box product behavior.

## Enterprise configuration

The enterprise configuration for a given enterprise.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | No | The identifier of the enterprise configuration which is the ID of the enterprise. |
  | `type` | `enum<string>` | No | The value will always be `enterprise_configuration`. Available options: `enterprise_configuration`. |
  | `security` | [Enterprise configuration security](#enterprise-configuration-security) | No | The enterprise configurations for the security category. Can be `null`. |
  | `content_and_sharing` | [Enterprise configuration content and sharing](#enterprise-configuration-content-and-sharing) | No | The enterprise configurations for the content and sharing category. Can be `null`. |
  | `user_settings` | [Enterprise configuration user settings](#enterprise-configuration-user-settings) | No | The enterprise configurations for the user settings category. Can be `null`. |
  | `shield` | [Enterprise configuration shield](#enterprise-configuration-shield) | No | The enterprise configurations for the shield category. If shield is turned off for given enterprise, the response will be 404. Can be `null`. |

  ```json Example theme={null}
  {
    "id": "11446498",
    "type": "enterprise_configuration",
    "security": {
      "is_managed_user_signup_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_signup_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_signup_corporate_email_enabled": {
        "is_used": true,
        "value": true
      },
      "is_new_user_notification_daily_digest_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_email_change_disabled": {
        "is_used": true,
        "value": true
      },
      "is_multi_factor_auth_required": {
        "is_used": true,
        "value": true
      },
      "is_weak_password_prevention_enabled": {
        "is_used": true,
        "value": true
      },
      "is_password_leak_detection_enabled": {
        "is_used": true,
        "value": true
      },
      "last_password_reset_at": {
        "is_used": true,
        "value": "2012-12-12T10:53:43-08:00"
      },
      "is_password_request_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "is_password_change_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "is_strong_password_for_ext_collab_enabled": {
        "is_used": true,
        "value": true
      },
      "is_managed_user_migration_disabled": {
        "is_used": true,
        "value": true
      },
      "join_link": {
        "is_used": true,
        "value": "value of configuration"
      },
      "join_url": {
        "is_used": true,
        "value": "value of configuration"
      },
      "failed_login_attempts_to_trigger_admin_notification": {
        "is_used": true,
        "value": 1234
      },
      "password_min_length": {
        "is_used": true,
        "value": 1234
      },
      "password_min_uppercase_characters": {
        "is_used": true,
        "value": 1234
      },
      "password_min_numeric_characters": {
        "is_used": true,
        "value": 1234
      },
      "password_min_special_characters": {
        "is_used": true,
        "value": 1234
      },
      "password_reset_frequency": {
        "is_used": true,
        "value": "value of configuration"
      },
      "previous_password_reuse_limit": {
        "is_used": true,
        "value": "value of configuration"
      },
      "session_duration": {
        "is_used": true,
        "value": "value of configuration"
      },
      "external_collab_multi_factor_auth_settings": {
        "is_used": true,
        "value": {
          "denylist_domains": [
            "example.com"
          ],
          "denylist_emails": [
            "spam@example.com"
          ],
          "allowlist_domains": [
            "example.com"
          ],
          "allowlist_emails": [
            "mail@example.com"
          ],
          "state": "enabled",
          "scheduled_status": "inprogress",
          "scheduled_at": "2012-12-12T10:53:43-08:00",
          "factor_type_settings": "totp"
        }
      },
      "keysafe": {
        "is_used": true,
        "value": {
          "keysafe_enabled": true,
          "cloud_provider": "",
          "key_id": "1234",
          "account_id": "1234",
          "location_id": "1234",
          "project_id": "1234",
          "keyring_id": "1234"
        }
      },
      "is_custom_session_duration_enabled": {
        "is_used": true,
        "value": true
      },
      "custom_session_duration_value": {
        "is_used": true,
        "value": "value of configuration"
      },
      "custom_session_duration_groups": {
        "is_used": true,
        "value": [
          {
            "id": "1234",
            "name": "Group Name"
          }
        ]
      },
      "multi_factor_auth_type": {
        "is_used": true,
        "value": "value of configuration"
      },
      "enforced_mfa_frequency": {
        "is_used": true,
        "value": {
          "days": 30,
          "hours": 24
        }
      }
    },
    "content_and_sharing": {
      "enterprise_feature_settings": [
        {
          "is_used": true,
          "value": {
            "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
            "feature": {
              "id": "canvas"
            },
            "state": "enabled",
            "can_configure": true,
            "is_configured": true,
            "allowlist": [
              {
                "type": "user",
                "id": "12345"
              }
            ],
            "denylist": [
              {
                "type": "user",
                "id": "12345"
              }
            ]
          }
        }
      ],
      "sharing_item_type": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_company_definition": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_access": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_default_access": {
        "is_used": true,
        "value": "value of configuration"
      },
      "shared_link_default_permissions_selected": {
        "is_used": true,
        "value": {
          "shared_links_option": "settings_shared_link_preview",
          "default_shared_link_type": "settings_default_shared_link_preview",
          "notes_shared_link_option": "settings_notes_option_to_edit",
          "default_notes_shared_link_type": "settings_default_notes_shared_link_to_edit"
        }
      },
      "is_open_custom_urls_disabled": {
        "is_used": true,
        "value": true
      },
      "is_custom_domain_hidden_in_shared_link": {
        "is_used": true,
        "value": true
      },
      "collaboration_permissions": {
        "is_used": true,
        "value": {
          "is_co_owner_role_enabled": true,
          "is_editor_role_enabled": true,
          "is_previewer_role_enabled": true,
          "is_previewer_uploader_role_enabled": true,
          "is_uploader_role_enabled": true,
          "is_viewer_role_enabled": true,
          "is_viewer_uploader_role_enabled": true
        }
      },
      "default_collaboration_role": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_invite_privilege_restricted": {
        "is_used": true,
        "value": true
      },
      "collaboration_restrictions": {
        "is_used": true,
        "value": [
          "internal"
        ]
      },
      "is_collaborator_invite_links_disabled": {
        "is_used": true,
        "value": true
      },
      "is_invite_group_collaborator_disabled": {
        "is_used": true,
        "value": true
      },
      "is_ownership_transfer_restricted": {
        "is_used": true,
        "value": true
      },
      "external_collaboration_status": {
        "is_used": true,
        "value": "enable_external_collaboration"
      },
      "external_collaboration_allowlist_users": {
        "is_used": true,
        "value": [
          {
            "id": 1234,
            "name": "John Doe",
            "email": "johndoe@box.com"
          }
        ]
      },
      "is_watermarking_enterprise_feature_enabled": {
        "is_used": true,
        "value": true
      },
      "is_root_content_creation_restricted": {
        "is_used": true,
        "value": true
      },
      "is_tag_creation_restricted": {
        "is_used": true,
        "value": true
      },
      "tag_creation_restriction": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_email_uploads_enabled": {
        "is_used": true,
        "value": true
      },
      "is_custom_settings_enabled": {
        "is_used": true,
        "value": true
      },
      "is_forms_login_required": {
        "is_used": true,
        "value": true
      },
      "is_forms_branding_default_enabled": {
        "is_used": true,
        "value": true
      },
      "is_cc_free_trial_active": {
        "is_used": true,
        "value": true
      },
      "is_file_request_editors_allowed": {
        "is_used": true,
        "value": true
      },
      "is_file_request_branding_default_enabled": {
        "is_used": true,
        "value": true
      },
      "is_file_request_login_required": {
        "is_used": true,
        "value": true
      },
      "is_shared_links_expiration_enabled": {
        "is_used": true,
        "value": true
      },
      "shared_links_expiration_days": {
        "is_used": true,
        "value": 1234
      },
      "is_public_shared_links_expiration_enabled": {
        "is_used": true,
        "value": true
      },
      "public_shared_links_expiration_days": {
        "is_used": true,
        "value": 1234
      },
      "shared_expiration_target": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_shared_links_expiration_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "shared_links_expiration_notification_days": {
        "is_used": true,
        "value": 1234
      },
      "is_shared_links_expiration_notification_prevented": {
        "is_used": true,
        "value": true
      },
      "is_auto_delete_enabled": {
        "is_used": true,
        "value": true
      },
      "auto_delete_days": {
        "is_used": true,
        "value": 1234
      },
      "is_auto_delete_expiration_modification_prevented": {
        "is_used": true,
        "value": true
      },
      "auto_delete_target": {
        "is_used": true,
        "value": "value of configuration"
      },
      "is_collaboration_expiration_enabled": {
        "is_used": true,
        "value": true
      },
      "collaboration_expiration_days": {
        "is_used": true,
        "value": 1234
      },
      "is_collaboration_expiration_modification_prevented": {
        "is_used": true,
        "value": true
      },
      "is_collaboration_expiration_notification_enabled": {
        "is_used": true,
        "value": true
      },
      "collaboration_expiration_target": {
        "is_used": true,
        "value": "value of configuration"
      },
      "trash_auto_clear_time": {
        "is_used": true,
        "value": 1234
      },
      "permanent_deletion_access": {
        "is_used": true,
        "value": "value of configuration"
      },
      "permanent_deletion_allowlist_users": {
        "is_used": true,
        "value": [
          {
            "id": 1234,
            "name": "John Doe",
            "email": "johndoe@box.com"
          }
        ]
      }
    },
    "user_settings": {
      "enterprise_feature_settings": [
        {
          "is_used": true,
          "value": {
            "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
            "feature": {
              "id": "canvas"
            },
            "state": "enabled",
            "can_configure": true,
            "is_configured": true,
            "allowlist": [
              {
                "type": "user",
                "id": "12345"
              }
            ],
            "denylist": [
              {
                "type": "user",
                "id": "12345"
              }
            ]
          }
        }
      ],
      "user_invites_expiration_time_frame": {
        "is_used": true,
        "value": "7 days"
      },
      "is_username_change_restricted": {
        "is_used": true,
        "value": true
      },
      "is_box_sync_restricted_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_view_all_users_enabled_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_device_limit_exemption_enabled_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_external_collaboration_restricted_for_new_users": {
        "is_used": true,
        "value": true
      },
      "is_unlimited_storage_enabled_for_new_users": {
        "is_used": true,
        "value": true
      },
      "new_user_default_storage_limit": {
        "is_used": true,
        "value": 1234
      },
      "new_user_default_timezone": {
        "is_used": true,
        "value": "GMT-05:00 America\\/Chicago CDT"
      },
      "new_user_default_language": {
        "is_used": true,
        "value": "English (US)"
      },
      "is_enterprise_sso_required": {
        "is_used": true,
        "value": true
      },
      "is_enterprise_sso_in_testing": {
        "is_used": true,
        "value": true
      },
      "is_sso_auto_add_groups_enabled": {
        "is_used": true,
        "value": true
      },
      "is_sso_auto_add_user_to_groups_enabled": {
        "is_used": true,
        "value": true
      },
      "is_sso_auto_remove_user_from_groups_enabled": {
        "is_used": true,
        "value": true
      },
      "user_tracking_codes": {
        "is_used": true,
        "value": [
          {
            "id": 1234,
            "name": "Employee ID"
          }
        ]
      },
      "number_of_user_tracking_codes_remaining": {
        "is_used": true,
        "value": 1234
      },
      "is_instant_login_restricted": {
        "is_used": true,
        "value": true
      }
    },
    "shield": {
      "shield_rules": [
        {
          "id": "1234567890",
          "type": "shield_rule",
          "rule_category": "Malicious Content",
          "name": "Block malicious files",
          "description": "Blocks files identified as malicious content",
          "priority": "high",
          "created_at": "2012-12-12T10:53:43-08:00",
          "modified_at": "2012-12-12T10:53:43-08:00"
        }
      ]
    }
  }
  ```
</Accordion>

## Enterprise configuration content and sharing

The enterprise configuration for the content and sharing category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `enterprise_feature_settings` | array of `Enterprise feature settings item` | No | |
  | `sharing_item_type` | `Enterprise configuration item with string value` | No | The selected option for the type of items that sharing is enable for. |
  | `shared_link_company_definition` | `Enterprise configuration item with string value` | No | The definition of the company for shared links (such as `enterprise_id`, `users_with_email_domain`). |
  | `shared_link_access` | `Enterprise configuration item with string value` | No | The selected option for who has access to shared links. |
  | `shared_link_default_access` | `Enterprise configuration item with string value` | No | The selected option for the access level of shared links. |
  | `shared_link_default_permissions_selected` | `Enterprise configuration item` | No | The permissions selected for shared links for each type. |
  | `is_open_custom_urls_disabled` | `Enterprise configuration item with boolean value` | No | Disables custom shared link URLs for public access. |
  | `is_custom_domain_hidden_in_shared_link` | `Enterprise configuration item with boolean value` | No | Hides the custom domain in shared links. |
  | `collaboration_permissions` | `Enterprise configuration item` | No | |
  | `default_collaboration_role` | `Enterprise configuration item with string value` | No | The current default collaboration role. |
  | `is_invite_privilege_restricted` | `Enterprise configuration item with boolean value` | No | Restrict invites to only admin, folder owners, and co-owners. |
  | `collaboration_restrictions` | `Enterprise configuration item` | No | The collaboration restrictions for the enterprise. |
  | `is_collaborator_invite_links_disabled` | `Enterprise configuration item with boolean value` | No | Disables users to invite collaborators using invite links. |
  | `is_invite_group_collaborator_disabled` | `Enterprise configuration item with boolean value` | No | Disables users to invite group collaborators. |
  | `is_ownership_transfer_restricted` | `Enterprise configuration item with boolean value` | No | Prevents ownership transfer to external users. |
  | `external_collaboration_status` | `Enterprise configuration item` | No | The external collaboration status. Possible values: `enable_external_collaboration`, `limit_collaboration_to_allowlisted_domains`, `limit_collaboration_to_users_within_enterprise`. |
  | `external_collaboration_allowlist_users` | `Enterprise configuration item` | No | The external collaboration allowlist users. |
  | `is_watermarking_enterprise_feature_enabled` | `Enterprise configuration item with boolean value` | No | Enables watermarking enterprise feature. |
  | `is_root_content_creation_restricted` | `Enterprise configuration item with boolean value` | No | Only admins can create and delete first-level folders, files, and bookmarks. |
  | `is_tag_creation_restricted` | `Enterprise configuration item with boolean value` | No | Only selected users can create tags. |
  | `tag_creation_restriction` | `Enterprise configuration item with string value` | No | The selected option for tag creation restriction. |
  | `is_email_uploads_enabled` | `Enterprise configuration item with boolean value` | No | Enables email uploads. |
  | `is_custom_settings_enabled` | `Enterprise configuration item with boolean value` | No | Enables custom settings. |
  | `is_forms_login_required` | `Enterprise configuration item with boolean value` | No | Require uploaders to log in with a Box account for Forms. |
  | `is_forms_branding_default_enabled` | `Enterprise configuration item with boolean value` | No | Company brand color and logo defaults to Logo for use on Brand Color for Forms. |
  | `is_cc_free_trial_active` | `Enterprise configuration item with boolean value` | No | Indicates if the enterprise is on a free trial. |
  | `is_file_request_editors_allowed` | `Enterprise configuration item with boolean value` | No | Indicates if editors are allowed for file requests feature. |
  | `is_file_request_branding_default_enabled` | `Enterprise configuration item with boolean value` | No | Company brand color and logo defaults to Logo for use on Brand Color for File Requests. |
  | `is_file_request_login_required` | `Enterprise configuration item with boolean value` | No | Require uploaders to log in with a Box account for File Requests. |
  | `is_shared_links_expiration_enabled` | `Enterprise configuration item with boolean value` | No | Enables shared links expiration. |
  | `shared_links_expiration_days` | `Enterprise configuration item with integer value` | No | The expiration time for shared links. |
  | `is_public_shared_links_expiration_enabled` | `Enterprise configuration item with boolean value` | No | Enables public shared links expiration. |
  | `public_shared_links_expiration_days` | `Enterprise configuration item with integer value` | No | The expiration time for public shared links. |
  | `shared_expiration_target` | `Enterprise configuration item with string value` | No | The selected option of types for applying shared link expiration. |
  | `is_shared_links_expiration_notification_enabled` | `Enterprise configuration item with boolean value` | No | Enables shared links expiration notification. |
  | `shared_links_expiration_notification_days` | `Enterprise configuration item with integer value` | No | The number of days before expiration to notify users. |
  | `is_shared_links_expiration_notification_prevented` | `Enterprise configuration item with boolean value` | No | Prevents users from disabling shared links expiration notification. |
  | `is_auto_delete_enabled` | `Enterprise configuration item with boolean value` | No | Enables auto delete. |
  | `auto_delete_days` | `Enterprise configuration item with integer value` | No | The number of days before auto delete. |
  | `is_auto_delete_expiration_modification_prevented` | `Enterprise configuration item with boolean value` | No | Prevents users from modifying auto delete expiration. |
  | `auto_delete_target` | `Enterprise configuration item with string value` | No | The selected option of types for applying auto delete. |
  | `is_collaboration_expiration_enabled` | `Enterprise configuration item with boolean value` | No | Enables collaboration expiration. |
  | `collaboration_expiration_days` | `Enterprise configuration item with integer value` | No | The number of days before collaboration expiration. |
  | `is_collaboration_expiration_modification_prevented` | `Enterprise configuration item with boolean value` | No | Prevents users from modifying collaboration expiration. |
  | `is_collaboration_expiration_notification_enabled` | `Enterprise configuration item with boolean value` | No | Enables collaboration expiration notification. |
  | `collaboration_expiration_target` | `Enterprise configuration item with string value` | No | The selected option of types for applying collaboration expiration. |
  | `trash_auto_clear_time` | `Enterprise configuration item with integer value` | No | The time before items are permanently deleted from the trash in seconds. |
  | `permanent_deletion_access` | `Enterprise configuration item with string value` | No | The selected option for who can delete items from the trash. |
  | `permanent_deletion_allowlist_users` | `Enterprise configuration item` | No | The allowlist users for permanently deleting items from the trash. |

  ```json Example theme={null}
  {
    "enterprise_feature_settings": [
      {
        "is_used": true,
        "value": {
          "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
          "feature": {
            "id": "canvas"
          },
          "state": "enabled",
          "can_configure": true,
          "is_configured": true,
          "allowlist": [
            {
              "type": "user",
              "id": "12345"
            }
          ],
          "denylist": [
            {
              "type": "user",
              "id": "12345"
            }
          ]
        }
      }
    ],
    "sharing_item_type": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_company_definition": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_access": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_default_access": {
      "is_used": true,
      "value": "value of configuration"
    },
    "shared_link_default_permissions_selected": {
      "is_used": true,
      "value": {
        "shared_links_option": "settings_shared_link_preview",
        "default_shared_link_type": "settings_default_shared_link_preview",
        "notes_shared_link_option": "settings_notes_option_to_edit",
        "default_notes_shared_link_type": "settings_default_notes_shared_link_to_edit"
      }
    },
    "is_open_custom_urls_disabled": {
      "is_used": true,
      "value": true
    },
    "is_custom_domain_hidden_in_shared_link": {
      "is_used": true,
      "value": true
    },
    "collaboration_permissions": {
      "is_used": true,
      "value": {
        "is_co_owner_role_enabled": true,
        "is_editor_role_enabled": true,
        "is_previewer_role_enabled": true,
        "is_previewer_uploader_role_enabled": true,
        "is_uploader_role_enabled": true,
        "is_viewer_role_enabled": true,
        "is_viewer_uploader_role_enabled": true
      }
    },
    "default_collaboration_role": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_invite_privilege_restricted": {
      "is_used": true,
      "value": true
    },
    "collaboration_restrictions": {
      "is_used": true,
      "value": [
        "internal"
      ]
    },
    "is_collaborator_invite_links_disabled": {
      "is_used": true,
      "value": true
    },
    "is_invite_group_collaborator_disabled": {
      "is_used": true,
      "value": true
    },
    "is_ownership_transfer_restricted": {
      "is_used": true,
      "value": true
    },
    "external_collaboration_status": {
      "is_used": true,
      "value": "enable_external_collaboration"
    },
    "external_collaboration_allowlist_users": {
      "is_used": true,
      "value": [
        {
          "id": 1234,
          "name": "John Doe",
          "email": "johndoe@box.com"
        }
      ]
    },
    "is_watermarking_enterprise_feature_enabled": {
      "is_used": true,
      "value": true
    },
    "is_root_content_creation_restricted": {
      "is_used": true,
      "value": true
    },
    "is_tag_creation_restricted": {
      "is_used": true,
      "value": true
    },
    "tag_creation_restriction": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_email_uploads_enabled": {
      "is_used": true,
      "value": true
    },
    "is_custom_settings_enabled": {
      "is_used": true,
      "value": true
    },
    "is_forms_login_required": {
      "is_used": true,
      "value": true
    },
    "is_forms_branding_default_enabled": {
      "is_used": true,
      "value": true
    },
    "is_cc_free_trial_active": {
      "is_used": true,
      "value": true
    },
    "is_file_request_editors_allowed": {
      "is_used": true,
      "value": true
    },
    "is_file_request_branding_default_enabled": {
      "is_used": true,
      "value": true
    },
    "is_file_request_login_required": {
      "is_used": true,
      "value": true
    },
    "is_shared_links_expiration_enabled": {
      "is_used": true,
      "value": true
    },
    "shared_links_expiration_days": {
      "is_used": true,
      "value": 1234
    },
    "is_public_shared_links_expiration_enabled": {
      "is_used": true,
      "value": true
    },
    "public_shared_links_expiration_days": {
      "is_used": true,
      "value": 1234
    },
    "shared_expiration_target": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_shared_links_expiration_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "shared_links_expiration_notification_days": {
      "is_used": true,
      "value": 1234
    },
    "is_shared_links_expiration_notification_prevented": {
      "is_used": true,
      "value": true
    },
    "is_auto_delete_enabled": {
      "is_used": true,
      "value": true
    },
    "auto_delete_days": {
      "is_used": true,
      "value": 1234
    },
    "is_auto_delete_expiration_modification_prevented": {
      "is_used": true,
      "value": true
    },
    "auto_delete_target": {
      "is_used": true,
      "value": "value of configuration"
    },
    "is_collaboration_expiration_enabled": {
      "is_used": true,
      "value": true
    },
    "collaboration_expiration_days": {
      "is_used": true,
      "value": 1234
    },
    "is_collaboration_expiration_modification_prevented": {
      "is_used": true,
      "value": true
    },
    "is_collaboration_expiration_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "collaboration_expiration_target": {
      "is_used": true,
      "value": "value of configuration"
    },
    "trash_auto_clear_time": {
      "is_used": true,
      "value": 1234
    },
    "permanent_deletion_access": {
      "is_used": true,
      "value": "value of configuration"
    },
    "permanent_deletion_allowlist_users": {
      "is_used": true,
      "value": [
        {
          "id": 1234,
          "name": "John Doe",
          "email": "johndoe@box.com"
        }
      ]
    }
  }
  ```
</Accordion>

## Enterprise configuration security

The enterprise configuration for the security category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `is_managed_user_signup_enabled` | `Enterprise configuration item with boolean value` | No | Determines if users are allowed to sign up on their own. |
  | `is_managed_user_signup_notification_enabled` | `Enterprise configuration item with boolean value` | No | Determines if users must sign up with your corporate email. |
  | `is_managed_user_signup_corporate_email_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, admin are emailed when new users are added. |
  | `is_new_user_notification_daily_digest_enabled` | `Enterprise configuration item with boolean value` | No | Depends on `is_managed_user_signup_corporate_email_enabled`. A true value represents `In daily summary emails`. A false value represents `Immediately`. |
  | `is_managed_user_email_change_disabled` | `Enterprise configuration item with boolean value` | No | When enabled, prevents users from changing their primary email address. |
  | `is_multi_factor_auth_required` | `Enterprise configuration item with boolean value` | No | Determines if multi-factor authentication is required for all managed users. |
  | `is_weak_password_prevention_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, prevents common words / email address to be used in a password. |
  | `is_password_leak_detection_enabled` | `Enterprise configuration item with boolean value` | No | Enables exposed password detection. |
  | `last_password_reset_at` | `Enterprise configuration item` | No | |
  | `is_password_request_notification_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, admins are notified when users request a forget password email. |
  | `is_password_change_notification_enabled` | `Enterprise configuration item with boolean value` | No | When enabled, admins are notified when users change passwords in Settings. |
  | `is_strong_password_for_ext_collab_enabled` | `Enterprise configuration item with boolean value` | No | Requires strong passwords for External Collaborators. |
  | `is_managed_user_migration_disabled` | `Enterprise configuration item with boolean value` | No | Disables users from being migrated in or out of the enterprise. |
  | `join_link` | `Enterprise configuration item with string value` | No | Join url for self sign up. Depends on `is_managed_user_signup_enabled`. Applies if `join_url` is not used. |
  | `join_url` | `Enterprise configuration item with string value` | No | Join url for self sign up. Depends on `is_managed_user_signup_enabled`. Applies if `join_link` is not used. |
  | `failed_login_attempts_to_trigger_admin_notification` | `Enterprise configuration item with integer value` | No | Number of failed login attempts before the primary admin is notified. |
  | `password_min_length` | `Enterprise configuration item with integer value` | No | Minimum number of characters required for passwords. |
  | `password_min_uppercase_characters` | `Enterprise configuration item with integer value` | No | Minimum number of upper case characters required in passwords. |
  | `password_min_numeric_characters` | `Enterprise configuration item with integer value` | No | Minimum number of numbers required in passwords. |
  | `password_min_special_characters` | `Enterprise configuration item with integer value` | No | Minimum number of symbols required in passwords. |
  | `password_reset_frequency` | `Enterprise configuration item with string value` | No | Determines if users must reset their passwords every specified time period. |
  | `previous_password_reuse_limit` | `Enterprise configuration item with string value` | No | Number of previous passwords users are prevented from using. |
  | `session_duration` | `Enterprise configuration item with string value` | No | Value indicating time from the last activity a user can remain logged in without activity before being logged out. |
  | `external_collab_multi_factor_auth_settings` | `Enterprise configuration item` | No | External Collaborators multi-factor authentication settings. |
  | `keysafe` | `Enterprise configuration item` | No | |
  | `is_custom_session_duration_enabled` | `Enterprise configuration item with boolean value` | No | Enables custom session duration for select users. |
  | `custom_session_duration_value` | `Enterprise configuration item with string value` | No | Value indicating duration users from specified groups can remain logged in without activity before being logged out. |
  | `custom_session_duration_groups` | `Enterprise configuration item` | No | Groups for custom session duration. |
  | `multi_factor_auth_type` | `Enterprise configuration item with string value` | No | Managed Users multi-factor authentication requirement method type. |
  | `enforced_mfa_frequency` | `Enterprise configuration item` | No | Managed Users multi-factor authentication frequency. The default authentication frequency is set to 30 days, with authentication time calculated from the most recent successful MFA login. |

  ```json Example theme={null}
  {
    "is_managed_user_signup_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_signup_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_signup_corporate_email_enabled": {
      "is_used": true,
      "value": true
    },
    "is_new_user_notification_daily_digest_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_email_change_disabled": {
      "is_used": true,
      "value": true
    },
    "is_multi_factor_auth_required": {
      "is_used": true,
      "value": true
    },
    "is_weak_password_prevention_enabled": {
      "is_used": true,
      "value": true
    },
    "is_password_leak_detection_enabled": {
      "is_used": true,
      "value": true
    },
    "last_password_reset_at": {
      "is_used": true,
      "value": "2012-12-12T10:53:43-08:00"
    },
    "is_password_request_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "is_password_change_notification_enabled": {
      "is_used": true,
      "value": true
    },
    "is_strong_password_for_ext_collab_enabled": {
      "is_used": true,
      "value": true
    },
    "is_managed_user_migration_disabled": {
      "is_used": true,
      "value": true
    },
    "join_link": {
      "is_used": true,
      "value": "value of configuration"
    },
    "join_url": {
      "is_used": true,
      "value": "value of configuration"
    },
    "failed_login_attempts_to_trigger_admin_notification": {
      "is_used": true,
      "value": 1234
    },
    "password_min_length": {
      "is_used": true,
      "value": 1234
    },
    "password_min_uppercase_characters": {
      "is_used": true,
      "value": 1234
    },
    "password_min_numeric_characters": {
      "is_used": true,
      "value": 1234
    },
    "password_min_special_characters": {
      "is_used": true,
      "value": 1234
    },
    "password_reset_frequency": {
      "is_used": true,
      "value": "value of configuration"
    },
    "previous_password_reuse_limit": {
      "is_used": true,
      "value": "value of configuration"
    },
    "session_duration": {
      "is_used": true,
      "value": "value of configuration"
    },
    "external_collab_multi_factor_auth_settings": {
      "is_used": true,
      "value": {
        "denylist_domains": [
          "example.com"
        ],
        "denylist_emails": [
          "spam@example.com"
        ],
        "allowlist_domains": [
          "example.com"
        ],
        "allowlist_emails": [
          "mail@example.com"
        ],
        "state": "enabled",
        "scheduled_status": "inprogress",
        "scheduled_at": "2012-12-12T10:53:43-08:00",
        "factor_type_settings": "totp"
      }
    },
    "keysafe": {
      "is_used": true,
      "value": {
        "keysafe_enabled": true,
        "cloud_provider": "",
        "key_id": "1234",
        "account_id": "1234",
        "location_id": "1234",
        "project_id": "1234",
        "keyring_id": "1234"
      }
    },
    "is_custom_session_duration_enabled": {
      "is_used": true,
      "value": true
    },
    "custom_session_duration_value": {
      "is_used": true,
      "value": "value of configuration"
    },
    "custom_session_duration_groups": {
      "is_used": true,
      "value": [
        {
          "id": "1234",
          "name": "Group Name"
        }
      ]
    },
    "multi_factor_auth_type": {
      "is_used": true,
      "value": "value of configuration"
    },
    "enforced_mfa_frequency": {
      "is_used": true,
      "value": {
        "days": 30,
        "hours": 24
      }
    }
  }
  ```
</Accordion>

## Enterprise configuration shield

The enterprise configuration for the shield category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `shield_rules` | array of `Shield rule item` | No | The shield rules configuration for the enterprise. |

  ```json Example theme={null}
  {
    "shield_rules": [
      {
        "id": "1234567890",
        "type": "shield_rule",
        "rule_category": "Malicious Content",
        "name": "Block malicious files",
        "description": "Blocks files identified as malicious content",
        "priority": "high",
        "created_at": "2012-12-12T10:53:43-08:00",
        "modified_at": "2012-12-12T10:53:43-08:00"
      }
    ]
  }
  ```
</Accordion>

## Enterprise configuration user settings

The enterprise configuration for the user settings category.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `enterprise_feature_settings` | array of `Enterprise feature settings item` | No | |
  | `user_invites_expiration_time_frame` | `Enterprise configuration item with string value` | No | Determines the time frame for any unaccepted invitation to your Box enterprise account to expire. |
  | `is_username_change_restricted` | `Enterprise configuration item with boolean value` | No | Determines if users are restricted from changing their username in Account Settings. |
  | `is_box_sync_restricted_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if Box Sync is restricted for new users. |
  | `is_view_all_users_enabled_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users can see all managed users in their contacts when inviting collaborators. |
  | `is_device_limit_exemption_enabled_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users are exempt from the maximum number of devices specified in the Device Protection settings. |
  | `is_external_collaboration_restricted_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users will not be allowed to create folders that can have external collaborators. |
  | `is_unlimited_storage_enabled_for_new_users` | `Enterprise configuration item with boolean value` | No | Determines if new users are given unlimited storage. |
  | `new_user_default_storage_limit` | `Enterprise configuration item with integer value` | No | Determines the default storage limit for new users. Does not apply if `is_unlimited_storage_enabled_for_new_users` is true. |
  | `new_user_default_timezone` | `Enterprise configuration item with string value` | No | Determines the default timezone for new users. |
  | `new_user_default_language` | `Enterprise configuration item with string value` | No | Determines the default language for new users. |
  | `is_enterprise_sso_required` | `Enterprise configuration item with boolean value` | No | Value indicating if SSO is required for all users. |
  | `is_enterprise_sso_in_testing` | `Enterprise configuration item with boolean value` | No | Value indicating if SSO is in testing mode for all users. |
  | `is_sso_auto_add_groups_enabled` | `Enterprise configuration item with boolean value` | No | Determines if any new groups received for a user upon login through SSO but not present in the enterprise will be auto added to the enterprise. |
  | `is_sso_auto_add_user_to_groups_enabled` | `Enterprise configuration item with boolean value` | No | Determines if a user will be added to enterprise groups received upon user login through SSO. |
  | `is_sso_auto_remove_user_from_groups_enabled` | `Enterprise configuration item with boolean value` | No | Determines if a user will be removed from enterprise groups upon user login through SSO. |
  | `user_tracking_codes` | `Enterprise configuration item` | No | Properties that are assigned as additional values to users, like employee ID or region. |
  | `number_of_user_tracking_codes_remaining` | `Enterprise configuration item with integer value` | No | The remaining number of `user_tracking_codes` that can be created. |
  | `is_instant_login_restricted` | `Enterprise configuration item with boolean value` | No | Determines if users are restricted from granting (limited) access for Box Support for troubleshooting. |

  ```json Example theme={null}
  {
    "enterprise_feature_settings": [
      {
        "is_used": true,
        "value": {
          "id": "eyJlbnRlcnByaXNlSWQiOiIxMTExNDQyNzY3IiwiZmVhdHVyZUlkIjoiY2FudmFzIn0=",
          "feature": {
            "id": "canvas"
          },
          "state": "enabled",
          "can_configure": true,
          "is_configured": true,
          "allowlist": [
            {
              "type": "user",
              "id": "12345"
            }
          ],
          "denylist": [
            {
              "type": "user",
              "id": "12345"
            }
          ]
        }
      }
    ],
    "user_invites_expiration_time_frame": {
      "is_used": true,
      "value": "7 days"
    },
    "is_username_change_restricted": {
      "is_used": true,
      "value": true
    },
    "is_box_sync_restricted_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_view_all_users_enabled_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_device_limit_exemption_enabled_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_external_collaboration_restricted_for_new_users": {
      "is_used": true,
      "value": true
    },
    "is_unlimited_storage_enabled_for_new_users": {
      "is_used": true,
      "value": true
    },
    "new_user_default_storage_limit": {
      "is_used": true,
      "value": 1234
    },
    "new_user_default_timezone": {
      "is_used": true,
      "value": "GMT-05:00 America\\/Chicago CDT"
    },
    "new_user_default_language": {
      "is_used": true,
      "value": "English (US)"
    },
    "is_enterprise_sso_required": {
      "is_used": true,
      "value": true
    },
    "is_enterprise_sso_in_testing": {
      "is_used": true,
      "value": true
    },
    "is_sso_auto_add_groups_enabled": {
      "is_used": true,
      "value": true
    },
    "is_sso_auto_add_user_to_groups_enabled": {
      "is_used": true,
      "value": true
    },
    "is_sso_auto_remove_user_from_groups_enabled": {
      "is_used": true,
      "value": true
    },
    "user_tracking_codes": {
      "is_used": true,
      "value": [
        {
          "id": 1234,
          "name": "Employee ID"
        }
      ]
    },
    "number_of_user_tracking_codes_remaining": {
      "is_used": true,
      "value": 1234
    },
    "is_instant_login_restricted": {
      "is_used": true,
      "value": true
    }
  }
  ```
</Accordion>


# External Users resources
Source: https://developer.box.com/reference/v2025.0/external-users-resources



External users are collaborators from outside of your enterprise.

## External Users Submit Delete Job Response

Multi-status response containing the result for each external user deletion request.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of `External User Deletion Result` | Yes | Array of results of each external user deletion request. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "user_id": "12345",
        "status": 202,
        "detail": "string"
      }
    ]
  }
  ```
</Accordion>


# Box Hub Collaborations resources
Source: https://developer.box.com/reference/v2025.0/hub-collaborations-resources



A set of endpoints used to manage collaborations within a Box Hub.

## Box Hub Collaboration

A Box Hub collaboration object grants a user or group access to a Box Hub with permissions defined by a specific role.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this collaboration. |
  | `type` | `enum<string>` | Yes | The value will always be `hub_collaboration`. Available options: `hub_collaboration`. |
  | `hub` | [Box Hub (Base)](/reference/v2025.0/hubs-resources#box-hub-base) | No | |
  | `accessible_by` | `Box Hub Accessible By` | No | |
  | `role` | `string` | No | The level of access granted to a Box Hub. Possible values are `editor`, `viewer`, and `co-owner`. |
  | `status` | `enum<string>` | No | The status of the collaboration invitation. If the status is `pending`, `login` and `name` return an empty string. Available options: `accepted`, `pending`, `rejected`. |
  | `acceptance_requirements_status` | `object` | No | |

  ```json Example theme={null}
  {
    "id": "12345678",
    "type": "hub_collaboration",
    "hub": {
      "id": "12345",
      "type": "hubs"
    },
    "accessible_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "role": "editor",
    "status": "accepted",
    "acceptance_requirements_status": {
      "terms_of_service_requirement": {
        "is_accepted": true,
        "terms_of_service": {
          "id": "11446498",
          "type": "terms_of_service"
        }
      },
      "strong_password_requirement": {
        "enterprise_has_strong_password_required_for_external_users": true,
        "user_has_strong_password": true
      },
      "two_factor_authentication_requirement": {
        "enterprise_has_two_factor_auth_enabled": true,
        "user_has_two_factor_authentication_enabled": true
      }
    }
  }
  ```
</Accordion>

## Box Hub Collaborations

A list of Box Hub collaborations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub Collaboration](#box-hub-collaboration) | No | A list of Box Hub collaborations. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345678",
        "type": "hub_collaboration",
        "hub": {
          "id": "12345",
          "type": "hubs"
        },
        "accessible_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "role": "editor",
        "status": "accepted",
        "acceptance_requirements_status": {
          "terms_of_service_requirement": {
            "is_accepted": true,
            "terms_of_service": {
              "id": "11446498",
              "type": "terms_of_service"
            }
          },
          "strong_password_requirement": {
            "enterprise_has_strong_password_required_for_external_users": true,
            "user_has_strong_password": true
          },
          "two_factor_authentication_requirement": {
            "enterprise_has_two_factor_auth_enabled": true,
            "user_has_two_factor_authentication_enabled": true
          }
        }
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Box Hub Document resources
Source: https://developer.box.com/reference/v2025.0/hub-document-resources



A set of endpoints used to retrieve Box Hub Document elements (pages and content blocks).

## Box Hub Callout Box Text Block

A callout box block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `callout_box`. Available options: `callout_box`. |
  | `fragment` | `string` | Yes | Text content of the block. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "callout_box",
    "fragment": "This is the callout box"
  }
  ```
</Accordion>

## Box Hub Divider Block

A divider block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `divider`. Available options: `divider`. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "divider"
  }
  ```
</Accordion>

## Box Hub Document Blocks

A list of Hub Document blocks.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of `Box Hub Document Block Entry` | Yes | Ordered list of blocks. |
  | `type` | `enum<string>` | Yes | The value will always be `document_blocks`. Available options: `document_blocks`. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
        "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
        "type": "paragraph",
        "fragment": "This is the paragraph"
      }
    ],
    "type": "document_blocks",
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>

## Box Hub Document Page

A Page in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this page. |
  | `type` | `string` | Yes | The type of this resource. The value is always `page`. |
  | `parent_id` | `string` | No | The unique identifier of the parent page. Null for root-level pages. Can be `null`. |
  | `title_fragment` | `string` | Yes | The title text of the page. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "page",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "title_fragment": "This is the home page title"
  }
  ```
</Accordion>

## Box Hub Document Pages

A list of Hub Document Pages.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub Document Page](#box-hub-document-page) | Yes | Ordered list of pages. |
  | `type` | `enum<string>` | Yes | The value will always be `document_pages`. Available options: `document_pages`. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
        "type": "page",
        "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
        "title_fragment": "This is the home page title"
      }
    ],
    "type": "document_pages",
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>

## Box Hub Item List Block

An item list block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `item_list`. Available options: `item_list`. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "item_list"
  }
  ```
</Accordion>

## Box Hub Paragraph Text Block

A paragraph block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `paragraph`. Available options: `paragraph`. |
  | `fragment` | `string` | Yes | Text content of the block. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "paragraph",
    "fragment": "This is the paragraph"
  }
  ```
</Accordion>

## Box Hub Section Title Text Block

A section title block in the Box Hub Document.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this block. |
  | `parent_id` | `string` | No | The unique identifier of the parent block. Null for direct children of the page. Can be `null`. |
  | `type` | `enum<string>` | Yes | The type of this block. The value is always `section_title`. Available options: `section_title`. |
  | `fragment` | `string` | Yes | Text content of the block. Includes rich text formatting. |

  ```json Example theme={null}
  {
    "id": "c9588f08-22d7-4d17-8ca9-f1e61c98c0bd",
    "parent_id": "d97f7c26-0d9b-42a1-a00d-6e6db9619e0f",
    "type": "section_title",
    "fragment": "This is the section title"
  }
  ```
</Accordion>


# Box Hub Items resources
Source: https://developer.box.com/reference/v2025.0/hub-items-resources



A set of endpoints used to manage items within a Box Hub.

## Box Hub Item

A Box Hub Item is a Box Item that is referenced in a Box Hub.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier for this item. |
  | `type` | `enum<string>` | Yes | The type of the item. Available options: `file`, `folder`, `web_link`. |
  | `name` | `string` | Yes | The name of the item. |

  ```json Example theme={null}
  {
    "id": "12345678",
    "type": "file",
    "name": "My File"
  }
  ```
</Accordion>

## Box Hub Items

A list of Box Hub items.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub Item](#box-hub-item) | No | A list of Box Hub items. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345678",
        "type": "file",
        "name": "My File"
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>

## Box Hub Items Manage Response

Response schema for the status of Box Hub items management operations.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `operations` | array of `Box Hub Item Operation Result` | Yes | List of operations performed on Box Hub items. |

  ```json Example theme={null}
  {
    "operations": [
      {
        "action": "add",
        "item": {
          "type": "file",
          "id": "42037322"
        },
        "parent_id": "721d97d7-ac8a-4e5e-adb6-ef11af4e6d9e",
        "status": 200,
        "error": "Item not found"
      }
    ]
  }
  ```
</Accordion>


# Box Hubs resources
Source: https://developer.box.com/reference/v2025.0/hubs-resources



A set of endpoints used to manage Box Hubs.

## Box Hub

A standard representation of a Box Hub, as returned from any Box Hubs API endpoints by default.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Hub. The ID for any Box Hub can be determined by visiting a Box Hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. |
  | `type` | `enum<string>` | Yes | The value will always be `hubs`. Available options: `hubs`. |
  | `title` | `string` | No | The title given to the Box Hub. |
  | `description` | `string` | No | The description of the Box Hub. First 200 characters are returned. |
  | `created_at` | `string` | No | The date and time when the folder was created. This value may be `null` for some folders such as the root folder or the trash folder. |
  | `updated_at` | `string` | No | The date and time when the Box Hub was last updated. |
  | `created_by` | `User (Mini)` | No | The user who created this Box Hub. |
  | `updated_by` | `User (Mini)` | No | The user who last modified this Box Hub. |
  | `view_count` | `integer` | No | The number of views for the Box Hub. |
  | `is_ai_enabled` | `boolean` | No | Indicates if AI features are enabled for the Box Hub. |
  | `is_collaboration_restricted_to_enterprise` | `boolean` | No | Indicates if collaboration is restricted to the enterprise. |
  | `can_non_owners_invite` | `boolean` | No | Indicates if non-owners can invite others to the Box Hub. |
  | `can_shared_link_be_created` | `boolean` | No | Indicates if a shared link can be created for the Box Hub. |
  | `can_public_shared_link_be_created` | `boolean` | No | Indicates if a public shared link can be created for the Box Hub. |
  | `copy_hub_access` | `enum<string>` | No | Specifies who is allowed to copy the Box Hub. - `all` - Any user with access to the Hub can copy it. - `company` - Only users within the same enterprise as the Hub can copy it. - `none` - No one can copy the Hub. Available options: `all`, `company`, `none`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "hubs",
    "title": "Contracts",
    "description": "All the contracts for the company.",
    "created_at": "2012-12-12T10:53:43Z",
    "updated_at": "2012-12-12T10:53:43Z",
    "created_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "updated_by": {
      "id": "11446498",
      "type": "user",
      "name": "Aaron Levie",
      "login": "ceo@example.com"
    },
    "view_count": 506,
    "is_ai_enabled": true,
    "is_collaboration_restricted_to_enterprise": true,
    "can_non_owners_invite": true,
    "can_shared_link_be_created": true,
    "can_public_shared_link_be_created": true,
    "copy_hub_access": "company"
  }
  ```
</Accordion>

## Box Hub (Base)

The bare basic representation of a Box Hub.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier that represent a Box Hub. The ID for any Box Hub can be determined by visiting a Box Hub in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/hubs/123` the `hub_id` is `123`. |
  | `type` | `enum<string>` | Yes | The value will always be `hubs`. Available options: `hubs`. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "hubs"
  }
  ```
</Accordion>

## Box Hubs

A paginated list of hubs.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Box Hub](#box-hub) | No | A list of hubs. |
  | `limit` | `integer` | No | The limit that was used for these entries. This will be the same as the `limit` query parameter unless that value exceeded the maximum value allowed. The maximum value varies by API. |
  | `next_marker` | `string` | No | The marker for the start of the next page of results. Can be `null`. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "hubs",
        "title": "Contracts",
        "description": "All the contracts for the company.",
        "created_at": "2012-12-12T10:53:43Z",
        "updated_at": "2012-12-12T10:53:43Z",
        "created_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "updated_by": {
          "id": "11446498",
          "type": "user",
          "name": "Aaron Levie",
          "login": "ceo@example.com"
        },
        "view_count": 506,
        "is_ai_enabled": true,
        "is_collaboration_restricted_to_enterprise": true,
        "can_non_owners_invite": true,
        "can_shared_link_be_created": true,
        "can_public_shared_link_be_created": true,
        "copy_hub_access": "company"
      }
    ],
    "limit": 1000,
    "next_marker": "JV9IRGZmieiBasejOG9yDCRNgd2ymoZIbjsxbJMjIs3kioVii"
  }
  ```
</Accordion>


# Shield lists resources
Source: https://developer.box.com/reference/v2025.0/shield-lists-resources



Shield List allow an administrator to create a list which will be shared between different Shield Smart Access and Threat Detection rules.

## List of Shield Lists

List of Shield List objects.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Shield List (Mini)](#shield-list-mini) | No | A list of shield list objects. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345678-1234-1234-1234-123456789012",
        "type": "shield_list",
        "name": "My Shield List",
        "content": {
          "type": "country_code"
        }
      }
    ]
  }
  ```
</Accordion>

## Shield List

A standard representation of a Shield List.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | Unique identifier for the shield list. |
  | `type` | `string` | Yes | Type of the object. |
  | `name` | `string` | Yes | Name of the shield list. |
  | `enterprise` | `Enterprise reference` | Yes | Enterprise for which this list belongs to. |
  | `description` | `string` | No | Description of Shield List. |
  | `created_at` | `string` | Yes | ISO date time string when this shield list object was created. |
  | `updated_at` | `string` | Yes | ISO date time string when this shield list object was updated. |
  | `content` | `Shield List Content` | Yes | Specifies the type of elements in this Shield List and includes the elements themselves. |

  ```json Example theme={null}
  {
    "id": "90fb0e17-c332-40ed-b4f9-fa8908fbbb24",
    "type": "shield_list",
    "name": "Shield List Name",
    "enterprise": {
      "id": "1910967",
      "type": "enterprise"
    },
    "description": "A list of things that are shielded",
    "created_at": "2025-01-13T15:31:01.896Z",
    "updated_at": "2025-01-13T15:31:01.896Z",
    "content": {
      "type": "country",
      "country_codes": [
        "US",
        "PL"
      ]
    }
  }
  ```
</Accordion>

## Shield List (Mini)

A mini representation of a Shield List.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | Unique global identifier for this list. |
  | `type` | `enum<string>` | Yes | The type of object. Available options: `shield_list`. |
  | `name` | `string` | Yes | Name of Shield List. |
  | `content` | `object` | Yes | |

  ```json Example theme={null}
  {
    "id": "12345678-1234-1234-1234-123456789012",
    "type": "shield_list",
    "name": "My Shield List",
    "content": {
      "type": "country_code"
    }
  }
  ```
</Accordion>

## Shield List Content (Country)

Representation of content of a Shield List that contains countries data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `country`. |
  | `country_codes` | array of `string` | Yes | List of country codes values. |

  ```json Example theme={null}
  {
    "type": "country",
    "country_codes": [
      "US",
      "PL"
    ]
  }
  ```
</Accordion>

## Shield List Content (Domain)

Representation of content of a Shield List that contains domains data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `domain`. |
  | `domains` | array of `string` | Yes | List of domain. |

  ```json Example theme={null}
  {
    "type": "domain",
    "domains": [
      "box.com",
      "example.com"
    ]
  }
  ```
</Accordion>

## Shield List Content (Email)

Representation of content of a Shield List that contains email addresses data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `email`. |
  | `email_addresses` | array of `string` | Yes | List of emails. |

  ```json Example theme={null}
  {
    "type": "email",
    "email_addresses": [
      "example1@box.com",
      "example2@gmail.com"
    ]
  }
  ```
</Accordion>

## Shield List Content (Integration)

Representation of content of a Shield List that contains integrations data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `integration`. |
  | `integrations` | array of `object` | Yes | List of integration. |

  ```json Example theme={null}
  {
    "type": "integration",
    "integrations": [
      {
        "id": "505e40b5-5d04-446a-9268-72a0ccc13669"
      }
    ]
  }
  ```
</Accordion>

## Shield List Content (IP)

Representation of content of a Shield List that contains ip addresses data.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The type of content in the shield list. Available options: `ip`. |
  | `ip_addresses` | array of `string` | Yes | List of ip addresses and CIDRs. |

  ```json Example theme={null}
  {
    "type": "ip",
    "ip_addresses": [
      "127.0.0.1",
      "80.12.12.12/24"
    ]
  }
  ```
</Accordion>


# Convert to Box note resources
Source: https://developer.box.com/reference/v2026.0/notes-resources



Create Box Notes from supported source content (for example Markdown).

## Notes convert response

Identifies the created Box Note file.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `type` | `enum<string>` | Yes | The Box resource type; always `file` for a Box file. Available options: `file`. |
  | `id` | `string` | Yes | Box file ID of the created `.boxnote` file. |

  ```json Example theme={null}
  {
    "type": "file",
    "id": "1234567890"
  }
  ```
</Accordion>


# Query resources
Source: https://developer.box.com/reference/v2026.0/query-resources



Query for your items.

## Query insight entry

A single computed insight entry, containing its grouping keys (if applicable) and the computed metrics.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `key` | array of `string` | Yes | The grouping key values associated with the entry. Contains one value per `group_by` field for `group` entries, and is empty for `overall` and `other` entries. |
  | `type` | `enum<string>` | Yes | The type of insight entry, indicating how the associated metrics are aggregated. Available options: `group`, `overall`, `other`. |
  | `metrics` | `object` | Yes | A map of metric aliases to their computed results. For `other` entries, the count is reported under the `totalCountBeyondTopGroups` key. |

  ```json Example theme={null}
  {
    "key": [
      "ContractType1"
    ],
    "type": "group",
    "metrics": {
      "totalContractValue": {
        "type": "sum",
        "values": {
          "sum": 180000
        }
      },
      "countContractType": {
        "type": "count",
        "values": {
          "count": 245
        }
      }
    }
  }
  ```
</Accordion>

## Query insights

The computed results of an insights request, as a list of insight entries.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `insights` | array of [Query insight entry](#query-insight-entry) | Yes | The list of computed insight entries. Each entry corresponds to a group, the overall dataset, or the aggregate of groups outside the top results. |

  ```json Example theme={null}
  {
    "insights": [
      {
        "key": [
          "ContractType1"
        ],
        "type": "group",
        "metrics": {
          "totalContractValue": {
            "type": "sum",
            "values": {
              "sum": 180000
            }
          },
          "countContractType": {
            "type": "count",
            "values": {
              "count": 245
            }
          }
        }
      },
      {
        "key": [
          "ContractType4"
        ],
        "type": "group",
        "metrics": {
          "totalContractValue": {
            "type": "sum",
            "values": {
              "sum": 100000
            }
          },
          "countContractType": {
            "type": "count",
            "values": {
              "count": 185
            }
          }
        }
      },
      {
        "key": [
          "ContractType2"
        ],
        "type": "group",
        "metrics": {
          "totalContractValue": {
            "type": "sum",
            "values": {
              "sum": 200000
            }
          },
          "countContractType": {
            "type": "count",
            "values": {
              "count": 150
            }
          }
        }
      },
      {
        "key": [],
        "type": "other",
        "metrics": {
          "totalCountBeyondTopGroups": {
            "type": "count",
            "values": {
              "count": 165
            }
          }
        }
      }
    ]
  }
  ```
</Accordion>

## Query result entry

A single item matching the query. Always includes the item `type` and `id`. If a `fields` parameter was specified in the request, then additional item and/or metadata fields will be provided.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `id` | `string` | Yes | The unique identifier of the matching item. |
  | `type` | `string` | Yes | The type of the matching item. |

  ```json Example theme={null}
  {
    "id": "12345",
    "type": "file"
  }
  ```
</Accordion>

## Query results

A paginated list of items matching the query, using milestone-based marker pagination.

<Accordion title="Attributes and example">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `entries` | array of [Query result entry](#query-result-entry) | Yes | The list of items matching the query predicate. |
  | `next_marker` | `string` | Yes | The marker for the start of the next page of results. When `null`, there are no further results available. Can be `null`. |
  | `limit` | `integer` | Yes | The limit that was used for this request. This will be the same as the limit query parameter unless that value exceeded the maximum value allowed. |

  ```json Example theme={null}
  {
    "entries": [
      {
        "id": "12345",
        "type": "file",
        "box": {
          "item": {
            "name": "My Form"
          }
        },
        "enterprise_12345678": {
          "book": {
            "$parent": "file_12345",
            "$scope": "enterprise_12345678",
            "$template": "book",
            "$version": 4,
            "isbn": "1871263670",
            "purchasePrice": 234.57,
            "publicationYear": "1937"
          }
        }
      }
    ],
    "next_marker": "xppy0jjG1kBRSc7NBBSgQmBz1Gk6VaQdg5Vyb+Ob0iA=",
    "limit": 1
  }
  ```
</Accordion>