Core Concepts
Working with assets
Learn how to manage assets, their metadata, and related entities using the Mudstack API.
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.
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.