### Install mvsdk Package

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Install the MediaValet SDK using pip. This command is used to add the library to your Python environment.

```bash
pip install mvsdk
```

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

### Get Keyword

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves keywords. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get keyword
keyword = sdk_handle.keyword.get(
	auth=access_token
)
```

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

### Get Asset Renditions

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Fetches the available renditions for a given asset.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get asset renditions
renditions = sdk_handle.asset.get_renditions(
	auth=access_token,
	object_id=asset_id
)
```

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

### Get Asset Keywords

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves the keywords associated with a specific asset.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get asset keywords
keywords = sdk_handle.asset.get_keywords(
	auth=access_token,
	object_id=asset_id
)
```

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

### Get All Users

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves a list of all users. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get all users
users = sdk_handle.user.get_all(
	auth=access_token
)
```

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

### Use Batch Endpoint for Multiple Requests

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

This example shows how to use the MediaValet SDK's batch endpoint to send multiple commands in a single API call. This is useful for optimizing performance by reducing the number of individual requests.

```python
import mvsdk
from mvsdk.rest.bulk import BulkRequest, BulkResponse

import json

# Set Authentication Variables
auth_url: str = ""
base_url: str = ""
username: str = ""
password: str = ""
client_id: str = ""
client_secret: str = ""

# Set AssetId to be interacted with
asset_id: str = ""

# Open an MVSDK handle
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
    }

auth = {
        "client_id": client_id,
        "client_secret": client_secret
    }

session = sdk_handle.connect.auth(data=data, auth=auth)

# Get the asset specific metadata
asset_metadata = sdk_handle.asset.get(auth=session.access_token, object_id=asset_id)

# Get all instance metadata
existing_attributes = sdk_handle.attribute.get(auth=session.access_token)

# Map asset metadata to human readable metadata names
attributes = {}

for attribute_id in asset_metadata.json()["payload"]["attributes"]:
    attributes[existing_attributes[attribute_id]] = asset_metadata.json()["payload"]["attributes"][attribute_id]

# Build the BulkRequest
bulk_request = BulkRequest()

get_attribute_request = sdk_handle.asset.get_attributes(object_id=asset_id, bulk=True)

bulk_request.add_request(get_attribute_request)

# Send the BulkRequest object to the bulk handle
request = bulk_request.get_payload()

response = sdk_handle.bulk.post(
    headers=request["headers"], data=request["payload"], auth=session.access_token
)

bulk_response =  BulkResponse(response)
    
# Present the result
for response in bulk_response.get_response:
    print(f"Attributes for asset {asset_id}:\n{json.dumps(response, indent=4)}")

```

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

### Get Asset History

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves the history log for a specific asset.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get the asset history
history = sdk_handle.asset.get_history(
	auth=access_token,
	object_id=asset_id
)
```

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

### Asset API - Get Renditions

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieve available renditions (different sizes/formats) for an asset.

```APIDOC
## Asset API - Get Renditions

### Description
Retrieve available renditions (different sizes/formats) for an asset.

### Method
GET

### Endpoint
/api/asset/{object_id}/renditions

### Parameters
#### Path Parameters
- **object_id** (string) - Required - The unique identifier of the asset.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

renditions = sdk_handle.asset.get_renditions(
    auth=access_token,
    object_id=asset_id
)

print(renditions.json())
```

### Response
#### Success Response (200)
- **payload** (object) - Contains a list of renditions for the asset.
  - **name** (string) - The name of the rendition (e.g., 'thumbnail', 'web-optimized').
  - **width** (integer) - The width of the rendition in pixels.
  - **height** (integer) - The height of the rendition in pixels.
  - **url** (string) - The URL to access the rendition.

#### Response Example
```json
{
  "payload": [
    {
      "name": "thumbnail",
      "width": 150,
      "height": 100,
      "url": "/renditions/thumbnail/asset.jpg"
    },
    {
      "name": "web-optimized",
      "width": 1280,
      "height": 720,
      "url": "/renditions/web-optimized/asset.mp4"
    }
  ]
}
```
```

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

### Get Asset Categories

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves the categories associated with a specific asset.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get the assets categories
categories = sdk_handle.asset.get_categories(
	auth=access_token,
	object_id=asset_id
)
```

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

### Get Keyword Group

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves keyword groups. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get keyword group
keyword_group = sdk_handle.keyword_group.get(
	auth=access_token
)
```

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

### Get All Approvers

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves a list of all approvers. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get all approvers
approvers = sdk_handle.user.get_approvers(
	auth=access_token
)
```

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

### Build and Execute Bulk GET Requests

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Use `BulkRequest` to add multiple `get_attributes` calls and `BulkResponse` to process the results. Ensure `bulk=True` is passed to `get_attributes` to retrieve request data instead of executing immediately.

```python
import mvsdk
from mvsdk.rest.bulk import BulkRequest, BulkResponse
import json

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# List of asset IDs to process
asset_ids = [
    "asset-uuid-1",
    "asset-uuid-2",
    "asset-uuid-3"
]

# Create a bulk request container
bulk_request = BulkRequest()

# Add multiple requests to the batch
for asset_id in asset_ids:
    # Pass bulk=True to get request data instead of executing
    request_data = sdk_handle.asset.get_attributes(
        auth=access_token,
        object_id=asset_id,
        bulk=True  # Returns request dict instead of executing
    )
    bulk_request.add_request(request_data)

# Check how many requests are in the batch
print(f"Batch contains {bulk_request.get_request_count()} requests")

# Get the formatted payload for the bulk endpoint
request = bulk_request.get_payload()

# Send all requests in a single API call
response = sdk_handle.bulk.post(
    headers=request["headers"],
    data=request["payload"],
    auth=access_token
)

# Parse the bulk response
bulk_response = BulkResponse(response)

# Process results using get_response for GET requests
for idx, result in enumerate(bulk_response.get_response):
    if result["status_code"] == "200":
        print(f"Asset {idx + 1}: {json.dumps(result['payload'], indent=2)}")
    else:
        print(f"Asset {idx + 1} Error: {result['status_message']}")
```

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

### Asset API - Get History

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieve the activity history for a specific asset.

```APIDOC
## Asset API - Get History

### Description
Retrieve the activity history for a specific asset.

### Method
GET

### Endpoint
/api/asset/{object_id}/history

### Parameters
#### Path Parameters
- **object_id** (string) - Required - The unique identifier of the asset.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

history = sdk_handle.asset.get_history(
    auth=access_token,
    object_id=asset_id
)

print(history.json())
```

### Response
#### Success Response (200)
- **payload** (object) - Contains a list of historical events for the asset.
  - **action** (string) - The type of action performed (e.g., 'view', 'edit', 'delete').
  - **timestamp** (string) - The date and time the action occurred.
  - **user** (string) - The user who performed the action.

#### Response Example
```json
{
  "payload": [
    {
      "action": "view",
      "timestamp": "2024-01-15T09:00:00Z",
      "user": "johndoe"
    },
    {
      "action": "edit",
      "timestamp": "2024-01-15T09:15:00Z",
      "user": "admin"
    }
  ]
}
```
```

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

### Get Asset Renditions with Python SDK

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieves available renditions (different sizes/formats) for a specific asset. Requires authentication and asset ID.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

# Get asset renditions
renditions = sdk_handle.asset.get_renditions(
    auth=access_token,
    object_id=asset_id
)

for rendition in renditions.json()["payload"]:
    print(f"Rendition: {rendition['name']} - {rendition['width']}x{rendition['height']}")
```

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

### Get All User Groups

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves a list of all user groups. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get all user groups

```

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

### Get Asset Comments

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Fetches comments made on a specific asset.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get comments made on the asset
comments = sdk_handle.asset.get_comments(
	auth=access_token,
	object_id=asset_id
)
```

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

### Asset API - Get Categories

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieve the categories assigned to a specific asset.

```APIDOC
## Asset API - Get Categories

### Description
Retrieve the categories assigned to a specific asset.

### Method
GET

### Endpoint
/api/asset/{object_id}/categories

### Parameters
#### Path Parameters
- **object_id** (string) - Required - The unique identifier of the asset.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

categories = sdk_handle.asset.get_categories(
    auth=access_token,
    object_id=asset_id
)

print(categories.json())
```

### Response
#### Success Response (200)
- **payload** (object) - Contains a list of categories associated with the asset.
  - **name** (string) - The name of the category.
  - **path** (string) - The hierarchical path of the category.

#### Response Example
```json
{
  "payload": [
    {
      "name": "Marketing",
      "path": "/Categories/Marketing"
    },
    {
      "name": "Product",
      "path": "/Categories/Products/New"
    }
  ]
}
```
```

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

### Get Asset History with Python SDK

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieves the activity history for a specific asset. Requires authentication and asset ID.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

# Get asset history
history = sdk_handle.asset.get_history(
    auth=access_token,
    object_id=asset_id
)

for event in history.json()["payload"]:
    print(f"Event: {event['action']} at {event['timestamp']}")
```

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

### Asset API - Get Comments

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieve comments made on a specific asset.

```APIDOC
## Asset API - Get Comments

### Description
Retrieve comments made on a specific asset.

### Method
GET

### Endpoint
/api/asset/{object_id}/comments

### Parameters
#### Path Parameters
- **object_id** (string) - Required - The unique identifier of the asset.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

comments = sdk_handle.asset.get_comments(
    auth=access_token,
    object_id=asset_id
)

print(comments.json())
```

### Response
#### Success Response (200)
- **payload** (object) - Contains a list of comments for the asset.
  - **author** (string) - The username of the comment author.
  - **text** (string) - The content of the comment.
  - **timestamp** (string) - The date and time the comment was posted.

#### Response Example
```json
{
  "payload": [
    {
      "author": "johndoe",
      "text": "Great asset, very useful!",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  ]
}
```
```

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

### Get Current User Permissions

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves the permissions for the current user. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get current user permissions
current_user_permissions = sdk_handle.user.get_current_permissions(
	auth=access_token
)
```

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

### Get Video Intelligence Status with Python SDK

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Checks the video intelligence processing status for video assets. Requires authentication and video asset ID.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

video_asset_id = "12345678-1234-1234-1234-123456789abc"

# Get video intelligence status
vi_status = sdk_handle.asset.get_video_intelligence_status(
    auth=access_token,
    object_id=video_asset_id
)

status_data = vi_status.json()["payload"]
print(f"Video Intelligence Status: {status_data['status']}")
```

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

### Get Current User

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves information about the currently authenticated user. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get current user
current_user = sdk_handle.user.get_current(
	auth=access_token
)
```

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

### Asset API - Get Video Intelligence Status

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Check the video intelligence processing status for video assets.

```APIDOC
## Asset API - Get Video Intelligence Status

### Description
Check the video intelligence processing status for video assets.

### Method
GET

### Endpoint
/api/asset/{object_id}/video-intelligence/status

### Parameters
#### Path Parameters
- **object_id** (string) - Required - The unique identifier of the video asset.

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

video_asset_id = "12345678-1234-1234-1234-123456789abc"

vi_status = sdk_handle.asset.get_video_intelligence_status(
    auth=access_token,
    object_id=video_asset_id
)

print(vi_status.json())
```

### Response
#### Success Response (200)
- **payload** (object) - Contains the video intelligence processing status.
  - **status** (string) - The current status (e.g., 'processing', 'completed', 'failed').
  - **progress** (integer) - The processing progress in percentage (0-100).
  - **error_message** (string) - If status is 'failed', this contains the error details.

#### Response Example
```json
{
  "payload": {
    "status": "completed",
    "progress": 100
  }
}
```
```

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

### Get Asset Categories with Python SDK

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieves categories assigned to a specific asset. Requires authentication and asset ID.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

# Get asset categories
categories = sdk_handle.asset.get_categories(
    auth=access_token,
    object_id=asset_id
)

for category in categories.json()["payload"]:
    print(f"Category: {category['name']} (Path: {category['path']})")
```

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

### Get Current Organizational Unit

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves the current organizational unit. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get current org unit
current_org_unit = sdk_handle.org_unit.get_current(
	auth=access_token
)
```

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

### Get Asset Metadata

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Fetches specific metadata attributes for a given asset using its object ID.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get the asset specific metadata
attributes = sdk_handle.asset.get_attributes(
	auth=access_token,
	object_id=asset_id
)
```

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

### Get User Group Information

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves user group information using an access token. Ensure the access token is valid.

```python
renditions = sdk_handle.user_group.get(
	auth=access_token
)
```

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

### Get Asset Comments with Python SDK

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieves comments made on a specific asset. Requires authentication and asset ID.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

# Get asset comments
comments = sdk_handle.asset.get_comments(
    auth=access_token,
    object_id=asset_id
)

for comment in comments.json()["payload"]:
    print(f"Comment by {comment['author']}: {comment['text']}")
```

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

### SDK Handle Initialisation

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Initializes the SDK handle and establishes a session for interacting with the MediaValet API.

```APIDOC
## SDK Handle Initialisation

### Description
In order to interact with any SDK endpoint, you first need to initialise a session. An example of how to do this simply would be as follows:

### Method
N/A (Initialization)

### Endpoint
N/A (Initialization)

### Request Body
```python
import mvsdk

# Set Authentication Variables
auth_url: str = ""
base_url: str = ""
username: str = ""
password: str = ""
client_id: str = ""
client_secret: str = ""

# Open an MVSDK handle
 sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
    }

auth = {
        "client_id": client_id,
        "client_secret": client_secret
    }

session = sdk_handle.connect.auth(data=data, auth=auth)
```

Once you have initialised the `sdk_handle` and `session` variable, you must use that authenticated token in all calls to the SDK.
```

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

### Initialize SDK Handle and Session

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Initializes the SDK handle and establishes an authenticated session using provided credentials. Ensure all authentication variables are correctly set before execution.

```Python
import mvsdk

# Set Authentication Variables
auth_url: str = ""
base_url: str = ""
username: str = ""
password: str = ""
client_id: str = ""
client_secret: str = ""

# Open an MVSDK handle
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
    }

auth = {
        "client_id": client_id,
        "client_secret": client_secret
    }

session = sdk_handle.connect.auth(data=data, auth=auth)
```

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

### Initialize and Authenticate Client

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Configure the client with API credentials and perform an OAuth2 password grant authentication.

```python
import mvsdk

# Set Authentication Variables (available in your MediaValet API dashboard)
auth_url = "login.mediavalet.com"
base_url = "mv-api-usva.mediavalet.net"
username = "your_username"
password = "your_password"
client_id = "your_client_id"
client_secret = "your_client_secret"

# Initialize the SDK client
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet using OAuth2 password grant
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
}

auth = {
    "client_id": client_id,
    "client_secret": client_secret
}

# Get session with access token
session = sdk_handle.connect.auth(data=data, auth=auth)

# Use session.access_token for all subsequent API calls
print(f"Authenticated! Token: {session.json()['access_token'][:20]}...")
```

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

### Retrieve Asset Details and Download

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Fetch asset metadata and download the associated file using the asset ID.

```python
import mvsdk
import requests

# Initialize and authenticate (see above)
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)

asset_id = "12345678-1234-1234-1234-123456789abc"

# Get asset details including download URL
response = sdk_handle.asset.get(
    auth=session.json()["access_token"],
    object_id=asset_id
)

asset_data = response.json()
print(f"Asset Title: {asset_data['payload']['title']}")
print(f"File Type: {asset_data['payload']['file']['fileType']}")

# Download the asset file
download_url = asset_data["payload"]["media"]["download"]
file_response = requests.get(download_url)

try:
    with open("downloaded_asset.jpg", "wb") as file:
        for chunk in file_response.iter_content(1024):
            file.write(chunk)
    print("Asset downloaded successfully!")
except IOError as e:
    print(f"Could not write file: {e}")
```

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

### Manage Direct Links using Python

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Handles creation, retrieval, and export of direct links for external asset sharing. Requires authentication and asset IDs for creation.

```python
import mvsdk
import json

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Get all direct links
direct_links = sdk_handle.direct_link.get(auth=access_token)

for link in direct_links.json()["payload"]:
    print(f"Direct Link: {link['url']}")

# Create a new direct link
new_link = sdk_handle.direct_link.create(
    auth=access_token,
    data=json.dumps({
        "assetIds": ["asset-uuid-1", "asset-uuid-2"],
        "expirationDate": "2024-12-31"
    })
)

print(f"Created direct link: {new_link.json()['payload']['url']}")

# Export direct links data
export_data = sdk_handle.direct_link.export(
    auth=access_token,
    stream=True
)

with open("direct_links_export.csv", "wb") as f:
    for chunk in export_data.iter_content(1024):
        f.write(chunk)
```

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

### Manage Users using Python

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Provides functions to retrieve all users, the current authenticated user, their permissions, and users who can approve assets. Requires authentication.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Get all users
users = sdk_handle.user.get_all(auth=access_token)

for user in users.json()["payload"]:
    print(f"User: {user['email']} - {user['firstName']} {user['lastName']}")

# Get current authenticated user
current_user = sdk_handle.user.get_current(auth=access_token)
print(f"Current user: {current_user.json()['payload']['email']}")

# Get current user's permissions
permissions = sdk_handle.user.get_current_permissions(auth=access_token)
print(f"Permissions: {permissions.json()['payload']}")

# Get users who can approve assets
approvers = sdk_handle.user.get_approvers(auth=access_token)
for approver in approvers.json()["payload"]:
    print(f"Approver: {approver['email']}")
```

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

### Create Keyword

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Creates a new keyword. Requires an authenticated access token.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Create keyword
self.sdk_handle.keyword.create(
	auth=access_token,
	data="example"
)
```

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

### Manage Asset Keywords with Python SDK

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Handles creation, retrieval, and deletion of keywords for an asset. Supports synchronous and asynchronous keyword addition.

```python
import mvsdk
import json

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

# Add keywords to an asset (synchronous)
sdk_handle.asset.create_keywords(
    auth=access_token,
    object_id=asset_id,
    data=json.dumps(["marketing", "product-launch", "2024"])
)

# Add keywords asynchronously for better performance on large batches
sdk_handle.asset.create_keywords(
    auth=access_token,
    object_id=asset_id,
    data=json.dumps(["async-keyword1", "async-keyword2"]),
    sync=False  # Runs with low priority asynchronously
)

# Get asset keywords
keywords = sdk_handle.asset.get_keywords(
    auth=access_token,
    object_id=asset_id
)

print(f"Keywords: {keywords.json()['payload']}")

# Delete a keyword from an asset
sdk_handle.asset.delete_keyword(
    auth=access_token,
    object_id=asset_id,
    data=json.dumps("marketing")
)
```

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

### Manage Keywords using Python

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Provides functionality to retrieve and create global keywords. Authentication is required.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Get all keywords
keywords = sdk_handle.keyword.get(auth=access_token)

for keyword in keywords.json()["payload"]:
    print(f"Keyword: {keyword['name']}")

# Create a new keyword
sdk_handle.keyword.create(
    auth=access_token,
    data="example-keyword"
)
```

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

### Build and Execute Bulk POST Requests

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

For bulk POST operations, construct requests using `BulkRequest` and parse responses with `BulkResponse.post_response`. Ensure `bulk=True` is used when generating individual request data.

```python
import mvsdk
from mvsdk.rest.bulk import BulkRequest, BulkResponse
import json

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Create bulk request for adding keywords to multiple assets
bulk_request = BulkRequest()

assets_keywords = [
    {"asset_id": "asset-uuid-1", "keywords": ["marketing", "campaign"]},
    {"asset_id": "asset-uuid-2", "keywords": ["product", "launch"]},
]

for item in assets_keywords:
    request_data = sdk_handle.asset.create_keywords(
        auth=access_token,
        object_id=item["asset_id"],
        data=json.dumps(item["keywords"]),
        bulk=True
    )
    bulk_request.add_request(request_data)

request = bulk_request.get_payload()

response = sdk_handle.bulk.post(
    headers=request["headers"],
    data=request["payload"],
    auth=access_token
)

bulk_response = BulkResponse(response)

# Use post_response for POST/write operations
for idx, result in enumerate(bulk_response.post_response):
    print(f"Operation {idx + 1}: {result['status_code']} - {result['status_message']}")
```

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

### Manage Keyword Groups using Python

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Enables retrieval and creation of keyword groups for organizing keywords. Requires authentication.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Get all keyword groups
keyword_groups = sdk_handle.keyword_group.get(auth=access_token)

for group in keyword_groups.json()["payload"]:
    print(f"Keyword Group: {group['name']} (Members: {group['memberCount']})")

# Create a new keyword group
sdk_handle.keyword_group.create(
    auth=access_token,
    data="Products"
)
```

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

### Retrieve Assets by Category using Python

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Fetches all assets belonging to a specific category. Requires authentication and a valid category ID.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

category_id = "category-uuid-here"

# Get all assets in a category
category_assets = sdk_handle.category.get_assets(
    auth=access_token,
    object_id=category_id
)

for asset in category_assets.json()["payload"]:
    print(f"Asset in category: {asset['title']}")
```

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

### Authenticate and Fetch Asset Metadata

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

This snippet demonstrates how to authenticate with the MediaValet API and retrieve metadata for a specific asset. Ensure all authentication variables are correctly set.

```python
import mvsdk
import json

# Set Authentication Variables
# These variables are available in your API dashboard
auth_url: str = ""
base_url: str = ""
username: str = ""
password: str = ""
client_id: str = ""
client_secret: str = ""

# Set AssetId to be interacted with
asset_id: str = ""

# Open an MVSDK handle
sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)

# Authenticate to MediaValet
data = {
    "grant_type": "password",
    "username": username,
    "password": password,
    "scope": "openid api offline_access",
    }

auth = {
        "client_id": client_id,
        "client_secret": client_secret
    }

session = sdk_handle.connect.auth(data=data, auth=auth)

# Get the asset specific metadata
asset_metadata = sdk_handle.asset.get(auth=session.access_token, object_id=asset_id)

# Get all instance metadata
existing_attributes = sdk_handle.attribute.get(auth=session.access_token)

# Map asset metadata to human readable metadata names
attributes = {}

for attribute_id in asset_metadata.json()["payload"]["attributes"]:
    attributes[existing_attributes[attribute_id]] = asset_metadata.json()["payload"]["attributes"][attribute_id]

# Present the result
print(f"Attributes for asset {asset_id}:\n{json.dumps(attributes, indent=4)}")
```

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

### Retrieve Organizational Unit Information using Python

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Fetches details about the current organizational unit, including its name and ID. Requires authentication.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Get current organizational unit
current_org = sdk_handle.org_unit.get_current(auth=access_token)

org_data = current_org.json()["payload"]
print(f"Organization: {org_data['name']}")
print(f"Org ID: {org_data['id']}")
```

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

### Keyword API

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Manage global keywords in your MediaValet instance.

```APIDOC
## Keyword API

### Description
Manage global keywords in your MediaValet instance.

### Method
GET, POST

### Endpoint
/api/keyword

### Parameters
#### Query Parameters
None

#### Request Body (for POST)
- **keyword** (string) - Required - The name of the keyword to create.

### Request Example
```python
# Get all keywords
keywords = sdk_handle.keyword.get(auth=access_token)

# Create a new keyword
sdk_handle.keyword.create(auth=access_token, data="example-keyword")
```

### Response
#### Success Response (200)
- **payload** (array) - A list of keywords.
  - **name** (string) - The name of the keyword.

#### Response Example
```json
{
  "payload": [
    { "name": "Keyword 1" },
    { "name": "Keyword 2" }
  ]
}
```
```

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

### Manage Attribute Definitions with Python SDK

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Manages custom metadata attribute definitions. Includes retrieving all definitions and creating new ones.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Get all attribute definitions
attributes = sdk_handle.attribute.get(auth=access_token)

for attr_id, attr_data in attributes.json()["payload"].items():
    print(f"Attribute: {attr_data['name']} (ID: {attr_id})")

# Create a new attribute
new_attribute = sdk_handle.attribute.create(
    auth=access_token,
    data="name=Copyright&type=text"
)

print(f"Created attribute: {new_attribute.json()}")
```

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

### Add Keywords to Asset

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Adds a list of keywords to a specified asset.

```Python
import mvsdk

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Add keywords to an asset
sdk_handle.asset.create_keywords(
	auth=access_token,
	object_id=asset_id,
	data=["example1", "example2"]
)
```

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

### Asset API - Manage Keywords

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Create, retrieve, and delete keywords on assets. Keywords can be added synchronously or asynchronously for large operations.

```APIDOC
## Asset API - Manage Keywords

### Description
Create, retrieve, and delete keywords on assets. Keywords can be added synchronously or asynchronously for large operations.

### Methods
- **Create Keywords**: POST /api/asset/{object_id}/keywords
- **Get Keywords**: GET /api/asset/{object_id}/keywords
- **Delete Keyword**: DELETE /api/asset/{object_id}/keywords

### Parameters
#### Path Parameters
- **object_id** (string) - Required - The unique identifier of the asset.

#### Query Parameters
None

#### Request Body
- **data** (string) - Required - A JSON string representing an array of keywords to add or a single keyword to delete.
- **sync** (boolean) - Optional - If `false`, the operation runs asynchronously. Defaults to `true`.

### Request Examples
#### Add Keywords (Synchronous)
```python
import mvsdk
import json

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

sdk_handle.asset.create_keywords(
    auth=access_token,
    object_id=asset_id,
    data=json.dumps(["marketing", "product-launch", "2024"])
)
```

#### Add Keywords (Asynchronous)
```python
import mvsdk
import json

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

sdk_handle.asset.create_keywords(
    auth=access_token,
    object_id=asset_id,
    data=json.dumps(["async-keyword1", "async-keyword2"]),
    sync=False
)
```

#### Get Keywords
```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

keywords = sdk_handle.asset.get_keywords(
    auth=access_token,
    object_id=asset_id
)

print(keywords.json())
```

#### Delete Keyword
```python
import mvsdk
import json

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

asset_id = "12345678-1234-1234-1234-123456789abc"

sdk_handle.asset.delete_keyword(
    auth=access_token,
    object_id=asset_id,
    data=json.dumps("marketing")
)
```

### Response
#### Success Response (200)
- **payload** (object) - Contains a list of keywords associated with the asset.

#### Response Example (Get Keywords)
```json
{
  "payload": [
    "marketing",
    "product-launch",
    "2024"
  ]
}
```
```

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

### Direct Link API

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Create and manage direct links for sharing assets externally.

```APIDOC
## Direct Link API

### Description
Create and manage direct links for sharing assets externally.

### Method
GET, POST, GET (export)

### Endpoint
/api/direct-link

### Parameters
#### Query Parameters (for GET)
None

#### Request Body (for POST)
- **assetIds** (array of strings) - Required - IDs of the assets to include in the direct link.
- **expirationDate** (string) - Optional - The expiration date for the link in YYYY-MM-DD format.

### Request Example
```python
# Get all direct links
direct_links = sdk_handle.direct_link.get(auth=access_token)

# Create a new direct link
new_link = sdk_handle.direct_link.create(
    auth=access_token,
    data=json.dumps({
        "assetIds": ["asset-uuid-1", "asset-uuid-2"],
        "expirationDate": "2024-12-31"
    })
)

# Export direct links data
export_data = sdk_handle.direct_link.export(auth=access_token, stream=True)
```

### Response
#### Success Response (200)
- **payload** (array) - A list of direct links (for GET).
  - **url** (string) - The direct link URL.
- **payload** (object) - Details of the created direct link (for POST).
  - **url** (string) - The direct link URL.

#### Response Example
```json
{
  "payload": [
    { "url": "http://example.com/link1" },
    { "url": "http://example.com/link2" }
  ]
}
```
```json
{
  "payload": {
    "url": "http://example.com/newlink"
  }
}
```
```

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

### Download Asset

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Retrieves an asset using its object ID and saves it to a local file. Includes error handling for file writing operations.

```Python
import mvsdk
import requests

# Initialise the sdk_handle and session token.
sdk_handle = ...
session = ...

# Get(/download) an asset 
response = sdk_handle.asset.get(
	auth=session.access_token,
	object_id=asset_id
)

file_response = requests.get(response.json()["payload"]["media"]["download"])

try:
	with open("example_filename", "wb") as file:
		for data in file_response.iter_content(1024):
			file.write(data)
except IOError:
	print(f"Could not write file. Please check write permissions and try again.")
```

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

### Manage User Groups using Python

Source: https://context7.com/armstro-ca/mvsdk/llms.txt

Retrieves information about user groups, including their names and member counts. Requires authentication.

```python
import mvsdk

sdk_handle = mvsdk.rest.Client(auth_url=auth_url, base_url=base_url)
session = sdk_handle.connect.auth(data=data, auth=auth)
access_token = session.json()["access_token"]

# Get all user groups
user_groups = sdk_handle.user_group.get(auth=access_token)

for group in user_groups.json()["payload"]:
    print(f"User Group: {group['name']} (Members: {group['memberCount']})")
```

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

### Asset API

Source: https://github.com/armstro-ca/mvsdk/blob/main/README.md

Provides functionality to interact with digital assets, including downloading, retrieving metadata, comments, history, keywords, and renditions.

```APIDOC
## Asset API

### Description
The Asset method provides the user with the ability to directly interact with the asset. As MediaValet is a Digital Asset Management tool, by far the majority of the functionality and endpoints are based around the asset itself.

### Method
GET, POST

### Endpoint
/asset

### Parameters
#### Path Parameters
- **asset_id** (string) - Required - The unique identifier of the asset.

#### Query Parameters
None

#### Request Body
None for GET operations. For POST operations (e.g., create_keywords), refer to specific method documentation.

### Request Example
```python
# Get(/download) an asset
response = sdk_handle.asset.get(
	auth=session.access_token,
	object_id=asset_id
)

file_response = requests.get(response.json()["payload"]["media"]["download"])

try:
	with open("example_filename", "wb") as file:
		for data in file_response.iter_content(1024):
			file.write(data)
except IOError:
	print(f"Could not write file. Please check write permissions and try again.")

# Get the asset specific metadata
attributes = sdk_handle.asset.get_attributes(
	auth=access_token,
	object_id=asset_id
)

# Get the assets categories
categories = sdk_handle.asset.get_categories(
	auth=access_token,
	object_id=asset_id
)

# Get comments made on the asset
comments = sdk_handle.asset.get_comments(
	auth=access_token,
	object_id=asset_id
)

# Get the asset history
history = sdk_handle.asset.get_history(
	auth=access_token,
	object_id=asset_id
)

# Add keywords to an asset
sdk_handle.asset.create_keywords(
	auth=access_token,
	object_id=asset_id,
	data=["example1", "example2"]
)

# Get asset keywords
keywords = sdk_handle.asset.get_keywords(
	auth=access_token,
	object_id=asset_id
)

# Get asset renditions
renditions = sdk_handle.asset.get_renditions(
	auth=access_token,
	object_id=asset_id
)
```

### Response
#### Success Response (200)
- **payload** (object) - Contains asset-related data, including download URLs.
- **media** (object) - Contains media specific information, including download link.
- **download** (string) - URL to download the asset.
- **attributes** (object) - Metadata attributes of the asset.
- **categories** (array) - List of categories the asset belongs to.
- **comments** (array) - List of comments made on the asset.
- **history** (array) - History of changes made to the asset.
- **keywords** (array) - List of keywords associated with the asset.
- **renditions** (array) - List of available renditions for the asset.

#### Response Example
```json
{
  "payload": {
    "media": {
      "download": "https://example.com/download/asset_id"
    }
  }
}
```
```