### Install box-python-sdk-gen v1 (Old)

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-box-python-sdk-gen-v1-to-box-python-sdk.md

This is the old installation command for the box-python-sdk-gen v1.

```console
pip install box-sdk-gen
```

--------------------------------

### Install Box Python SDK v10

Source: https://github.com/box/box-python-sdk/blob/main/README.md

Use this command to install version 10 or higher of the Box Python SDK. This version is recommended for new users and those previously using `box-sdk-gen`.

```console
pip install boxsdk>=10
```

--------------------------------

### Install Box Python SDK v4

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-v3-to-v4.md

To upgrade from v3 to v4, update the `boxsdk` dependency in your requirements file or installation command to version 4.0 or higher.

```console
pip install boxsdk~=4.0
```

--------------------------------

### Start Automate workflow

Source: https://github.com/box/box-python-sdk/blob/main/docs/automate_workflows.md

Starts an Automate workflow manually by using a workflow action ID and file IDs. This is used to trigger a specific workflow on one or more files.

```APIDOC
## POST /automate_workflows/{workflow_id}/start

### Description
Starts an Automate workflow manually by using a workflow action ID and file IDs.

### Method
POST

### Endpoint
/automate_workflows/{workflow_id}/start

### Parameters
#### Path Parameters
- **workflow_id** (str) - Required - The ID of the workflow. Example: "12345"

#### Request Body
- **workflow_action_id** (str) - Required - The callable action ID used to trigger the selected workflow.
- **file_ids** (Array[str]) - Required - The files to process with the selected workflow.

### Response
#### Success Response (200)
This function returns a value of type `None`.

Starts the workflow.

### Request Example
```python
admin_client.automate_workflows.create_automate_workflow_start_v2026_r0(
    workflow_action.workflow.id, workflow_action.id, [workflow_file_id]
)
```

### Response Example
(No response body for success)

```

--------------------------------

### Install Box Python SDK v10 with JWT Authentication

Source: https://github.com/box/box-python-sdk/blob/main/README.md

To install version 10 or higher of the Box Python SDK along with extra dependencies required for JWT authentication, use this command.

```console
pip install "boxsdk[jwt]>=10"
```

--------------------------------

### Start Workflow

Source: https://github.com/box/box-python-sdk/blob/main/docs/workflows.md

Initiates a workflow with a trigger type of WORKFLOW_MANUAL_START. Requires 'Manage Box Relay' scope.

```APIDOC
## Starts workflow based on request body

### Description
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.

### Method
POST

### Endpoint
/workflows/{workflow_id}/start

### Parameters
#### Path Parameters
- **workflow_id** (str) - Required - The ID of the workflow. Example: "12345"

#### Request Body
- **type** (StartWorkflowType) - Optional - The type of the parameters object.
- **flow** (StartWorkflowFlow) - Required - The flow that will be triggered.
- **files** (List[StartWorkflowFiles]) - Required - The array of files for which the workflow should start. All files must be in the workflow's configured folder.
- **folder** (StartWorkflowFolder) - Required - The folder object for which the workflow is configured.
- **outcomes** (List[Outcome]) - Optional - A configurable outcome the workflow should complete.
- **extra_headers** (Dict[str, Optional[str]]) - Optional - Extra headers that will be included in the HTTP request.

### Response
#### Success Response (200)
- **None** - Starts the workflow.

### Request Example
```python
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,
)
```
```

--------------------------------

### Get Zip Download Status

Source: https://github.com/box/box-python-sdk/blob/main/docs/zip_downloads.md

Checks the status of a zip archive download. This endpoint is accessible only after the download has started and remains valid for 12 hours. Use the status URL obtained from the `create_zip_download` response.

```python
client.zip_downloads.get_zip_download_status(zip_download.status_url)
```

--------------------------------

### Initialize BoxClient with Developer Token

Source: https://github.com/box/box-python-sdk/blob/main/docs/authentication.md

Demonstrates how to create a BoxClient instance using a developer token for quick API access, suitable for testing.

```APIDOC
## Initialize BoxClient with Developer Token

### Description
This example shows how to initialize the BoxClient using a developer token. Developer tokens are short-lived and intended for testing purposes only.

### Method
```python
from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth

auth = BoxDeveloperTokenAuth(token="DEVELOPER_TOKEN_GOES_HERE")
client = BoxClient(auth=auth)

me = client.users.get_user_me()
print(f"My user ID is {me.id}")
```

### Parameters
- `token` (string): Your developer token obtained from the Box Developer Console.
```

--------------------------------

### Get zip download status

Source: https://github.com/box/box-python-sdk/blob/main/docs/zip_downloads.md

Checks the progress and status of a zip archive download. This endpoint is accessible only after the download has started and remains valid for 12 hours. Use the `status_url` obtained from the 'Create zip download' operation.

```APIDOC
## GET /zip/downloads/{zip_download_id}/status

### Description
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](https://developer.box.com/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.

### Method
GET

### Endpoint
/zip/downloads/{zip_download_id}/status

### Parameters
#### Query Parameters
- **status_url** (str) - Required - The URL to check the status of the zip download. Example: `https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status`
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Optional - Extra headers that will be included in the HTTP request.

### Response
#### Success Response (200)
- **status** (str) - The current status of the zip download (e.g., 'in_progress', 'succeeded', 'failed').
- **progress_percent** (int) - The percentage of the download that has been completed.
- **skipped_items** (List[SkippedItem]) - A list of items that were skipped during the zip creation process.

### Request Example
```python
client.zip_downloads.get_zip_download_status(zip_download.status_url)
```

### Response Example
```json
{
  "status": "in_progress",
  "progress_percent": 50,
  "skipped_items": []
}
```
```

--------------------------------

### Initialize BoxClient with JWT Auth (direct configuration)

Source: https://github.com/box/box-python-sdk/blob/main/docs/authentication.md

Illustrates how to set up JWT authentication by providing all necessary configuration parameters directly in the code.

```APIDOC
## Initialize BoxClient with JWT Auth (direct configuration)

### Description
This example shows how to initialize the BoxClient using JWT authentication by providing all required configuration parameters directly within the code. This is an alternative to loading configuration from a file.

### Method
```python
from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig

jwt_config = JWTConfig(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    jwt_key_id="YOUR_JWT_KEY_ID",
    private_key="YOUR_PRIVATE_KEY",
    private_key_passphrase="PASSPHRASE",
    enterprise_id="YOUR_ENTERPRISE_ID",
)

auth = BoxJWTAuth(config=jwt_config)
service_account_client = BoxClient(auth=auth)
```

### Parameters
- `client_id` (string): Your application's client ID.
- `client_secret` (string): Your application's client secret.
- `jwt_key_id` (string): The ID of the public/private key pair used for JWT signing.
- `private_key` (string): Your private key content.
- `private_key_passphrase` (string): The passphrase for your private key, if applicable.
- `enterprise_id` (string): The ID of the enterprise you are authenticating for.
```

--------------------------------

### Get shared link for web link

Source: https://github.com/box/box-python-sdk/blob/main/docs/shared_links_web_links.md

Gets the information for a shared link on a web link.

```APIDOC
## Get shared link for web link

### Description
Gets the information for a shared link on a web link.

### Method
GET

### Endpoint
/web_links/{web_link_id}

### Parameters
#### Path Parameters
- **web_link_id** (str) - The ID of the web link. Example: "12345"

#### Query Parameters
- **fields** (str) - Explicitly request the `shared_link` fields to be returned for this item.

#### Headers
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Extra headers that will be included in the HTTP request.

### Response
#### Success Response (200)
- **WebLink** (WebLink) - Returns the base representation of a web link with the additional shared link information.

### Request Example
```python
client.shared_links_web_links.get_shared_link_for_web_link(web_link_id, "shared_link")
```
```

--------------------------------

### Initialize Box Client with Developer Token

Source: https://github.com/box/box-python-sdk/blob/main/docs/authentication.md

Use a developer token for quick testing. This token is short-lived, cannot be refreshed, and is only suitable for testing with your own account.

```python
from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth

auth = BoxDeveloperTokenAuth(token="DEVELOPER_TOKEN_GOES_HERE")
client = BoxClient(auth=auth)

me = client.users.get_user_me()
print(f"My user ID is {me.id}")
```

--------------------------------

### Get Specific Comment

Source: https://github.com/box/box-python-sdk/blob/main/docs/comments.md

Retrieves the message and metadata for a single comment by its ID. Use this to get detailed information about a specific comment.

```python
client.comments.get_comment_by_id(new_comment.id)
```

--------------------------------

### New box_sdk_gen: Creating a client with 'as-user' header

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-boxsdk-to-box_sdk_gen.md

The box_sdk_gen package uses methods prefixed with 'with_' to return new, modified instances, promoting immutability. This example shows how to create a client that makes requests as a specific user.

```python
from box_sdk_gen import BoxClient

as_user_client: BoxClient = client.with_as_user_header("USER_ID")
```

--------------------------------

### Create Terms of Service Status for User

Source: https://github.com/box/box-python-sdk/blob/main/docs/terms_of_service_user_statuses.md

Sets the acceptance status for a user for a given terms of service. Use this to record a user's initial agreement.

```python
client.terms_of_service_user_statuses.create_terms_of_service_status_for_user(
    CreateTermsOfServiceStatusForUserTos(id=tos.id),
    CreateTermsOfServiceStatusForUserUser(id=user.id),
    False,
)
```

--------------------------------

### Get Shared Link for Folder

Source: https://github.com/box/box-python-sdk/blob/main/docs/shared_links_folders.md

Retrieves the shared link information for a specific folder. Ensure you have the folder ID and specify 'shared_link' to get the relevant details.

```python
client.shared_links_folders.get_shared_link_for_folder(folder.id, "shared_link")
```

--------------------------------

### Get Shared Link for File

Source: https://github.com/box/box-python-sdk/blob/main/docs/shared_links_files.md

Retrieves the shared link information for a specific file. Ensure the `fields` parameter is set to 'shared_link' to get the relevant details.

```python
client.shared_links_files.get_shared_link_for_file(file_id, "shared_link")
```

--------------------------------

### Start Automate Workflow

Source: https://github.com/box/box-python-sdk/blob/main/docs/automate_workflows.md

Initiate a Box Automate workflow manually. Provide the workflow ID, the specific action ID, and a list of file IDs to process.

```python
admin_client.automate_workflows.create_automate_workflow_start_v2026_r0(
    workflow_action.workflow.id, workflow_action.id, [workflow_file_id]
)
```

--------------------------------

### Create Metadata Instance on File

Source: https://github.com/box/box-python-sdk/blob/main/docs/file_metadata.md

Applies a metadata template instance to a file. The 'global.properties' template accepts any key-value pair, while others typically require predefined values.

```python
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"],
    },
)
```

--------------------------------

### JWT Configuration Manual Setup

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-boxsdk-to-box_sdk_gen.md

Compare manual JWT configuration between boxsdk and box_sdk_gen. Note the parameter name changes and the introduction of JWTConfig in the new SDK.

```python
from boxsdk import JWTAuth

auth = JWTAuth(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    enterprise_id="YOUR_ENTERPRISE_ID",
    user_id="USER_ID",
    jwt_key_id="YOUR_JWT_KEY_ID",
    rsa_private_key_file_sys_path="CERT.PEM",
    rsa_private_key_passphrase="PASSPHRASE",
    jwt_algorithm="RS256",
)
```

```python
from box_sdk_gen import BoxJWTAuth, JWTConfig, JwtAlgorithm

jwt_config = JWTConfig(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    enterprise_id="YOUR_ENTERPRISE_ID",
    user_id="USER_ID",
    jwt_key_id="YOUR_JWT_KEY_ID",
    private_key="YOUR_PRIVATE_KEY",
    private_key_passphrase="PASSPHRASE",
    algorithm=JwtAlgorithm.RS256,
)
auth = BoxJWTAuth(config=jwt_config)
```

--------------------------------

### Get File Version Retention by ID

Source: https://github.com/box/box-python-sdk/blob/main/docs/file_version_retentions.md

Retrieves information about a specific file version retention using its ID. This is useful for getting details of a single retention policy assignment.

```python
client.file_version_retentions.get_file_version_retention_by_id(
    file_version_retention.id
)
```

--------------------------------

### Initialize BoxClient with JWT Auth (from config file)

Source: https://github.com/box/box-python-sdk/blob/main/docs/authentication.md

Shows how to authenticate using JWT by loading configuration from a JSON file, enabling enterprise-level API access.

```APIDOC
## Initialize BoxClient with JWT Auth (from config file)

### Description
This example demonstrates how to authenticate with the Box API using JWT by loading configuration details from a JSON file. This method is used to authenticate as the enterprise's Service Account.

### Method
```python
from box_sdk_gen import BoxClient, BoxJWTAuth, JWTConfig

jwt_config = JWTConfig.from_config_file(config_file_path="/path/to/settings.json")
auth = BoxJWTAuth(config=jwt_config)
client = BoxClient(auth=auth)

service_account = client.users.get_user_me()
print(f"Service Account user ID is {service_account.id}")
```

### Parameters
- `config_file_path` (string): The local file path to the JWT configuration JSON file.
```

--------------------------------

### Start Workflow with Parameters

Source: https://github.com/box/box-python-sdk/blob/main/docs/workflows.md

Initiates a workflow manually. This requires the workflow ID, flow details, file(s) to process, and the target folder. The 'Manage Box Relay' scope is necessary.

```python
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,
)
```

--------------------------------

### Get Folder Information by ID

Source: https://github.com/box/box-python-sdk/blob/main/docs/folders.md

Retrieves details for a specific folder using its ID. Supports optional parameters for sorting, pagination, and field selection. Use this to get basic folder information and its first 100 entries.

```python
client.folders.get_folder_by_id("0")
```

--------------------------------

### Initialize BoxClient with Developer Token (v10)

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-box-python-sdk-gen-v1-to-box-python-sdk.md

Example of initializing the BoxClient using a developer token for the box-python-sdk v10. Ensure you replace 'INSERT YOUR DEVELOPER TOKEN HERE' with your actual token.

```python
from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth

auth: BoxDeveloperTokenAuth = BoxDeveloperTokenAuth(
    token="INSERT YOUR DEVELOPER TOKEN HERE"
)
client: BoxClient = BoxClient(auth=auth)
for item in client.folders.get_folder_items("0").entries:
    print(item.name)
```

--------------------------------

### Get webhook by ID

Source: https://github.com/box/box-python-sdk/blob/main/docs/webhooks.md

Retrieves a specific webhook by its ID.

```APIDOC
## Get webhook by ID

### Description
Retrieves a specific webhook by its ID.

### Method
GET

### Endpoint
/webhooks/{webhook_id}

### Parameters
#### Path Parameters
- **webhook_id** (str) - Required - The ID of the webhook. Example: "3321123"
#### Query Parameters
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Optional - Extra headers that will be included in the HTTP request.

### Returns
#### Success Response (200)
- **webhook** (Webhook) - Returns a webhook object.

### Request Example
```python
client.webhooks.get_webhook_by_id(webhook.id)
```
```

--------------------------------

### Complete Box OAuth 2.0 Workflow with Flask

Source: https://github.com/box/box-python-sdk/blob/main/docs/authentication.md

A Flask application example demonstrating the complete OAuth 2.0 workflow, including obtaining an authorization URL, handling the callback, exchanging the code for tokens, and listing items in the root folder.

```python
from flask import Flask, request, redirect

from box_sdk_gen import BoxClient, BoxOAuth, OAuthConfig, GetAuthorizeUrlOptions

app = Flask(__name__)

AUTH = BoxOAuth(
    OAuthConfig(client_id="YOUR_CLIENT_ID", client_secret="YOUR_CLIENT_SECRET")
)


@app.route("/")
def get_auth():
    auth_url = AUTH.get_authorize_url(
        options=GetAuthorizeUrlOptions(redirect_uri="YOUR_REDIRECT_URL")
    )
    return redirect(auth_url, code=302)


@app.route("/oauth2callback")
def callback():
    AUTH.get_tokens_authorization_code_grant(request.args.get("code"))
    client = BoxClient(auth=AUTH)

    items_in_root_folder = [
        item.name for item in client.folders.get_folder_items(folder_id="0").entries
    ]
    return ", ".join(items_in_root_folder)


if __name__ == "__main__":
    app.run(port=4999)
```

--------------------------------

### Get Legal Hold Policy Assignment File on Hold

Source: https://github.com/box/box-python-sdk/blob/main/docs/legal_hold_policy_assignments.md

Retrieves a list of current file versions held under legal hold for a specific assignment. Use this to get the latest version of files. Note that this API might not return all file versions due to re-architecture.

```python
client.legal_hold_policy_assignments.get_legal_hold_policy_assignment_file_on_hold(
    legal_hold_policy_assignment_id
)
```

--------------------------------

### Create metadata instance on file

Source: https://github.com/box/box-python-sdk/blob/main/docs/file_metadata.md

Applies an instance of a metadata template to a file. Accepts key-value pairs, with specific handling for the `global.properties` template.

```APIDOC
## POST /files/{file_id}/metadata/{scope}/{template_key}

### Description
Applies an instance of a metadata template to a file.

### Method
POST

### Endpoint
/files/{file_id}/metadata/{scope}/{template_key}

### Parameters
#### Path Parameters
- **file_id** (str) - Required - The unique identifier that represents a file. Example: "12345"
- **scope** (CreateFileMetadataByIdScope) - Required - The scope of the metadata template. Example: "global"
- **template_key** (str) - Required - The name of the metadata template. Example: "properties"

#### Request Body
- **request_body** (Dict) - Required - Request body containing metadata key-value pairs.

#### Query Parameters
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Optional - Extra headers that will be included in the HTTP request.

### Returns
#### Success Response (200)
- **MetadataFull** - Returns the instance of the template that was applied to the file, including the data.

### Request Example
```python
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"],
    },
)
```

### Response Example
{
  "example": "MetadataFull"
}
```

--------------------------------

### List All Storage Policies

Source: https://github.com/box/box-python-sdk/blob/main/docs/storage_policies.md

Fetches all storage policies in the enterprise. Use optional arguments like `fields`, `marker`, `limit`, and `extra_headers` for customization.

```python
client.storage_policies.get_storage_policies()
```

--------------------------------

### Get Task

Source: https://github.com/box/box-python-sdk/blob/main/docs/tasks.md

Retrieves information about a specific task using its ID.

```APIDOC
## Get Task

### Description
Retrieves information about a specific task.

### Method
GET

### Endpoint
/tasks/{task_id}

### Parameters
#### Path Parameters
- **task_id** (str) - Required - The ID of the task. Example: "12345"

#### Request Body
None

### Response
#### Success Response (200)
- **Task** (object) - Returns a task object.

### Request Example
```python
client.tasks.get_task_by_id(task.id)
```

### Response Example
```json
{
  "type": "task",
  "id": "12345",
  "message": "Please review this document."
}
```
```

--------------------------------

### Get Watermark for Folder

Source: https://github.com/box/box-python-sdk/blob/main/docs/folder_watermarks.md

Retrieve the watermark configuration for a specific folder.

```APIDOC
## Get watermark for folder

### Description
Retrieve the watermark for a folder.

### Method
GET

### Endpoint
/folders/{folder_id}/watermark

### Parameters
#### Path Parameters
- **folder_id** (str) - Required - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this 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`. The root folder of a Box account is always represented by the ID `0`. Example: "12345"

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
client.folder_watermarks.get_folder_watermark(folder.id)
```

### Response
#### Success Response (200)
- **watermark** (Watermark) - Information about the watermark associated with the folder.

#### Response Example
```json
{
  "watermark": {
    "created_at": "2023-10-27T10:00:00Z",
    "created_by": {
      "type": "user",
      "id": "12345",
      "name": "John Doe"
    },
    "watermark_type": "text",
    "text_watermark": {
      "text": "Confidential"
    }
  }
}
```
```

--------------------------------

### Create metadata instance on folder

Source: https://github.com/box/box-python-sdk/blob/main/docs/folder_metadata.md

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.

```APIDOC
## POST /folders/{folder_id}/metadata/{scope}/{template_key}

### Description
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.

### Method
POST

### Endpoint
/folders/{folder_id}/metadata/{scope}/{template_key}

### Parameters
#### Path Parameters
- **folder_id** (str) - Required - The unique identifier that represent a folder. The ID for any folder can be determined by visiting this 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`. The root folder of a Box account is always represented by the ID `0`.
- **scope** (CreateFolderMetadataByIdScope) - Required - The scope of the metadata template.
- **template_key** (str) - Required - The name of the metadata template.

#### Query Parameters
None

#### Request Body
- **fields** (object) - Required - Key-value pairs representing the metadata to be applied to the folder.

### Request Example
```python
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"],
    },
)
```

### Response
#### Success Response (201)
- **MetadataFull** - An instance of the metadata template that includes additional "key:value" pairs defined by the user or an application.
```

--------------------------------

### Get storage policy assignment

Source: https://github.com/box/box-python-sdk/blob/main/docs/storage_policy_assignments.md

Fetches a specific storage policy assignment by its ID.

```APIDOC
## Get storage policy assignment

### Description
Fetches a specific storage policy assignment.

### Method
GET

### Endpoint
/storage_policy_assignments/{storage_policy_assignment_id}

### Parameters
#### Path Parameters
- **storage_policy_assignment_id** (str) - Required - The ID of the storage policy assignment. Example: "932483"
#### Query Parameters
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Optional - Extra headers that will be included in the HTTP request.

### Response
#### Success Response (200)
- Returns a storage policy assignment object.

### Request Example
```python
client.storage_policy_assignments.get_storage_policy_assignment_by_id(
    storage_policy_assignment.id
)
```
```

--------------------------------

### Authenticate with Developer Token and List Root Folder Items

Source: https://github.com/box/box-python-sdk/blob/main/README.md

This Python script demonstrates how to authenticate with a developer token using `BoxDeveloperTokenAuth` and `BoxClient`. It then lists the names of all items within the root folder ('0'). Replace 'INSERT YOUR DEVELOPER TOKEN HERE' with your actual developer token.

```python
from box_sdk_gen import BoxClient, BoxDeveloperTokenAuth

def main(token: str):
    auth: BoxDeveloperTokenAuth = BoxDeveloperTokenAuth(token=token)
    client: BoxClient = BoxClient(auth=auth)
    for item in client.folders.get_folder_items('0').entries:
        print(item.name)

if __name__ == '__main__':
    main('INSERT YOUR DEVELOPER TOKEN HERE')
```

--------------------------------

### Create Metadata Instance on Folder

Source: https://github.com/box/box-python-sdk/blob/main/docs/folder_metadata.md

Applies a metadata template instance to a folder. The 'global.properties' template accepts any key-value pair, while others typically require values present in the template. Enterprise configuration for 'Cascading Folder Level Metadata' may be required.

```python
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"],
    },
)
```

--------------------------------

### Get shared link for file

Source: https://github.com/box/box-python-sdk/blob/main/docs/shared_links_files.md

Retrieves the shared link information for a specific file.

```APIDOC
## Get shared link for file

### Description
Gets the information for a shared link on a file.

### Method
GET

### Endpoint
/files/{file_id}/get_shared_link

### Parameters
#### Path Parameters
- **file_id** (str) - The unique identifier that represents a file. The ID for any file can be determined by visiting a file in the web application and copying the ID from the URL. For example, for the URL `https://*.app.box.com/files/123` the `file_id` is `123`. Example: "12345"

#### Query Parameters
- **fields** (str) - Explicitly request the `shared_link` fields to be returned for this item.

#### Headers
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Extra headers that will be included in the HTTP request.

### Response
#### Success Response (200)
- **FileFull** - Returns the base representation of a file with the additional shared link information.

### Request Example
```python
client.shared_links_files.get_shared_link_for_file(file_id, "shared_link")
```
```

--------------------------------

### Old boxsdk: Creating a User class instance

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-boxsdk-to-box_sdk_gen.md

In the old boxsdk, you first created a class instance representing an existing user by providing their ID.

```python
user = client.user(user_id="123456")
```

--------------------------------

### Get retention policy assignment

Source: https://github.com/box/box-python-sdk/blob/main/docs/retention_policy_assignments.md

Retrieves a specific retention policy assignment by its ID.

```APIDOC
## Get retention policy assignment

### Description
Retrieves a retention policy assignment.

### Method
GET

### Endpoint
/retention_policy_assignments/{retention_policy_assignment_id}

### Parameters
#### Path Parameters
- **retention_policy_assignment_id** (str) - Required - The ID of the retention policy assignment.

#### Query Parameters
- **fields** (Optional[List[str]]) - Optional - A comma-separated list of attributes to include in the response.

### Request Example
```python
client.retention_policy_assignments.get_retention_policy_assignment_by_id(
    retention_policy_assignment.id
)
```

### Response
#### Success Response (200)
- **retention_policy_assignment** (RetentionPolicyAssignment) - The retention policy assignment object.
```

--------------------------------

### Get legal hold policy

Source: https://github.com/box/box-python-sdk/blob/main/docs/legal_hold_policies.md

Retrieves a specific legal hold policy by its ID.

```APIDOC
## Get legal hold policy

### Description
Retrieve a legal hold policy.

### Method
GET

### Endpoint
/legal_hold_policies/{legal_hold_policy_id}

### Parameters
#### Path Parameters
- **legal_hold_policy_id** (str) - Required - The ID of the legal hold policy. Example: "324432"
#### Query Parameters
- **extra_headers** (Dict[str, Optional[str]]) - Optional - Extra headers that will be included in the HTTP request.

### Response
#### Success Response (200)
- **LegalHoldPolicy** - Returns a legal hold policy object.

### Request Example
```python
client.legal_hold_policies.get_legal_hold_policy_by_id(
    legal_hold_policy_id='324432',
    extra_headers={'X-Request-ID': 'abcde'}
)
```
```

--------------------------------

### Create a Box Hub

Source: https://github.com/box/box-python-sdk/blob/main/docs/hubs.md

Use this snippet to create a new Box Hub. Ensure you provide a title and optionally a description.

```python
client.hubs.create_hub_v2025_r0(hub_title, description=hub_description)
```

--------------------------------

### Create Client to Impersonate a User

Source: https://github.com/box/box-python-sdk/blob/main/docs/client.md

Use `client.with_as_user_header(user_id)` to create a new client instance that makes API calls on behalf of a specified user. This is useful for admin tasks and requires appropriate privileges.

```python
user_client = client.with_as_user_header(user_id="1234567")
```

--------------------------------

### Get Folder Watermark

Source: https://github.com/box/box-python-sdk/blob/main/docs/folder_watermarks.md

Retrieve the watermark for a specific folder. Requires the folder ID.

```python
client.folder_watermarks.get_folder_watermark(folder.id)
```

--------------------------------

### Configure Custom Base URLs (Box SDK Gen)

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-boxsdk-to-box_sdk_gen.md

The `box_sdk_gen` package handles custom base URLs via the `with_custom_base_urls` method on `BoxClient`, accepting a `BaseUrls` object. This creates a new client instance.

```python
from box_sdk_gen import BoxClient, BaseUrls

new_client: BoxClient = client.with_custom_base_urls(
    base_urls=BaseUrls(
        base_url="https://new-base-url.com",
        upload_url="https://my-company-upload-url.com",
        oauth_2_url="https://my-company.com/oauth2",
    )
)
```

--------------------------------

### Get Watermark on File

Source: https://github.com/box/box-python-sdk/blob/main/docs/file_watermarks.md

Retrieve the watermark for a specific file. Requires the file ID.

```python
client.file_watermarks.get_file_watermark(file.id)
```

--------------------------------

### Get File Request

Source: https://github.com/box/box-python-sdk/blob/main/docs/file_requests.md

Retrieves the information about a specific file request using its ID.

```APIDOC
## Get file request

### Description
Retrieves the information about a file request.

### Method
GET

### Endpoint
/file_requests/:file_request_id

### Parameters
#### Path Parameters
- **file_request_id** (string) - Required - The unique identifier that represent a file request.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
client.file_requests.get_file_request_by_id(file_request_id)
```

### Response
#### Success Response (200)
- **FileRequest** (object) - Returns a file request object.

#### Response Example
```json
{
  "type": "file_request",
  "id": "12345",
  "title": "My File Request",
  "description": "Please upload your files here.",
  "status": "active",
  "is_email_required": true,
  "is_description_required": false,
  "expires_at": "2024-12-31T23:59:59Z",
  "url": "https://app.box.com/filerequest/12345"
}
```
```

--------------------------------

### Initialize BoxOAuth with Custom Token Storage

Source: https://github.com/box/box-python-sdk/blob/main/docs/authentication.md

Implement and use a custom token storage solution by inheriting from `TokenStorage` and providing your own implementations for storing, retrieving, and clearing tokens.

```python
from typing import Optional
from box_sdk_gen import BoxOAuth, OAuthConfig, TokenStorage, AccessToken


class MyCustomTokenStorage(TokenStorage):
    def store(self, token: AccessToken) -> None:
        # store token in your custom storage
        pass

    def get(self) -> Optional[AccessToken]:
        # retrieve token from your custom storage
        pass

    def clear(self) -> None:
        # clear token from your custom storage
        pass


auth = BoxOAuth(
    OAuthConfig(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET",
        token_storage=MyCustomTokenStorage(),
    )
)
```

--------------------------------

### Create Web Link

Source: https://github.com/box/box-python-sdk/blob/main/docs/web_links.md

Creates a new web link within a specified parent folder. Requires the target URL, parent folder ID, and optionally a name and description.

```python
client.web_links.create_web_link(
    "https://www.box.com",
    CreateWebLinkParent(id=parent.id),
    name=get_uuid(),
    description="Weblink description",
)
```

--------------------------------

### Get Device Pin

Source: https://github.com/box/box-python-sdk/blob/main/docs/device_pinners.md

Retrieves information about a specific device pin using its ID.

```APIDOC
## Get device pin

Retrieves information about an individual device pin.

### Method
GET

### Endpoint
/device_pinners/{device_pinner_id}

### Parameters
#### Path Parameters
- **device_pinner_id** (string) - Required - The ID of the device pin.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **type** (string) - The type of the object.
- **id** (string) - The ID of the device pin.
- **item** (object) - The item associated with the device pin.
  - **type** (string) - The type of the item.
  - **id** (string) - The ID of the item.
- **device** (object) - The device associated with the device pin.
  - **type** (string) - The type of the device.
  - **id** (string) - The ID of the device.
  - **name** (string) - The name of the device.
- **created_at** (string) - The timestamp when the device pin was created.
- **modified_at** (string) - The timestamp when the device pin was last modified.

### Request Example
```json
{
  "example": "request body"
}
```

### Response Example
```json
{
  "type": "device_pinner",
  "id": "12345",
  "item": {
    "type": "file",
    "id": "67890"
  },
  "device": {
    "type": "device",
    "id": "device-1",
    "name": "My Device"
  },
  "created_at": "2023-01-01T12:00:00Z",
  "modified_at": "2023-01-01T12:00:00Z"
}
```
```

--------------------------------

### Get upload session by URL

Source: https://github.com/box/box-python-sdk/blob/main/docs/chunked_uploads.md

Retrieves information about an upload session using its status URL.

```APIDOC
## Get upload session by URL

Return information about an upload session.

The actual endpoint URL is returned by the [`Create upload session`](https://developer.box.com/reference/post-files-upload-sessions) endpoint.

```python
client.chunked_uploads.get_file_upload_session_by_url(status_url)
```

### Arguments

- url `str`
  - URL of getFileUploadSessionById method
- extra_headers `Optional[Dict[str, Optional[str]]]`
  - Extra headers that will be included in the HTTP request.

### Returns

This function returns a value of type `UploadSession`.

Returns an upload session object.
```

--------------------------------

### Initialize Client with Client Credentials Grant

Source: https://github.com/box/box-python-sdk/blob/main/docs/authentication.md

Initialize a Box client using Client Credentials Grant (CCG) authentication with provided client ID, secret, and user ID. The token is automatically refreshed.

```python
from box_sdk_gen import BoxClient, BoxCCGAuth, CCGConfig

ccg_config = CCGConfig(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    user_id="YOUR_USER_ID",
)
auth = BoxCCGAuth(config=ccg_config)
client = BoxClient(auth=auth)

print(f"Id of the authenticated user is: {client.users.get_user_me().id}")
```

--------------------------------

### Get files under retention

Source: https://github.com/box/box-python-sdk/blob/main/docs/retention_policy_assignments.md

Returns a list of files under retention for a specific retention policy assignment.

```APIDOC
## Get files under retention

Returns a list of files under retention for a retention policy assignment.

### Method
GET

### Endpoint
/retention_policy_assignments/:retention_policy_assignment_id/files_under_retention

### Parameters
#### Path Parameters
- **retention_policy_assignment_id** (string) - Required - The ID of the retention policy assignment. Example: "1233123"

#### Query Parameters
- **marker** (string) - Optional - Defines the position marker at which to begin returning results. This is used when paginating using marker-based pagination. This requires `usemarker` to be set to `true`.
- **limit** (integer) - Optional - The maximum number of items to return per page.

### Response
#### Success Response (200)
- **files** (array) - A list of files under retention.
- **next_marker** (string) - The marker for the next page of results.

### Request Example
```python
client.retention_policy_assignments.get_files_under_retention_policy_assignment(
    retention_policy_assignment.id
)
```
```

--------------------------------

### Get Watermark on File

Source: https://github.com/box/box-python-sdk/blob/main/docs/file_watermarks.md

Retrieve the watermark for a file. This operation is performed by calling the `get_file_watermark` function.

```APIDOC
## Get watermark on file

### Description
Retrieve the watermark for a file.

### Method
GET

### Endpoint
/files/{file_id}/watermark

### Parameters
#### Path Parameters
- **file_id** (str) - Required - The unique identifier that represents a file. Example: "12345"

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
client.file_watermarks.get_file_watermark(file.id)
```

### Response
#### Success Response (200)
- **watermark** (Watermark) - Information about the watermark associated with the file.

#### Response Example
```json
{
  "watermark": {
    "imprint": "default"
  }
}
```
```

--------------------------------

### Get comment

Source: https://github.com/box/box-python-sdk/blob/main/docs/comments.md

Retrieves the message and metadata for a specific comment, including information about the user who created it.

```APIDOC
## GET /comments/:comment_id

### Description
Retrieves the message and metadata for a specific comment, as well as information on the user who created the comment.

### Method
GET

### Endpoint
/comments/:comment_id

### Parameters
#### Path Parameters
- **comment_id** (str) - Required - The ID of the comment. Example: "12345"

#### Query Parameters
- **fields** (Optional[List[str]]) - A comma-separated list of attributes to include in the response.

### Request Example
```python
client.comments.get_comment_by_id(new_comment.id)
```

### Returns
#### Success Response (200)
- **CommentFull** - Returns a full comment object.
```

--------------------------------

### Use Proxy for API Calls with Client

Source: https://github.com/box/box-python-sdk/blob/main/docs/client.md

Create a new client instance that routes API calls through a specified proxy. Supports HTTP/S proxies with basic authentication. The original client remains unmodified, and username/password are optional.

```python
new_client = client.with_proxy(
    ProxyConfig(url="http://proxy.com", username="username", password="password")
)
```

--------------------------------

### Create Slack Integration Mapping

Source: https://github.com/box/box-python-sdk/blob/main/docs/integration_mappings.md

Creates a Slack integration mapping by linking a Slack channel to a Box item. Requires Admin or Co-Admin role. Use this to establish a new connection between Slack and Box.

```python
user_client.integration_mappings.create_slack_integration_mapping(
    IntegrationMappingPartnerItemSlack(
        id=slack_partner_item_id, slack_org_id=slack_org_id
    ),
    IntegrationMappingBoxItemSlack(id=folder.id),
)
```

--------------------------------

### Get collection by ID

Source: https://github.com/box/box-python-sdk/blob/main/docs/collections.md

Retrieves a collection by its ID. This operation is performed by calling the `get_collection_by_id` function.

```APIDOC
## Get collection by ID

### Description
Retrieves a collection by its ID.

### Method
GET

### Endpoint
/collections/{collection_id}

### Parameters
#### Path Parameters
- **collection_id** (str) - Required - The ID of the collection. Example: "926489"

#### Query Parameters
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Optional - Extra headers that will be included in the HTTP request.

### Request Example
```python
client.collections.get_collection_by_id(collections.entries[0].id)
```

### Response
#### Success Response (200)
- **collection** (Collection) - Returns the specified collection.

#### Response Example
{
  "type": "collection",
  "id": "12345",
  "name": "Favorites"
}
```

--------------------------------

### Make Custom Multi-part HTTP Request

Source: https://github.com/box/box-python-sdk/blob/main/docs/client.md

Use `client.make_request()` with `FetchOptions` for multipart requests, such as uploading files. Specify `content_type` as `"multipart/form-data"` and provide `multipart_data` as a list of `MultipartItem` objects.

```python
from box_sdk_gen import FetchResponse, FetchOptions, MultipartItem

response: FetchResponse = client.make_request(
    FetchOptions(
        method="POST",
        url="https://upload.box.com/api/2.0/files/content",
        content_type="multipart/form-data",
        multipart_data=[
            MultipartItem(
                part_name="attributes",
                data={"name": "new_folder_name", "parent": {"id": "0"}},
            ),
            MultipartItem(part_name="file", file_stream=open("file.txt", "rb")),
        ],
    )
)
print("Received status code: ", response.status)
```

--------------------------------

### Get Collaboration by ID

Source: https://github.com/box/box-python-sdk/blob/main/docs/user_collaborations.md

Retrieves a single collaboration by its ID. You can also specify which fields to include in the response.

```APIDOC
## GET /collaborations/{collaboration_id}

### Description
Retrieves a single collaboration.

### Method
GET

### Endpoint
/collaborations/{collaboration_id}

### Parameters
#### Path Parameters
- **collaboration_id** (str) - Required - The ID of the collaboration.

#### Query Parameters
- **fields** (Optional[List[str]]) - Optional - A comma-separated list of attributes to include in the response.
- **extra_headers** (Optional[Dict[str, Optional[str]]]) - Optional - Extra headers that will be included in the HTTP request.

### Response
#### Success Response (200)
- **Collaboration** - Returns a collaboration object.
```

--------------------------------

### Get Collaboration by ID

Source: https://github.com/box/box-python-sdk/blob/main/docs/user_collaborations.md

Retrieves a specific collaboration using its ID. Useful for checking collaboration details.

```python
client.user_collaborations.get_collaboration_by_id(collaboration_id)
```

--------------------------------

### List All Global Metadata Templates

Source: https://github.com/box/box-python-sdk/blob/main/docs/metadata_templates.md

Fetches all generic, global metadata templates available across all enterprises. Useful for discovering available standard templates.

```python
client.metadata_templates.get_global_metadata_templates()
```

--------------------------------

### Create New Client with User Subject (Box SDK Gen)

Source: https://github.com/box/box-python-sdk/blob/main/migration-guides/from-boxsdk-to-box_sdk_gen.md

In box_sdk_gen, use with_user_subject to get a new auth instance for a user. This new instance is immutable and fetches a new token on the next API call. A new BoxClient can then be created with this new auth instance. The token_storage parameter can be specified to provide a custom token storage for the new instance.

```python
from box_sdk_gen import BoxCCGAuth, BoxClient

user_auth: BoxCCGAuth = auth.with_user_subject(user_id="USER_ID")
user_client: BoxClient = BoxClient(auth=user_auth)
```

--------------------------------

### Get All Shield Lists in Enterprise

Source: https://github.com/box/box-python-sdk/blob/main/docs/shield_lists.md

Retrieves all shield lists present in the enterprise. This function requires the BoxVersionHeaderV2025R0.

```python
client.shield_lists.get_shield_lists_v2025_r0()
```