Working with assets

​

Overview

Assets are a core entity in the Mudstack API, representing files and their associated metadata within a workspace. Each asset belongs to a workspace and cannot be accessed without specifying the appropriate headers in every request:

• x-workspace-id: The unique identifier of the workspace.
• x-account-id: The unique identifier of the account associated with the workspace.

Assets are highly flexible and include several sub-entities that provide additional functionality and metadata. Below is a detailed explanation of the key elements of an asset and how to interact with them using the Mudstack API.

---

​

Key Elements of an Asset

​

1. Versions

Asset versions represent different iterations of an asset. Each version contains metadata such as its name, description, size, checksum, and more. Versions allow you to track changes and manage updates to an asset over time.

​

Endpoints:

• Get all versions of an asset: GET /workspaces/assets/{asset_id}/versions
• Get a specific version: GET /workspaces/assets/{asset_id}/versions/{version_id}
• Create a new version: POST /workspaces/assets/{asset_id}/versions
• Update a version: PATCH /workspaces/assets/{asset_id}/versions/{version_id}
• Delete a version: DELETE /workspaces/assets/{asset_id}/versions/{version_id}
• Restore a deleted version: PATCH /workspaces/assets/{asset_id}/versions/{version_id}/restore
• Download a version: GET /workspaces/assets/{asset_id}/versions/{version_id}/download

---

​

2. Tags

Tags are used to categorize and organize assets. They can be applied to assets to make them easier to search and filter.

​

Endpoints:

• Retrieve tags for an asset: GET /workspaces/assets/{asset_id}/tags
• Add tags to an asset: POST /workspaces/assets/{asset_id}/tags
• Retrieve a specific tag: GET /workspaces/assets/{asset_id}/tags/{tag_id}
• Add a specific tag: POST /workspaces/assets/{asset_id}/tags/{tag_id}
• Remove a specific tag: DELETE /workspaces/assets/{asset_id}/tags/{tag_id}

---

​

3. Tasks

Tasks allow you to assign work related to an asset. Tasks can include details such as title, description, priority, and status.

​

Endpoints:

• Get tasks for an asset: GET /workspaces/assets/{asset_id}/tasks

---

​

4. Comments

Comments provide a way to add notes or feedback to an asset. Comments can include mentions of other users and attachments.

​

Endpoints:

• Add a comment to an asset: POST /workspaces/assets/{asset_id}/comments
• Get comments for an asset: GET /workspaces/assets/{asset_id}/comments
• Get a specific comment: GET /workspaces/assets/{asset_id}/comments/{comment_id}
• Update comment: PUT /workspaces/assets/{asset_id}/comments/{comment_id}
• Delete comment: DELETE /workspaces/assets/{asset_id}/comments/{comment_id}

---

​

5. Reviews

Reviews allow you to provide feedback on an asset. Change requests can be assigned to specific users and will appear in their dashboard.

​

Endpoints:

• Create a new review: POST /workspaces/assets/{asset_id}/reviews
• Get all reviews for an asset: GET /workspaces/assets/{asset_id}/reviews
• Get a specific review: GET /workspaces/assets/{asset_id}/reviews/{review_id}
• Update a review: PUT /workspaces/assets/{asset_id}/reviews/{review_id}
• Delete a review: DELETE /workspaces/assets/{asset_id}/reviews/{review_id}

---

​

5. Review Requests

Review Requests allow you to request feedback from a specific user for an asset. These review requests are tied to the “current version” of an asset, and will be refreshed whenever the “current version” of an asset is changed.

​

Endpoints:

• Create a review request: POST /workspaces/assets/{asset_id}/reviewRequests/{user_id}
• Get review requests for an asset: GET /workspaces/assets/{asset_id}/reviewRequests
• Update a review request: PUT /workspaces/assets/{asset_id}/reviewRequests/{user_id}
• Delete a review request: DELETE /workspaces/assets/{asset_id}/reviewRequests/{user_id}

---

​

6. History

The history of an asset provides a record of actions performed on the asset, such as creation, updates, and deletions.

​

Endpoints:

• Get asset history: GET /workspaces/assets/{asset_id}/history
• Get asset review history: GET /workspaces/assets/{asset_id}/history/review

---

​

General Asset Management

​

Create or Update an Asset

• Endpoint: POST /workspaces/assets
• Description: Creates a new asset or updates an existing one.

​

Delete an Asset

• Endpoint: DELETE /workspaces/assets
• Description: Deletes assets either permanently or soft deletes them.

​

Get Asset by ID

• Endpoint: GET /workspaces/assets/{asset_id}
• Description: Retrieves an asset.

​

Update Asset by ID

• Endpoint: PUT /workspaces/assets/{asset_id}
• Description: Updates an asset.

​

Restore a Soft-Deleted Asset

• Endpoint: PATCH /workspaces/assets/{asset_id}/restore
• Description: Restores a soft-deleted asset.

​

Download an Asset

• Endpoint: GET /workspaces/assets/{asset_id}/download
• Description: Downloads an asset.

---

​

Headers Required for All Requests

• x-workspace-id: The workspace ID to which the asset belongs.
• x-account-id: The account ID associated with the workspace.

Ensure these headers are included in every request to interact with assets and their sub-entities.