# Working with your account Source: https://docs.mudstack.com/api-reference/accounts Understand how your mudstack account is structured and how to utilize our API to manage it. ## Overview Accounts in Mudstack represent the top-level entity for organizing and managing your content. They are used by users, teams, or studios to group workspaces and their associated entities. All content within an account is isolated and cannot be accessed without specifying the appropriate `x-account-id` header in every API request. ## Key Concepts ### Accounts * **Definition**: An account is the primary container for all your workspaces and your team members. * **Ownership**: All content inside an account belongs exclusively to that account. * **Access Control**: API requests must include the `x-account-id` header to interact with account-specific resources. ### Entities within Accounts Accounts own various entities, including: * **Workspaces**: Containers environments for assets, tags, libraries, and tasks. * **Invites**: Pending invitations for new members. * **History**: Logs of account activities. * **Members**: Users associated with the account. * **Settings**: Configuration options for the account. ## API Headers To interact with accounts, include the following headers in your API requests: * `Authorization`: Bearer token for authentication. * `x-account-id`: The unique identifier of the account you want to access. Example: ```http theme={null} GET /accounts HTTP/1.1 Host: api.mudstack.com Authorization: Bearer x-account-id: ``` ## Common API Endpoints ### 1. Account * **Get User Accounts**: [GET /users/accounts](./accounts/get-user-accounts) (no x-account-id required) * **Get Account Metadata**: [GET /accounts](./accounts/get-account-metadata) * **Update Account**: [PUT /accounts](./accounts/update-account) * **Delete Account**: [DELETE /accounts](./accounts/delete-account) * **Get Account Thumbnail**: [GET /accounts](./accounts/get-thumbnail) ### 2. Account Members * **Get Members**: [GET /accounts/members](./accounts/members/get-members) * **Update Member**: [PUT /accounts/members/\{member\_id}](./accounts/members/update-member) * **Delete Member**: [DELETE /accounts/members/\{member\_id}](./accounts/members/delete-member) ### 3. List Workspaces in an Account * **Get Workspaces**: [GET /accounts/workspaces](./accounts/get-workspaces) ### 4. Account Settings * **Get Settings**: [GET /accounts/settings](./accounts/settings/get-settings) * **Update Setting**: [PUT /accounts/settings/\{setting\_id}](./accounts/settings/update-setting) ### 5. Account History * **Get History**: [GET /accounts/history](./accounts/history/get-history) ### 6. Account Invites * **Get Invites**: [GET /accounts/invites](./accounts/invites/get-invites) * **Create Invite**: [POST /accounts/invites](./accounts/invites/create-invites) * **Delete Invite**: [DELETE /accounts/invites/\{invite\_id}](./accounts/invites/delete-invite) ## Additional Information For more API endpoints, refer to the [API Reference](./getting-started). # Delete account Source: https://docs.mudstack.com/api-reference/accounts/delete-account delete /accounts # Get account metadata Source: https://docs.mudstack.com/api-reference/accounts/get-account-metadata get /accounts # Get limits Source: https://docs.mudstack.com/api-reference/accounts/get-limits get /accounts/limits # Get thumbnail Source: https://docs.mudstack.com/api-reference/accounts/get-thumbnail get /accounts/download # Get user accounts Source: https://docs.mudstack.com/api-reference/accounts/get-user-accounts get /users/accounts Returns the accounts associated with the current user. # Get workspaces Source: https://docs.mudstack.com/api-reference/accounts/get-workspaces get /accounts/workspaces # Get history Source: https://docs.mudstack.com/api-reference/accounts/history/get-history get /accounts/history Retrieve the history of the account. # Create invites Source: https://docs.mudstack.com/api-reference/accounts/invites/create-invites post /accounts/invites # Delete invite Source: https://docs.mudstack.com/api-reference/accounts/invites/delete-invite delete /accounts/invites # Get invites Source: https://docs.mudstack.com/api-reference/accounts/invites/get-invites get /accounts/invites # Delete member Source: https://docs.mudstack.com/api-reference/accounts/members/delete-member delete /accounts/members/{user_id} Remove a user from the current account. # Get members Source: https://docs.mudstack.com/api-reference/accounts/members/get-members get /accounts/members Retrieve a list of members for the current account. # Leave account Source: https://docs.mudstack.com/api-reference/accounts/members/leave-account delete /accounts/members/leave/{account_id} Remove the current user from the specified account. # Update member Source: https://docs.mudstack.com/api-reference/accounts/members/update-member put /accounts/members/{user_id} Update the role of a user in the current account. # Dismiss notification Source: https://docs.mudstack.com/api-reference/accounts/notifications/dismiss-notification delete /subscribed/{notification_id} # Dismiss notifications Source: https://docs.mudstack.com/api-reference/accounts/notifications/dismiss-notifications delete /subscribed # Get change requests Source: https://docs.mudstack.com/api-reference/accounts/notifications/get-change-requests get /changeRequests # Get notifications Source: https://docs.mudstack.com/api-reference/accounts/notifications/get-notifications get /subscribed # Get review requests Source: https://docs.mudstack.com/api-reference/accounts/notifications/get-review-requests get /reviewRequests # Get tasks Source: https://docs.mudstack.com/api-reference/accounts/notifications/get-tasks get /tasks # Update notification Source: https://docs.mudstack.com/api-reference/accounts/notifications/update-notification put /subscribed/{notification_id} # Get setting Source: https://docs.mudstack.com/api-reference/accounts/settings/get-setting get /accounts/settings/{key} # Get settings Source: https://docs.mudstack.com/api-reference/accounts/settings/get-settings get /accounts/settings # Update setting Source: https://docs.mudstack.com/api-reference/accounts/settings/update-setting put /accounts/settings/{key} # Update settings Source: https://docs.mudstack.com/api-reference/accounts/settings/update-settings put /accounts/settings # Get subscription Source: https://docs.mudstack.com/api-reference/accounts/subscriptions/get-subscription get /accounts/subscriptions Retrieve the subscription details for the account. # Update subscription Source: https://docs.mudstack.com/api-reference/accounts/subscriptions/update-subscription put /accounts/subscriptions Update the subscription details for the account. # Update account Source: https://docs.mudstack.com/api-reference/accounts/update-account put /accounts # Working with assets Source: https://docs.mudstack.com/api-reference/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. 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](./workspaces/assets/versions/get-versions) * **Get a specific version**: [GET /workspaces/assets/\{asset\_id}/versions/\{version\_id}](./workspaces/assets/versions/get-version) * **Create a new version**: [POST /workspaces/assets/\{asset\_id}/versions](./workspaces/assets/versions/create-version) * **Update a version**: [PATCH /workspaces/assets/\{asset\_id}/versions/\{version\_id}](./workspaces/assets/versions/update-version) * **Delete a version**: [DELETE /workspaces/assets/\{asset\_id}/versions/\{version\_id}](./workspaces/assets/versions/delete-version) * **Restore a deleted version**: [PATCH /workspaces/assets/\{asset\_id}/versions/\{version\_id}/restore](./workspaces/assets/versions/restore-version) * **Download a version**: [GET /workspaces/assets/\{asset\_id}/versions/\{version\_id}/download](./workspaces/assets/versions/download-version) *** ### 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](./workspaces/assets/tags/get-tags) * **Add tags to an asset**: [POST /workspaces/assets/\{asset\_id}/tags](./workspaces/assets/tags/add-tags) * **Retrieve a specific tag**: [GET /workspaces/assets/\{asset\_id}/tags/\{tag\_id}](./workspaces/assets/tags/get-tag) * **Add a specific tag**: [POST /workspaces/assets/\{asset\_id}/tags/\{tag\_id}](./workspaces/assets/tags/add-tag) * **Remove a specific tag**: [DELETE /workspaces/assets/\{asset\_id}/tags/\{tag\_id}](./workspaces/assets/tags/remove-tag) *** ### 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](./workspaces/assets/tasks/get-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](./workspaces/assets/comments/create-comment) * **Get comments for an asset**: [GET /workspaces/assets/\{asset\_id}/comments](./workspaces/assets/comments/get-comments) * **Get a specific comment**: [GET /workspaces/assets/\{asset\_id}/comments/\{comment\_id}](./workspaces/assets/comments/get-comment) * **Update comment**: [PUT /workspaces/assets/\{asset\_id}/comments/\{comment\_id}](./workspaces/assets/comments/update-comment) * **Delete comment**: [DELETE /workspaces/assets/\{asset\_id}/comments/\{comment\_id}](./workspaces/assets/comments/delete-comment) *** ### 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](./workspaces/assets/reviews/create-review) * **Get all reviews for an asset**: [GET /workspaces/assets/\{asset\_id}/reviews](./workspaces/assets/reviews/get-reviews) * **Get a specific review**: [GET /workspaces/assets/\{asset\_id}/reviews/\{review\_id}](./workspaces/assets/reviews/get-review) * **Update a review**: [PUT /workspaces/assets/\{asset\_id}/reviews/\{review\_id}](./workspaces/assets/reviews/update-review) * **Delete a review**: [DELETE /workspaces/assets/\{asset\_id}/reviews/\{review\_id}](./workspaces/assets/reviews/delete-review) *** ### 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}](./workspaces/assets/reviewRequests/create-review-request) * **Get review requests for an asset**: [GET /workspaces/assets/\{asset\_id}/reviewRequests](./workspaces/assets/reviewRequests/get-review-requests) * **Update a review request**: [PUT /workspaces/assets/\{asset\_id}/reviewRequests/\{user\_id}](./workspaces/assets/reviewRequests/update-review-request) * **Delete a review request**: [DELETE /workspaces/assets/\{asset\_id}/reviewRequests/\{user\_id}](./workspaces/assets/reviewRequests/delete-review-request) *** ### 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](./workspaces/assets/history/get-history) * **Get asset review history**: [GET /workspaces/assets/\{asset\_id}/history/review](./workspaces/assets/history/get-review-history) *** ## General Asset Management ### Create or Update an Asset * **Endpoint**: [POST /workspaces/assets](./workspaces/assets/create-or-update-asset) * **Description**: Creates a new asset or updates an existing one. ### Delete an Asset * **Endpoint**: [DELETE /workspaces/assets](./workspaces/assets/delete-assets) * **Description**: Deletes assets either permanently or soft deletes them. ### Get Asset by ID * **Endpoint**: [GET /workspaces/assets/\{asset\_id}](./workspaces/assets/get-asset) * **Description**: Retrieves an asset. ### Update Asset by ID * **Endpoint**: [PUT /workspaces/assets/\{asset\_id}](./workspaces/assets/update-asset) * **Description**: Updates an asset. ### Restore a Soft-Deleted Asset * **Endpoint**: [PATCH /workspaces/assets/\{asset\_id}/restore](./workspaces/assets/restore-asset) * **Description**: Restores a soft-deleted asset. ### Download an Asset * **Endpoint**: [GET /workspaces/assets/\{asset\_id}/download](./workspaces/assets/download-asset) * **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. # Authenticate api key Source: https://docs.mudstack.com/api-reference/auth/authenticate-api-key post /auth/token Authenticate API keys using account_id, key, and secret. # Validate access token Source: https://docs.mudstack.com/api-reference/auth/validate-access-token post /auth/validate Given the access token, validate the associated user. Will create any required user and workspaces as well, it will upgrade any temporary workspaces to pro accounts. If no authorization token present, then access is invalid. `req.auth.sub` must have the auth0 user id present. # Authenticating with the Mudstack API Source: https://docs.mudstack.com/api-reference/authentication Learn how to securely authenticate with the Mudstack API using API keys and JSON Web Tokens (JWTs). To interact with the Mudstack API, you need to authenticate using a JSON Web Token (JWT). This token is generated using an API Key and Secret Key linked to your account. **Note:** API access is only available for Pro and Enterprise customers. If you are on a different plan, please contact Mudstack support to upgrade your account. *** ## Generating API Key + Secret Key To get an API Key and Secret Key, please contact Mudstack support. Click the link below to start an email to [support@mudstack.com](mailto:support@mudstack.com) with the subject "Generate API Key for my Mudstack Account". [Generate API Key for my Mudstack Account](mailto:support@mudstack.com?subject=Generate%20API%20Key%20for%20my%20Mudstack%20Account) **Important:** * Treat your API Key and Secret Key as sensitive credentials. Do not share them publicly or store them in unsecured locations. * If you suspect your keys have been compromised, contact Mudstack support immediately to revoke and regenerate them. *** ## Using the API Key + Secret Key Once you have your API Key and Secret Key, you can generate a JWT. Use the following endpoint to authenticate: ``` POST /auth/token ``` ### Request Body ```json theme={null} { "key": "your-api-key", "secret": "your-secret-key" } ``` ### Request Headers ``` x-account-id: your-account-id ``` ### Response ```string theme={null} "your-jwt-token" ``` **Notes:** * The `token` field contains your JWT, which is valid for the duration specified in `expires_in` (in seconds). * You must regenerate the JWT once it expires. Use this token in the `Authorization` header for all subsequent API requests: ``` Authorization: Bearer your-jwt-token ``` *** ## Additional Headers for Resource Access In addition to the `Authorization` header, some endpoints require additional headers to validate resource access or ownership. These headers are: * **`x-account-id`**: Specifies the account ID associated with the request. Required for endpoints that operate at the account level. * **`x-workspace-id`**: Specifies the workspace ID associated with the request. Required for endpoints that operate within a specific workspace. ### Example Request with Additional Headers Here is an example of a request that includes all necessary headers: ``` GET /workspace/assets/{asset_id} ``` #### Headers ``` Authorization: Bearer your-jwt-token x-account-id: your-account-id x-workspace-id: your-workspace-id ``` **Best Practices:** * Always ensure the `x-account-id` and `x-workspace-id` values match the resources you are trying to access. * Use environment variables or secure configuration files to store these values. *** ## Error Handling If the required headers are missing or invalid, the API will return an error. Common error responses include: * **401 Unauthorized**: Invalid or expired JWT. * **403 Forbidden**: Insufficient permissions or invalid resource ownership. * **400 Bad Request**: Missing or malformed headers. ### Example Error Response ```json theme={null} { "error": "Unauthorized", "message": "Invalid or expired token" } ``` **Tips for Debugging:** * Double-check your JWT and ensure it has not expired. * Verify that the `x-account-id` and `x-workspace-id` headers are correct and match the requested resource. *** ## Security Recommendations **Keep Your JWT Secure:** * Do not expose your JWT in client-side code or public repositories. * Store your JWT securely, such as in environment variables or secure storage mechanisms. * Never hardcode your API Key, Secret Key, or JWT in your application code. **Rotate Your Keys Regularly:** * Periodically request to regenerate your API Key and Secret Key to minimize security risks. * Update your application with the new keys immediately after regeneration. *** For further assistance contact [Mudstack Support](mailto:support@mudstack.com). # Get assets with outstanding tasks Source: https://docs.mudstack.com/api-reference/examples/get-assets-with-outstanding-tasks ## Introduction Efficiently managing tasks and their associated assets is a critical requirement in workflows involving digital asset management systems. This guide demonstrates how to automate the process of finding tasks with a status that is not "Completed" and retrieving their corresponding assets by their IDs. By following these examples, you can streamline your task and asset management processes and integrate them into your existing workflows. Authentication is a critical step in interacting with the Mudstack API. Each request requires an authorization token, which is obtained using your API key and secret. Additionally, the `x-workspace-id` and `x-account-id` headers must be included in every request to ensure proper scoping. This example is particularly useful for scenarios such as: * Identifying tasks that require immediate attention. * Automating the retrieval of assets associated with pending tasks. * Integrating task and asset management with other systems or workflows. This example demonstrates how to: 1. Authenticate and retrieve an authorization token. 2. Retrieve tasks using the [`/tasks`](../workspaces/tasks/get-tasks) endpoint. 3. Filter tasks with a status that is not "Completed". 4. Retrieve the corresponding assets for the filtered tasks using the [`/workspaces/assets/{asset_id}`](../workspaces/assets/get-asset) endpoint. ## Steps ### Step 1: Authenticate and Retrieve an Authorization Token Use the [`/auth/token`](../auth/authenticate-api-key) endpoint to retrieve an authorization token. Replace ``, ``, and `` with your account ID, API key, and secret, respectively. ```python auth.py theme={null} # Python example to retrieve an authorization token import requests url = "https://api.mudstack.com/auth/token" headers = { "x-account-id": "", "Content-Type": "application/json" } data = { "key": "", "secret": "" } response = requests.post(url, headers=headers, json=data) token = response.json()["token"] print(token) ``` ```javascript auth.js theme={null} // JavaScript example to retrieve an authorization token const fetch = require('node-fetch'); const url = "https://api.mudstack.com/auth/token"; const headers = { "x-account-id": "", "Content-Type": "application/json" }; const data = { key: "", secret: "" }; fetch(url, { method: "POST", headers, body: JSON.stringify(data) }) .then(res => res.json()) .then(data => console.log(data.token)); ``` ```csharp auth.cs theme={null} // C# example to retrieve an authorization token using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new HttpClient(); var requestBody = "{\"key\": \"\", \"secret\": \"\"}"; var content = new StringContent(requestBody, Encoding.UTF8, "application/json"); content.Headers.Add("x-account-id", ""); var response = await client.PostAsync("https://api.mudstack.com/auth/token", content); var token = await response.Content.ReadAsStringAsync(); Console.WriteLine(token); } } ``` **Response Example:** ```json theme={null} { "token": "your_generated_token" } ``` ### Step 2: Retrieve Tasks Use the [`/tasks`](../workspaces/tasks/get-tasks) endpoint to retrieve tasks. Replace ``, ``, and `` with your authorization token, workspace ID, and account ID, respectively. ```python get-tasks.py theme={null} # Python example to retrieve tasks import requests url = "https://api.mudstack.com/tasks" headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "" } response = requests.get(url, headers=headers) tasks = response.json()["tasks"] print(tasks) ``` ```javascript get-tasks.js theme={null} // JavaScript example to retrieve tasks const fetch = require('node-fetch'); const url = "https://api.mudstack.com/tasks"; const headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "" }; fetch(url, { method: "GET", headers }) .then(res => res.json()) .then(data => console.log(data.tasks)); ``` ```csharp get-tasks.cs theme={null} // C# example to retrieve tasks using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.mudstack.com/tasks"); request.Headers.Add("Authorization", "Bearer "); request.Headers.Add("x-workspace-id", ""); request.Headers.Add("x-account-id", ""); var response = await client.SendAsync(request); Console.WriteLine(await response.Content.ReadAsStringAsync()); } } ``` **Response Example:** ```json theme={null} { "tasks": [ { "id": "task1", "status": "Pending", "asset_id": "asset1" }, { "id": "task2", "status": "Completed", "asset_id": "asset2" } ] } ``` ### Step 3: Filter Tasks with Status Not "Completed" Filter the tasks to exclude those with a status of "Completed". ```javascript filter-tasks.js theme={null} // Filter tasks with status not "Completed" const filteredTasks = tasks.filter(task => task.status !== "Completed"); ``` ```python filter-tasks.py theme={null} # Python example to filter tasks filtered_tasks = [task for task in tasks if task["status"] != "Completed"] ``` ```csharp filter-tasks.cs theme={null} // C# example to filter tasks var filteredTasks = tasks.Where(task => task.Status != "Completed").ToList(); ``` ### Step 4: Retrieve Corresponding Assets For each filtered task, retrieve the corresponding asset using the [`/workspaces/assets/{asset_id}`](../workspaces/assets/get-asset) endpoint. ```python get-assets.py theme={null} # Python example to retrieve assets for task in filtered_tasks: url = f"https://api.mudstack.com/workspaces/assets/{task['asset_id']}" headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "" } response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript get-assets.js theme={null} // JavaScript example to retrieve assets filteredTasks.forEach(task => { const url = `https://api.mudstack.com/workspaces/assets/${task.asset_id}`; const headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "" }; fetch(url, { method: "GET", headers }) .then(res => res.json()) .then(console.log); }); ``` ```csharp get-assets.cs theme={null} // C# example to retrieve assets foreach (var task in filteredTasks) { var url = $"https://api.mudstack.com/workspaces/assets/{task.AssetId}"; var request = new HttpRequestMessage(HttpMethod.Get, url); request.Headers.Add("Authorization", "Bearer "); request.Headers.Add("x-workspace-id", ""); request.Headers.Add("x-account-id", ""); var response = await client.SendAsync(request); Console.WriteLine(await response.Content.ReadAsStringAsync()); } ``` **Response Example:** ```json theme={null} { "id": "asset1", "name": "example_asset.png", "status": "Pending" } ``` *** ## Explore More Examples Looking for more examples? Check out the following guides to learn about other use cases: * [Search Assets](../examples/searching-assets) * [Update Status on Assets](../examples/update-status-on-assets) * [Invite Users to Account](../examples/invite-users-to-account) # Invite users to account Source: https://docs.mudstack.com/api-reference/examples/invite-users-to-account ## Introduction Inviting users to an account is a common operation in collaborative workflows. This guide demonstrates how to automate the process of inviting multiple users to an account by specifying their email addresses, roles, and associated workspaces. By following these examples, you can streamline the user onboarding process and integrate it into your existing workflows. Each example in this guide begins with obtaining an authorization token from the Mudstack API and setting the required headers (`Authorization`, `x-workspace-id`, and `x-account-id`) for every request. These steps ensure secure and properly scoped API interactions. Authentication is a critical step in interacting with the Mudstack API. Each request requires an authorization token, which is obtained using your API key and secret. Additionally, the `x-workspace-id` and `x-account-id` headers must be included in every request to ensure proper scoping. This example is particularly useful for scenarios such as: * Onboarding new team members to an account. * Assigning roles and workspace access during the invitation process. * Automating user invitations for large teams. This example demonstrates how to: 1. Authenticate and retrieve an authorization token. 2. Invite multiple users to an account using the [`/accounts/invites`](../../accounts/invites) endpoint. ## Steps ### Step 1: Authenticate and Retrieve an Authorization Token Use the [`/auth/token`](../auth/authenticate-api-key) endpoint to retrieve an authorization token. Replace ``, ``, and `` with your account ID, API key, and secret, respectively. ```python auth.py theme={null} # Python example to retrieve an authorization token import requests url = "https://api.mudstack.com/auth/token" headers = { "x-account-id": "", "Content-Type": "application/json" } data = { "key": "", "secret": "" } response = requests.post(url, headers=headers, json=data) token = response.json()["token"] print(token) ``` ```javascript auth.js theme={null} // JavaScript example to retrieve an authorization token const fetch = require('node-fetch'); const url = "https://api.mudstack.com/auth/token"; const headers = { "x-account-id": "", "Content-Type": "application/json" }; const data = { key: "", secret: "" }; fetch(url, { method: "POST", headers, body: JSON.stringify(data) }) .then(res => res.json()) .then(data => console.log(data.token)); ``` ```csharp auth.cs theme={null} // C# example to retrieve an authorization token using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new HttpClient(); var requestBody = "{\"key\": \"\", \"secret\": \"\"}"; var content = new StringContent(requestBody, Encoding.UTF8, "application/json"); content.Headers.Add("x-account-id", ""); var response = await client.PostAsync("https://api.mudstack.com/auth/token", content); var token = await response.Content.ReadAsStringAsync(); Console.WriteLine(token); } } ``` **Response Example:** ```json theme={null} { "token": "your_generated_token" } ``` ### Step 2: Invite Users to an Account Use the [`/accounts/invites`](../accounts/invites) endpoint to invite users to an account. Replace ``, ``, and `` with your authorization token, workspace ID, and account ID, respectively. Provide the list of users to invite, including their email addresses, roles, and associated workspaces. ```python invite-users.py theme={null} # Python example to invite users import requests # Step 1: Authenticate auth_url = "https://api.mudstack.com/auth/token" auth_data = { "key": "", "secret": "" } auth_headers = {"x-account-id": "", "Content-Type": "application/json"} auth_response = requests.post(auth_url, headers=auth_headers, json=auth_data) token = auth_response.json()["token"] # Step 2: Invite users url = "https://api.mudstack.com/accounts/invites" headers = { "Authorization": f"Bearer {token}", "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" } data = { "invites": [ { "email": "user1@example.com", "roles": ["Editor"], "workspace_ids": ["workspace1"] }, { "email": "user2@example.com", "roles": ["Viewer"], "workspace_ids": ["workspace2", "workspace3"] } ] } response = requests.post(url, headers=headers, json=data) print(response.json()) ``` ```javascript invite-users.js theme={null} // JavaScript example to invite users const fetch = require('node-fetch'); // Step 1: Authenticate const authUrl = "https://api.mudstack.com/auth/token"; const authData = { key: "", secret: "" }; const authHeaders = { "x-account-id": "", "Content-Type": "application/json" }; fetch(authUrl, { method: "POST", headers: authHeaders, body: JSON.stringify(authData) }) .then(res => res.json()) .then(authResponse => { const token = authResponse.token; // Step 2: Invite users const url = "https://api.mudstack.com/accounts/invites"; const headers = { "Authorization": `Bearer ${token}`, "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" }; const data = { invites: [ { email: "user1@example.com", roles: ["Editor"], workspace_ids: ["workspace1"] }, { email: "user2@example.com", roles: ["Viewer"], workspace_ids: ["workspace2", "workspace3"] } ] }; fetch(url, { method: "POST", headers, body: JSON.stringify(data) }) .then(res => res.json()) .then(console.log); }); ``` ```csharp invite-users.cs theme={null} // C# example to invite users using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { // Step 1: Authenticate var client = new HttpClient(); var authUrl = "https://api.mudstack.com/auth/token"; var authJson = "{\"key\": \"\", \"secret\": \"\"}"; var authContent = new StringContent(authJson, Encoding.UTF8, "application/json"); authContent.Headers.Add("x-account-id", ""); var authResponse = await client.PostAsync(authUrl, authContent); var authResponseString = await authResponse.Content.ReadAsStringAsync(); var token = authResponseString; // Extract token from response // Step 2: Invite users var url = "https://api.mudstack.com/accounts/invites"; var json = "{\"invites\": [{\"email\": \"user1@example.com\", \"roles\": [\"Editor\"], \"workspace_ids\": [\"workspace1\"]}, {\"email\": \"user2@example.com\", \"roles\": [\"Viewer\"], \"workspace_ids\": [\"workspace2\", \"workspace3\"]}]}"; var content = new StringContent(json, Encoding.UTF8, "application/json"); client.DefaultRequestHeaders.Add("Authorization", "Bearer " + token); client.DefaultRequestHeaders.Add("x-workspace-id", ""); client.DefaultRequestHeaders.Add("x-account-id", ""); var response = await client.PostAsync(url, content); var responseString = await response.Content.ReadAsStringAsync(); Console.WriteLine(responseString); } } ``` **Response Example:** ```json theme={null} { "invites": [ { "email": "user1@example.com", "status": "sent" }, { "email": "user2@example.com", "status": "sent" } ] } ``` *** ## Explore More Examples Looking for more examples? Check out the following guides to learn about other use cases: * [Update Status on Assets](../examples/update-status-on-assets) * [Search Assets](../examples/search-assets) * [Get Assets with Outstanding Tasks](../examples/get-assets-with-outstanding-tasks) # Searching assets Source: https://docs.mudstack.com/api-reference/examples/searching-assets ## Introduction Searching for assets is a fundamental operation in digital asset management workflows. Whether you're managing a large library of assets or collaborating with a team, being able to efficiently locate and filter assets is crucial. This guide demonstrates how to use the Mudstack API to search for assets, filter them by library, and filter by review status. By following these examples, you can streamline your workflows and improve productivity. These examples are designed for developers integrating Mudstack into their applications or automation scripts. They demonstrate how to: 1. Search for assets using the [`/workspaces/assets/search`](../workspaces/assets/search-assets) endpoint. 2. Filter assets by library, specifically finding the library named "Ready for engine". 3. Filter assets where the `reviewStatus` is "rejected". Before starting, ensure you have a valid API token and workspace ID. These are required for authenticating your requests. ### Before Starting: Authenticate and Retrieve an Authorization Token Use the [`/auth/token`](../auth/authenticate-api-key) endpoint to retrieve an authorization token. Replace ``, ``, and `` with your account ID, API key, and secret, respectively. ```python auth.py theme={null} # Python example to retrieve an authorization token import requests url = "https://api.mudstack.com/auth/token" headers = { "x-account-id": "", "Content-Type": "application/json" } data = { "key": "", "secret": "" } response = requests.post(url, headers=headers, json=data) token = response.json()["token"] print(token) ``` ```javascript auth.js theme={null} // JavaScript example to retrieve an authorization token const fetch = require('node-fetch'); const url = "https://api.mudstack.com/auth/token"; const headers = { "x-account-id": "", "Content-Type": "application/json" }; const data = { key: "", secret: "" }; fetch(url, { method: "POST", headers, body: JSON.stringify(data) }) .then(res => res.json()) .then(data => console.log(data.token)); ``` ```csharp auth.cs theme={null} // C# example to retrieve an authorization token using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new HttpClient(); var requestBody = "{\"key\": \"\", \"secret\": \"\"}"; var content = new StringContent(requestBody, Encoding.UTF8, "application/json"); content.Headers.Add("x-account-id", ""); var response = await client.PostAsync("https://api.mudstack.com/auth/token", content); var token = await response.Content.ReadAsStringAsync(); Console.WriteLine(token); } } ``` ## Examples ### Example 1: Search for Assets by Query Use the [`/workspaces/assets/search`](../workspaces/assets/search-assets) endpoint to search for assets by a specific query. Replace ``, ``, ``, and `` with your API key, secret, workspace ID, and account ID, respectively. ```python search-by-query.py theme={null} # Step 1: Obtain an authorization token import requests auth_url = "https://api.mudstack.com/auth/token" auth_data = {"key": "", "secret": ""} auth_headers = {"x-account-id": "", "Content-Type": "application/json"} auth_response = requests.post(auth_url, headers=auth_headers, json=auth_data) token = auth_response.json()["token"] # Step 2: Use the token to search for assets by query url = "https://api.mudstack.com/workspaces/assets/search" headers = { "Authorization": f"Bearer {token}", "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" } data = {"filters": {"query": "example"}} response = requests.get(url, headers=headers, json=data) print(response.json()) ``` ```javascript search-by-query.js theme={null} // Step 1: Obtain an authorization token const fetch = require('node-fetch'); const authUrl = "https://api.mudstack.com/auth/token"; const authData = { key: "", secret: "" }; const authHeaders = { "x-account-id": "", "Content-Type": "application/json" }; fetch(authUrl, { method: "POST", headers: authHeaders, body: JSON.stringify(authData) }) .then(res => res.json()) .then(auth => { const token = auth.token; // Step 2: Use the token to search for assets by query const url = "https://api.mudstack.com/workspaces/assets/search"; const headers = { "Authorization": `Bearer ${token}`, "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" }; const data = { filters: { query: "example" } }; return fetch(url, { method: "GET", headers, body: JSON.stringify(data) }); }) .then(res => res.json()) .then(console.log); ``` ```csharp search-by-query.cs theme={null} using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; using Newtonsoft.Json; class Program { static async Task Main() { // Step 1: Obtain an authorization token var authUrl = "https://api.mudstack.com/auth/token"; var authData = new { key = "", secret = "" }; using var client = new HttpClient(); var authResponse = await client.PostAsync(authUrl, new StringContent(JsonConvert.SerializeObject(authData), Encoding.UTF8, "application/json")); var authResult = JsonConvert.DeserializeObject(await authResponse.Content.ReadAsStringAsync()); var token = authResult.token; // Step 2: Use the token to search for assets by query var url = "https://api.mudstack.com/workspaces/assets/search"; client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}"); client.DefaultRequestHeaders.Add("x-workspace-id", ""); client.DefaultRequestHeaders.Add("x-account-id", ""); var data = new { filters = new { query = "example" } }; var response = await client.GetAsync(url + "?filters.query=" + data.filters.query); var result = await response.Content.ReadAsStringAsync(); Console.WriteLine(result); } } ``` *** ### Example 2: Filter Assets by Library To filter assets by library, first retrieve all libraries using the [`/workspaces/libraries`](../workspaces/libraries/get-libraries) endpoint. Then, find the library with the name "Ready for engine" and use its `id` to filter assets. ```python filter-by-library.py theme={null} # Step 1: Obtain an authorization token auth_url = "https://api.mudstack.com/auth/token" auth_data = {"key": "", "secret": ""} auth_headers = {"x-account-id": "", "Content-Type": "application/json"} auth_response = requests.post(auth_url, headers=auth_headers, json=auth_data) token = auth_response.json()["token"] # Step 2: Retrieve libraries libraries_url = "https://api.mudstack.com/workspaces/libraries" headers = { "Authorization": f"Bearer {token}", "x-workspace-id": "", "x-account-id": "" } libraries_response = requests.get(libraries_url, headers=headers) libraries = libraries_response.json()["libraries"] library_id = next(lib["id"] for lib in libraries if lib["name"] == "Ready for engine") # Step 3: Filter assets by library ID assets_url = "https://api.mudstack.com/workspaces/assets/search" data = {"filters": {"libraries": [library_id]}} assets_response = requests.get(assets_url, headers=headers, json=data) print(assets_response.json()) ``` ```javascript filter-by-library.js theme={null} // Step 1: Obtain an authorization token const authUrl = "https://api.mudstack.com/auth/token"; const authData = { key: "", secret: "" }; const authHeaders = { "x-account-id": "", "Content-Type": "application/json" }; fetch(authUrl, { method: "POST", headers: authHeaders, body: JSON.stringify(authData) }) .then(res => res.json()) .then(auth => { const token = auth.token; // Step 2: Retrieve libraries const librariesUrl = "https://api.mudstack.com/workspaces/libraries"; const headers = { "Authorization": `Bearer ${token}`, "x-workspace-id": "", "x-account-id": "" }; return fetch(librariesUrl, { method: "GET", headers }); }) .then(res => res.json()) .then(data => { const library = data.libraries.find(lib => lib.name === "Ready for engine"); const libraryId = library.id; // Step 3: Filter assets by library ID const assetsUrl = "https://api.mudstack.com/workspaces/assets/search"; const body = { filters: { libraries: [libraryId] } }; return fetch(assetsUrl, { method: "GET", headers, body: JSON.stringify(body) }); }) .then(res => res.json()) .then(console.log); ``` ```csharp filter-by-library.cs theme={null} using System; using System.Linq; using System.Net.Http; using System.Text; using System.Threading.Tasks; using Newtonsoft.Json; class Program { static async Task Main() { // Step 1: Obtain an authorization token var authUrl = "https://api.mudstack.com/auth/token"; var authData = new { key = "", secret = "" }; using var client = new HttpClient(); var authContent = new StringContent(JsonConvert.SerializeObject(authData), Encoding.UTF8, "application/json"); authContent.Headers.Add("x-account-id", ""); var authResponse = await client.PostAsync(authUrl, authContent); var authResult = JsonConvert.DeserializeObject(await authResponse.Content.ReadAsStringAsync()); var token = authResult.token; // Step 2: Retrieve libraries var librariesUrl = "https://api.mudstack.com/workspaces/libraries"; client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}"); client.DefaultRequestHeaders.Add("x-workspace-id", ""); client.DefaultRequestHeaders.Add("x-account-id", ""); var librariesResponse = await client.GetAsync(librariesUrl); var librariesResult = JsonConvert.DeserializeObject(await librariesResponse.Content.ReadAsStringAsync()); var library = librariesResult.libraries.First(lib => lib.name == "Ready for engine"); var libraryId = library.id; // Step 3: Filter assets by library ID var assetsUrl = "https://api.mudstack.com/workspaces/assets/search"; var data = new { filters = new { libraries = new[] { libraryId } } }; var response = await client.GetAsync(assetsUrl + "?filters.libraries=" + data.filters.libraries[0]); var result = await response.Content.ReadAsStringAsync(); Console.WriteLine(result); } } ``` *** ### Example 3: Filter Assets by Review Status Filter assets where the `reviewStatus` is "rejected" using the [`/workspaces/assets/search`](../workspaces/assets/search-assets) endpoint. ```python filter-by-review-status.py theme={null} # Step 1: Obtain an authorization token auth_url = "https://api.mudstack.com/auth/token" auth_data = {"key": "", "secret": ""} auth_headers = {"x-account-id": "", "Content-Type": "application/json"} auth_response = requests.post(auth_url, headers=auth_headers, json=auth_data) token = auth_response.json()["token"] # Step 2: Filter assets by review status url = "https://api.mudstack.com/workspaces/assets/search" headers = { "Authorization": f"Bearer {token}", "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" } data = {"filters": {"reviewStatus": ["rejected"]}} response = requests.get(url, headers=headers, json=data) print(response.json()) ``` ```javascript filter-by-review-status.js theme={null} // Step 1: Obtain an authorization token const authUrl = "https://api.mudstack.com/auth/token"; const authData = { key: "", secret: "" }; const authHeaders = { "x-account-id": "", "Content-Type": "application/json" }; fetch(authUrl, { method: "POST", headers: authHeaders, body: JSON.stringify(authData) }) .then(res => res.json()) .then(auth => { const token = auth.token; // Step 2: Filter assets by review status const url = "https://api.mudstack.com/workspaces/assets/search"; const headers = { "Authorization": `Bearer ${token}`, "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" }; const data = { filters: { reviewStatus: ["rejected"] } }; return fetch(url, { method: "GET", headers, body: JSON.stringify(data) }); }) .then(res => res.json()) .then(console.log); ``` ```csharp filter-by-review-status.cs theme={null} using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; using Newtonsoft.Json; class Program { static async Task Main() { // Step 1: Obtain an authorization token var authUrl = "https://api.mudstack.com/auth/token"; var authData = new { key = "", secret = "" }; using var client = new HttpClient(); var authContent = new StringContent(JsonConvert.SerializeObject(authData), Encoding.UTF8, "application/json"); authContent.Headers.Add("x-account-id", ""); var authResponse = await client.PostAsync(authUrl, authContent); var authResult = JsonConvert.DeserializeObject(await authResponse.Content.ReadAsStringAsync()); var token = authResult.token; // Step 2: Filter assets by review status var url = "https://api.mudstack.com/workspaces/assets/search"; client.DefaultRequestHeaders.Add("Authorization", $"Bearer {token}"); client.DefaultRequestHeaders.Add("x-workspace-id", ""); client.DefaultRequestHeaders.Add("x-account-id", ""); var data = new { filters = new { reviewStatus = new[] { "rejected" } } }; var response = await client.GetAsync(url + "?filters.reviewStatus=" + data.filters.reviewStatus[0]); var result = await response.Content.ReadAsStringAsync(); Console.WriteLine(result); } } ``` *** ## Explore More Examples Looking for more examples? Check out the following guides to learn about other use cases: * [Update Status on Assets](../examples/update-status-on-assets) * [Invite Users to Account](../examples/invite-users-to-account) * [Get Assets with Outstanding Tasks](../examples/get-assets-with-outstanding-tasks) # Update status on assets Source: https://docs.mudstack.com/api-reference/examples/update-status-on-assets ## Introduction Managing asset statuses efficiently is a common requirement in workflows involving digital asset management systems. This guide demonstrates how to automate the process of searching for assets, filtering them based on their last update date, retrieving available statuses, and updating the status of selected assets. By following these examples, you can streamline your asset management tasks and integrate them into your existing workflows. Authentication is a critical step in interacting with the Mudstack API. Each request requires an authorization token, which is obtained using your API key and secret. Additionally, the `x-workspace-id` and `x-account-id` headers must be included in every request to ensure proper scoping. This example is particularly useful for scenarios such as: * Keeping track of assets that require immediate attention. * Automating status updates for assets based on predefined criteria. * Integrating asset management with other systems or workflows. This example demonstrates how to: 1. Authenticate and retrieve an authorization token. 2. Search for assets in a specific path using the [`/workspaces/assets/search`](../workspaces/assets/search-assets) endpoint. 3. Filter out assets that are more than 2 weeks old. 4. Retrieve all asset statuses using the [`/workspaces/assetStatuses`](../workspaces/assets/status/get-statuses) endpoint and find the status with the name "In Progress". 5. Assign the `status_id` of the "In Progress" status to each filtered asset and update them using the [`/workspaces/assets/{asset_id}`](../workspaces/assets/update-asset) endpoint. ## Steps ### Step 1: Authenticate and Retrieve an Authorization Token Use the [`/auth/token`](../auth/authenticate-api-key) endpoint to retrieve an authorization token. Replace ``, ``, and `` with your account ID, API key, and secret, respectively. ```python auth.py theme={null} # Python example to retrieve an authorization token import requests url = "https://api.mudstack.com/auth/token" headers = { "x-account-id": "", "Content-Type": "application/json" } data = { "key": "", "secret": "" } response = requests.post(url, headers=headers, json=data) token = response.json()["token"] print(token) ``` ```javascript auth.js theme={null} // JavaScript example to retrieve an authorization token const fetch = require('node-fetch'); const url = "https://api.mudstack.com/auth/token"; const headers = { "x-account-id": "", "Content-Type": "application/json" }; const data = { key: "", secret: "" }; fetch(url, { method: "POST", headers, body: JSON.stringify(data) }) .then(res => res.json()) .then(data => console.log(data.token)); ``` ```csharp auth.cs theme={null} // C# example to retrieve an authorization token using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new HttpClient(); var requestBody = "{\"key\": \"\", \"secret\": \"\"}"; var content = new StringContent(requestBody, Encoding.UTF8, "application/json"); content.Headers.Add("x-account-id", ""); var response = await client.PostAsync("https://api.mudstack.com/auth/token", content); var token = await response.Content.ReadAsStringAsync(); Console.WriteLine(token); } } ``` ### Step 2: Search for Assets in a Specific Path Use the [`/workspaces/assets/search`](../workspaces/assets/search-assets) endpoint to search for assets in a specific path. Replace ``, ``, and `` with your authorization token, workspace ID, and account ID, respectively. ```python search-assets.py theme={null} # Python example to search for assets import requests url = "https://api.mudstack.com/workspaces/assets/search" headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" } data = {"folder": "/example/path"} response = requests.get(url, headers=headers, json=data) print(response.json()) ``` ```javascript search-assets.js theme={null} // JavaScript example to search for assets const fetch = require('node-fetch'); const url = "https://api.mudstack.com/workspaces/assets/search"; const headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" }; const data = { folder: "/example/path" }; fetch(url, { method: "GET", headers, body: JSON.stringify(data) }) .then(res => res.json()) .then(console.log); ``` ```csharp search-assets.cs theme={null} // C# example to search for assets using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.mudstack.com/workspaces/assets/search"); request.Headers.Add("Authorization", "Bearer "); request.Headers.Add("x-workspace-id", ""); request.Headers.Add("x-account-id", ""); request.Content = new StringContent("{\"folder\": \"/example/path\"}", Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine(await response.Content.ReadAsStringAsync()); } } ``` **Response Example:** ```json theme={null} { "assets": [ { "id": "asset1", "name": "file1.png", "updated_at": "2023-10-01T12:00:00Z" }, { "id": "asset2", "name": "file2.png", "updated_at": "2023-09-15T12:00:00Z" } ] } ``` ### Step 3: Filter Assets Older Than 2 Weeks Filter the assets by comparing the `updated_at` field to the current date. This ensures only assets updated within the last 2 weeks are processed. ```python filter-assets.py theme={null} # Python example to filter assets from datetime import datetime, timedelta two_weeks_ago = datetime.now() - timedelta(days=14) filtered_assets = [asset for asset in assets if datetime.fromisoformat(asset['updated_at']) > two_weeks_ago] ``` ```javascript filter-assets.js theme={null} // Filter assets updated within the last 2 weeks const twoWeeksAgo = new Date(); twoWeeksAgo.setDate(twoWeeksAgo.getDate() - 14); const filteredAssets = assets.filter(asset => new Date(asset.updated_at) > twoWeeksAgo); ``` ```csharp filter-assets.cs theme={null} // C# example to filter assets using System; using System.Collections.Generic; class Program { static void Main(string[] args) { List assets = new List(); // Add assets to the list DateTime twoWeeksAgo = DateTime.Now.AddDays(-14); List filteredAssets = assets.FindAll(asset => DateTime.Parse(asset.UpdatedAt) > twoWeeksAgo); } } class Asset { public string Id { get; set; } public string Name { get; set; } public string UpdatedAt { get; set; } } ``` ### Step 4: Retrieve Asset Statuses and Find "In Progress" Use the [`/workspaces/assetStatuses`](../workspaces/assets/status/get-statuses) endpoint to retrieve all asset statuses. Identify the status with the name "In Progress". ```python retrieve-statuses.py theme={null} # Python example to retrieve statuses import requests url = "https://api.mudstack.com/workspaces/assetStatuses" headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "" } response = requests.get(url, headers=headers) statuses = response.json()["statuses"] in_progress_status = next(status for status in statuses if status["name"] == "In Progress") print(in_progress_status) ``` ```javascript retrieve-statuses.js theme={null} // JavaScript example to retrieve statuses const fetch = require('node-fetch'); const url = "https://api.mudstack.com/workspaces/assetStatuses"; const headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "" }; fetch(url, { method: "GET", headers }) .then(res => res.json()) .then(data => { const inProgressStatus = data.statuses.find(status => status.name === "In Progress"); console.log(inProgressStatus); }); ``` ```csharp retrieve-statuses.cs theme={null} // C# example to retrieve statuses using System; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json.Linq; class Program { static async Task Main(string[] args) { var client = new HttpClient(); var request = new HttpRequestMessage(HttpMethod.Get, "https://api.mudstack.com/workspaces/assetStatuses"); request.Headers.Add("Authorization", "Bearer "); request.Headers.Add("x-workspace-id", ""); request.Headers.Add("x-account-id", ""); var response = await client.SendAsync(request); var jsonResponse = await response.Content.ReadAsStringAsync(); var statuses = JObject.Parse(jsonResponse)["statuses"]; var inProgressStatus = statuses.First(status => status["name"].ToString() == "In Progress"); Console.WriteLine(inProgressStatus); } } ``` **Response Example:** ```json theme={null} { "statuses": [ { "id": "status1", "name": "In Progress", "color": "#FFCC00" }, { "id": "status2", "name": "Completed", "color": "#00FF00" } ] } ``` ### Step 5: Update Assets with the "In Progress" Status For each filtered asset, assign the `status_id` of the "In Progress" status and update the asset using the [`/workspaces/assets/{asset_id}`](../workspaces/assets/update-asset) endpoint. ```python update-assets.py theme={null} # Python example to update assets import requests url_template = "https://api.mudstack.com/workspaces/assets/{asset_id}" headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" } for asset in filtered_assets: url = url_template.format(asset_id=asset["id"]) data = {"status_id": in_progress_status["id"]} response = requests.patch(url, headers=headers, json=data) print(f"Updated asset {asset['id']}: {response.status_code}") ``` ```javascript update-assets.js theme={null} // JavaScript example to update assets const fetch = require('node-fetch'); const urlTemplate = "https://api.mudstack.com/workspaces/assets/{asset_id}"; const headers = { "Authorization": "Bearer ", "x-workspace-id": "", "x-account-id": "", "Content-Type": "application/json" }; filteredAssets.forEach(asset => { const url = urlTemplate.replace("{asset_id}", asset.id); const data = { status_id: inProgressStatus.id }; fetch(url, { method: "PATCH", headers, body: JSON.stringify(data) }) .then(res => console.log(`Updated asset ${asset.id}: ${res.status}`)) .catch(console.error); }); ``` ```csharp update-assets.cs theme={null} // C# example to update assets using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; class Program { static async Task Main(string[] args) { var client = new HttpClient(); string urlTemplate = "https://api.mudstack.com/workspaces/assets/{asset_id}"; foreach (var asset in filteredAssets) { string url = urlTemplate.Replace("{asset_id}", asset.Id); string requestBody = $"{{\"status_id\": \"{inProgressStatus.Id}\"}}"; var request = new HttpRequestMessage(HttpMethod.Patch, url); request.Headers.Add("Authorization", "Bearer "); request.Headers.Add("x-workspace-id", ""); request.Headers.Add("x-account-id", ""); request.Content = new StringContent(requestBody, Encoding.UTF8, "application/json"); var response = await client.SendAsync(request); Console.WriteLine($"Updated asset {asset.Id}: {response.StatusCode}"); } } } ``` **Response Example:** ```json theme={null} { "id": "", "status_id": "" } ``` *** ## Explore More Examples Looking for more examples? Check out the following guides to learn about other use cases: * [Search Assets](../examples/searching-assets) * [Invite Users to Account](../examples/invite-users-to-account) * [Get Assets with Outstanding Tasks](../examples/get-assets-with-outstanding-tasks) # Mudstack API: Getting Started Source: https://docs.mudstack.com/api-reference/getting-started A comprehensive guide to understanding the Mudstack API, including authentication, key concepts, and making your first API call. Welcome to the Mudstack API documentation. This guide will help you get started with key concepts and how to authenticate using our API. ## Overview The Mudstack REST API allows you to programmatically interact with your Mudstack account. You can manage accounts, workspaces, and assets, as well as perform other operations to integrate Mudstack into your workflows. ## Key Concepts * **Accounts**: Your Mudstack account is the foundation for all API interactions. Learn more about managing accounts in the [Accounts Documentation](./accounts). * **Workspaces**: Workspaces are collaborative environments where you can organize and manage your assets. Learn more in the [Workspaces Documentation](./workspaces). * **Assets**: Assets are the core entities you manage in Mudstack. Learn more about asset management in the [Assets Documentation](./assets). ## Authentication All API requests require authentication. Mudstack uses token-based authentication to ensure secure access to your data. To get started with authentication, refer to the [Authentication Documentation](./authentication). ## Base URL The base URL for all API requests is: ``` https://api.mudstack.com ``` ## Making Your First API Call Here’s an example of how to make your first API call to retrieve a list of workspaces: ### Request ```bash theme={null} curl -X GET "https://api.mudstack.com/workspaces" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "x-account-id: YOUR_ACCOUNT_ID" ``` ### Response ```json theme={null} { "workspaces": [ { "account_id": "531f3750-dfab-4bf3-aefe-27d923e4daf6", "id": "531f3750-dfab-4bf3-aefe-27d923e4daf6", "name": "Design Team Workspace", "created_at": "2023-01-01T12:00:00Z", "thumbnail_file_id": "uuid", "defaultAvatar": 2, "created_by_user_id": "uuid", "sequence": 123456 } ] } ``` Replace `YOUR_ACCESS_TOKEN` with the token obtained during authentication. ## Rate Limiting To ensure fair usage and prevent abuse, the Mudstack API enforces rate limits. If you exceed the allowed number of requests, you will receive a `429 Too Many Requests` response. The response will include a `Retry-After` header indicating when you can retry your request. ### Example Response for Rate Limiting ```json theme={null} { "error": "Rate limit exceeded", "retry_after": 60 } ``` To avoid hitting rate limits, consider implementing exponential backoff in your API calls. ## Error Handling The Mudstack API uses standard HTTP status codes to indicate the success or failure of an API request. Here are some common status codes you might encounter: * `200 OK`: The request was successful. * `400 Bad Request`: The request was invalid or cannot be processed. * `401 Unauthorized`: Authentication failed or the token is missing. * `403 Forbidden`: You do not have permission to access the resource. * `404 Not Found`: The requested resource does not exist. * `500 Internal Server Error`: An error occurred on the server. ### Example Error Response ```json theme={null} { "error": { "code": "invalid_request", "message": "The provided account ID is invalid." } } ``` ## Next Steps * Learn how to authenticate: [Authentication Documentation](./authentication) * Manage your accounts: [Accounts Documentation](./accounts) * Explore workspaces: [Workspaces Documentation](./workspaces) * Manage assets: [Assets Documentation](./assets) # Delete avatar Source: https://docs.mudstack.com/api-reference/users/avatar/delete-avatar delete /users/avatar Deletes the avatar of the current user. # Get avatar Source: https://docs.mudstack.com/api-reference/users/avatar/get-avatar get /users/avatar Returns the signed URL for the current user's avatar. # Update avatar Source: https://docs.mudstack.com/api-reference/users/avatar/update-avatar put /users/avatar Updates the avatar of the current user. # Delete user Source: https://docs.mudstack.com/api-reference/users/delete-user delete /users Deletes the currently authenticated user. # Get accounts Source: https://docs.mudstack.com/api-reference/users/get-accounts get /users/accounts Returns the accounts associated with the current user. # Get permissions Source: https://docs.mudstack.com/api-reference/users/get-permissions get /users/permissions Returns the permissions of the current user. # Get user Source: https://docs.mudstack.com/api-reference/users/get-user get /users Returns the details of the currently authenticated user. # Get history Source: https://docs.mudstack.com/api-reference/users/history/get-history get /users/history Retrieve the history of the current user. # Accept invite Source: https://docs.mudstack.com/api-reference/users/invites/accept-invite post /users/accept_invite/{token} Accepts an invitation using the provided token. # Delete invite Source: https://docs.mudstack.com/api-reference/users/invites/delete-invite post /users/reject_invite/{token} Rejects an invitation using the provided token. # Get invites Source: https://docs.mudstack.com/api-reference/users/invites/get-invites get /users/invites Returns the invites of the current user. # Get setting Source: https://docs.mudstack.com/api-reference/users/settings/get-setting get /users/settings/{key} Retrieve a specific setting for the current user. # Get settings Source: https://docs.mudstack.com/api-reference/users/settings/get-settings get /users/settings Retrieve all settings for the current user. # Update setting Source: https://docs.mudstack.com/api-reference/users/settings/update-setting put /users/settings/{key} Update a specific setting for the current user. # Update settings Source: https://docs.mudstack.com/api-reference/users/settings/update-settings put /users/settings Update settings for the current user. # Update user Source: https://docs.mudstack.com/api-reference/users/update-user patch /users Updates the details of the currently authenticated user. # Webhooks Source: https://docs.mudstack.com/api-reference/webhooks Automatically send real-time event notifications to external services, enabling integrations and automations without manual checks. ## Introduction Webhooks allow Mudstack to send real-time updates from your workspace to external services. When an event happens (like a file upload, comment, or review), Mudstack will deliver a JSON payload to your configured endpoint. Only **workspace admins** can create, manage, or view webhooks. *** ## Managing Webhooks You can manage webhooks from `Workspace Settings` → `Webhooks`. ### Creating a Webhook 1. Click **`Create a webhook`** in the top right corner. 2. Enter a **Name** for the webhook. 3. Provide a **URL** for the endpoint that will receive the payloads. 4. Check **Allow sensitive data** to control if the payload will contain IP or just IDs. If this is unchecked, you must call the api upon receiving the payload. 5. Set which events should be sent to the webhook URL 6. Add custom headers if needed The **URL** and **Allow sensitive data** options are not editable after creation Webhooks cannot be edited. To change a webhook, you’ll need to delete it and create a new one. A Secret will be generated after creation for verifying webhook signatures. ### Disabling a Webhook * Toggle the webhook status off by clicking on a webhook, then unchecking the `Enabled` option. ### Deleting a Webhook * Click **Delete** next to the webhook entry in the table. *** ## Event Payload Examples with Sensitive Data ### `asset_created` ```json theme={null} { "accountId": "b8f71389-2a45-4938-b6d5-0a70f9b9858c", "workspaceId": "2c8a5e43-58cb-47ec-b8a5-f0de2dcf9121", "type": "asset_created", "payload": { "assetId": "c1822d26-51b1-4923-8d8a-28d496f965cc", "assetName": "Bot_moodboard_03.png", "assetPath": "/Concepts/Robot/", "createdAt": "2025-10-01T22:58:17.062Z" }, "id": "0e54816a-4c6f-4e64-9826-99ec42f79ef7" } ``` ### `asset_status_changed` ```json theme={null} { "accountId": "b8f71389-2a45-4938-b6d5-0a70f9b9858c", "workspaceId": "2c8a5e43-58cb-47ec-b8a5-f0de2dcf9121", "type": "asset_status_changed", "payload": { "assetId": "afdc6c97-82da-4d14-8a1f-915ba0ac2f1b", "statusName": "record updated", "statusId": "7b9a9f46-fc5d-4409-8a8f-d1383ebd9f6c", "changedAt": "2025-10-01T22:58:17.062Z" }, "id": "c3a72db9-6b8f-4b25-81ff-51a999edca1b" } ``` ### `asset_version_added` ```json theme={null} { "accountId": "b8f71389-2a45-4938-b6d5-0a70f9b9858c", "workspaceId": "2c8a5e43-58cb-47ec-b8a5-f0de2dcf9121", "type": "asset_version_added", "payload": { "assetId": "e8e2b38c-8a4a-4ff8-b9e3-5b78915b2ee3", "checksum": "2dc626b2bc1b7c6cce987e6383b191486f1a1895689e4bf32411d58b203709627ffbf7052a2f5303913fa1d98d8a0e5c40907476e7312fadcc349aac9fcd5a40", "name": "DPN_flying_bot.fbx", "sizeBytes": 652175, "createdAt": "2025-10-01T23:06:14.299Z", "versionId": "b6bac2a0-ad3b-482a-b966-b4f8a4e595c5" }, "id": "708fc78d-f3bb-441d-a699-2ef43cd3e26d" } ``` ### `commit_added` ```json theme={null} { "accountId": "b8f71389-2a45-4938-b6d5-0a70f9b9858c", "workspaceId": "2c8a5e43-58cb-47ec-b8a5-f0de2dcf9121", "type": "commit_added", "payload": { "authorEmail": "josef@mudstack.com", "authorName": "Josef Bell", "commitDescription": "Changed the colors to properly match the armor defaults", "commitId": "e7a3b44f-44d1-4938-b28e-12f8163cfa6a", "commitTitle": "Updated cape on robot4arms", "createdAt": "2025-10-01T23:00:00.496Z" }, "id": "d93e5e4b-ff6a-4eb8-b123-0d12f5c1d46c" } ``` ### `asset_comment_added` ```json theme={null} { "accountId": "b8f71389-2a45-4938-b6d5-0a70f9b9858c", "workspaceId": "2c8a5e43-58cb-47ec-b8a5-f0de2dcf9121", "type": "asset_comment_added", "payload": { "assetId": "42f19bc0-13e7-4d3d-a935-9304823f93a7", "authorName": "Joe Bell", "authorEmail": "josef@mudstack.com", "commentText": "

did you update this @Josef Bell?

", "commentId": "d24587e3-b04f-43ef-bf9a-7d3316405db8", "createdAt": "2025-10-02T21:23:38.891Z" }, "id": "cc02b8c1-45e4-4cc4-b6fd-6a0b9a8c31f5" } ``` ### `asset_reviewer_added` ```json theme={null} { "accountId": "b8f71389-2a45-4938-b6d5-0a70f9b9858c", "workspaceId": "2c8a5e43-58cb-47ec-b8a5-f0de2dcf9121", "type": "asset_reviewer_added", "payload": { "assetId": "b5e1af7b-1f24-48a5-81b2-83f374ec3e35", "createdAt": "2025-10-02T21:25:01.770Z", "requesterName": "Joe Bell", "requesterEmail": "josef@mudstack.com", "requesterId": "c5ec24a9-46b9-4d13-a441-7a2f9d9deeb7", "reviewerId": "0dbe34a8-9a9a-4e4f-b4b1-78f0d67a0b8f" }, "id": "0dc7597c-0e1f-4b9e-a52a-20689b69d52b" } ``` ### `asset_review_added` ```json theme={null} { "accountId": "b8f71389-2a45-4938-b6d5-0a70f9b9858c", "workspaceId": "2c8a5e43-58cb-47ec-b8a5-f0de2dcf9121", "type": "asset_review_added", "payload": { "assetId": "9d0ee2e7-3f25-4e38-b1cc-2cfb88f57df1", "createdAt": "2025-10-02T21:25:01.770Z", "authorName": "Joe Bell", "authorEmail": "josef@mudstack.com", "reviewId": "8f0c9b6e-24f5-4b9e-b5ac-6e593d6cd5ea", "reviewText": "

The color space on this export didn’t convert properly.

", "reviewType": "change_request" }, "id": "6a4f9cb0-2a2b-4b38-b621-d3db4cf94936" } ``` Reviews will have a `reviewType` of `approved` or `change_request` depending on the message. If `Allow sensitive data` is unchecked, the responses will only include the type, date, and ids. ## Example Integrations ### Jira Use our [downloadable sample](/images/Mudstack_JiraWebhookSample.json) to automatically create Jira issues when new assets or tasks are added in Mudstack. You can [import this into an Automation Rule](https://support.atlassian.com/cloud-automation/docs/import-and-export-jira-automation-rules/) and enter your webhook URL info Jira Template The sample will parse a ticket id found at in the `commitTitle` on the `commit_added` event. This allows us to map the message to a specific ticket in Jira ### Zapier A general Zap structure will contain the following: 1. Webhook catch (use the zap url in Mudstack, and generate some events to show in Zapier) 2. IF USING THE API, an Authentication step to use the API 3. Formatter for the Date/Time conversion 4. Paths to do specific action based on the `type` of event from Mudstack 5. Code to generate a url to the file for the message 6. API calls to enrich webhook data 7. Integration point to send the data out of Zapier Zapier Template #### Best Practices * Use **Paths** for splitting multiple event types in a single Zap * Use **Formatter** to convert Date / Time into something more human readable before sending to other systems. * You can use the **Code** block to concatenate assetIDs to generate links, make sure you pass in the input data from the webhook. These urls are only accessbile by users that have permssions in the account and workspace of the file. ```py theme={null} # Extract the input values account_id = input_data.get('accountId', '') workspace_id = input_data.get('workspaceId', '') asset_id = input_data.get('assetId', '') # Construct the URL using string formatting url = f"https://app.dev.mudstack.com/sh/asset/{account_id}/{workspace_id}/{asset_id}" # Prepare the output as a dictionary output = {'url': url} ``` ## Using the API with Webhooks Webhooks push essential event data, but often you’ll need more context. You can use the Mudstack API in conjunction with webhooks to: * Fetch full asset metadata from an asset\_id. * Retrieve commit details with a commit\_id. * Join user and workspace information to enrich webhook payloads, like the user name or other file metadata. Make sure to add this to your Automation 1. Make sure you have a step to [authenticate](/api-reference/authentication#using-the-api-key-%2B-secret-key) before using the API. 2. GET Requests to gather additional information The webhook response will contain the account, workspace, and object IDs for you to collect additional data from the API If you don't currently have your API Key, [ask us about generating your API Key](/api-reference/authentication#generating-api-key-%2B-secret-key) Example: * When a webhook sends asset\_created with only an asset ID, call the API to fetch additional fields like tags, linked versions, or folder structure. * Adding an attachment to a comment or review * Adding change context to a commit ### Best Practices with the API * When attempting to GET Attachments from a comment or review, make sure to have an error handler. This will allow you to support posting when it returns with an error if there are no attachments on the comment. * Make sure file attachments are uploaded to their destination, NOT referencing the url. Our file urls have a 15 min time limit, so they must be uploaded and stored elsewhere to have any permanence. # Working with workspaces Source: https://docs.mudstack.com/api-reference/workspaces Learn how to interact with workspaces in Mudstack using the API. ## Overview Workspaces in Mudstack are containers that organize and manage assets, libraries, tags, and other entities. Each workspace belongs to a specific account and is isolated from other workspaces. This means that all content within a workspace is accessible only through that workspace and cannot be shared across workspaces. ## Key Concepts ### Headers To interact with a workspace, you must include the following headers in every API request: * **x-workspace-id**: The unique identifier of the workspace. * **x-account-id**: The unique identifier of the account to which the workspace belongs. Without these headers, the API will not be able to identify the workspace or account, and the request will fail. ### Entities Within a Workspace Workspaces contain several entities, each with its own sub-entities. These include: * **Assets**: Files, images, videos, or other digital content. Assets can have versions, tags, comments, and attachments. * **Libraries**: Collections of assets grouped together for better organization. * **Tags**: Metadata used to categorize and search for assets. * **Members**: Users who have access to the workspace, with specific roles and permissions. * **Settings**: Configuration options for the workspace. * **History**: Logs of actions performed within the workspace. ## Common API Endpoints Below are some common endpoints for interacting with workspaces: ### Workspace Management * **Create a Workspace**: [POST /workspaces](./workspaces/create-workspace) * **Get Workspace Details**: [GET /workspaces](./workspaces/get-workspace) * **Update Workspace Details**: [PUT /workspaces](./workspaces/update-workspace) * **Delete a Workspace**: [DELETE /workspaces](./workspaces/delete-workspace) ### Member Management * **Get Workspace Members**: [GET /workspaces/members](./workspaces/members/get-members) * **Add Account Member to Workspace**: [POST /workspaces/members/\{user\_id}](./workspaces/members/create-member) * **Remove Member from Workspace**: [DELETE /workspaces/members/\{user\_id}](./workspaces/members/delete-member) For the Teams update, migrated teams cannot use this endpoint, as members access to a workspace is now defined as a rule on a team. ### Asset Management * To learn more about managing assets, see our [Assets Documentation](./assets) ### Folder Management * **Create a Folder**: [POST /workspaces/folders](./workspaces/folders/create-folder) * **Get a Folder**: [GET /workspaces/folders/\{folder\_id}](./workspaces/folders/get-folder) * **Move a Folder**: [PUT /workspaces/folders/\{folder\_id}](./workspaces/folders/move-folder) * **Delete a Folder**: [DELETE /workspaces/folders/\{folder\_id}](./workspaces/folders/delete-folder) * **Get folder hierarchy**: [GET /workspaces/folders/hierarchy](./workspaces/folders/get-hierarchy) ### Library Management * **Get All Libraries**: [GET /workspaces/libraries](./workspaces/libraries/get-libraries) * **Create a Library**: [POST /workspaces/libraries](./workspaces/libraries/create-library) * **Update a Library**: [PUT /workspaces/libraries/\{library\_id}](./workspaces/libraries/update-library) * **Delete a Library**: [DELETE /workspaces/libraries/\{library\_id}](./workspaces/libraries/delete-library) ### Tag Management * **Get All Tags**: [GET /workspaces/tags](./workspaces/tags/get-tags) * **Create Tags**: [POST /workspaces/tags](./workspaces/tags/create-tags) * **Delete Tag**: [DELETE /workspaces/tags/\{tag\_id}](./workspaces/tags/delete-tag) ### Tasks * **Create a new task**: [POST /workspaces/tasks](./workspaces/tasks/create-task) * **Get a specific task**: [GET /workspaces/tasks/\{task\_id}](./workspaces/tasks/get-task) * **Update a task**: [PUT /workspaces/tasks/\{task\_id}](./workspaces/tasks/update-task) * **Delete a task**: [DELETE /workspaces/tasks/\{task\_id}](./workspaces/tasks/delete-task) ### Settings Management * **Get Workspace Settings**: [GET /workspaces/settings](./workspaces/settings/get-settings) * **Update Workspace Settings**: [PUT /workspaces/settings](./workspaces/settings/update-settings) ## Example Request Here is an example of how to retrieve the details of a workspace: ```http theme={null} GET /workspaces HTTP/1.1 Host: api.mudstack.com Authorization: Bearer x-account-id: x-workspace-id: ``` ## Notes * Ensure that the `x-workspace-id` and `x-account-id` headers are included in every request to avoid authorization errors. * Workspaces are isolated, so entities like assets, libraries, and tags cannot be accessed outside their respective workspace. For more details on specific endpoints, refer to the API reference documentation for each entity. # Create attachment Source: https://docs.mudstack.com/api-reference/workspaces/assets/attachments/create-attachment post /workspaces/assets/{asset_id}/attachments Create a new attachment for a specific asset. # Delete attachment Source: https://docs.mudstack.com/api-reference/workspaces/assets/attachments/delete-attachment delete /workspaces/assets/{asset_id}/attachments/{attachment_id} Delete a specific attachment by its ID. # Download attachment Source: https://docs.mudstack.com/api-reference/workspaces/assets/attachments/download-attachment get /workspaces/assets/{asset_id}/attachments/{attachment_id}/download Download a specific attachment by its ID. # Get attachment Source: https://docs.mudstack.com/api-reference/workspaces/assets/attachments/get-attachment get /workspaces/assets/{asset_id}/attachments/{attachment_id} Retrieve a specific attachment by its ID. # Get attachments Source: https://docs.mudstack.com/api-reference/workspaces/assets/attachments/get-attachments get /workspaces/assets/{asset_id}/attachments Retrieve all attachments for a specific asset. # Update attachment Source: https://docs.mudstack.com/api-reference/workspaces/assets/attachments/update-attachment patch /workspaces/assets/{asset_id}/attachments/{attachment_id} Update a specific attachment by its ID. # Update thumbnail Source: https://docs.mudstack.com/api-reference/workspaces/assets/attachments/update-thumbnail post /workspaces/assets/{asset_id}/attachments/{attachment_id}/thumbnail Upload a thumbnail for a specific attachment by its ID. # Create comment Source: https://docs.mudstack.com/api-reference/workspaces/assets/comments/create-comment post /workspaces/assets/{asset_id}/comments Add a new comment to a specific asset. # Delete comment Source: https://docs.mudstack.com/api-reference/workspaces/assets/comments/delete-comment delete /workspaces/assets/{asset_id}/comments/{comment_id} Delete a specific comment by its ID. # Get comment Source: https://docs.mudstack.com/api-reference/workspaces/assets/comments/get-comment get /workspaces/assets/{asset_id}/comments/{comment_id} Retrieve a specific comment by its ID. # Get comments Source: https://docs.mudstack.com/api-reference/workspaces/assets/comments/get-comments get /workspaces/assets/{asset_id}/comments Retrieve all comments for a specific asset. # Update comment Source: https://docs.mudstack.com/api-reference/workspaces/assets/comments/update-comment put /workspaces/assets/{asset_id}/comments/{comment_id} Update the content of a specific comment by its ID. # Create or update asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/create-or-update-asset post /workspaces/assets Creates a new asset or updates an existing one. # Delete asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/delete-asset delete /workspaces/assets/{asset_id} Deletes an asset by its ID. # Delete assets Source: https://docs.mudstack.com/api-reference/workspaces/assets/delete-assets delete /workspaces/assets Deletes assets either permanently or soft deletes them. # Download asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/download-asset get /workspaces/assets/{asset_id}/download Downloads an asset by its ID. # Download assets Source: https://docs.mudstack.com/api-reference/workspaces/assets/download-assets post /workspaces/assets/download Downloads assets based on provided IDs and folders. # Favorite asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/favorites/favorite-asset post /workspaces/assets/{asset_id}/favorites # Unfavorite asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/favorites/unfavorite-asset delete /workspaces/assets/{asset_id}/favorites # Get asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/get-asset get /workspaces/assets/{asset_id} Retrieves an asset by its ID. # Get assets Source: https://docs.mudstack.com/api-reference/workspaces/assets/get-assets get /workspaces/assets/getByIds Retrieves assets by their IDs. # Get history Source: https://docs.mudstack.com/api-reference/workspaces/assets/history/get-history get /workspaces/assets/{asset_id}/history Retrieve the history of a specific asset. # Get review history Source: https://docs.mudstack.com/api-reference/workspaces/assets/history/get-review-history get /workspaces/assets/{asset_id}/history/review Retrieve the review history of a specific asset. # Abort a multi part upload to a temp location using the upload id Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/abort-a-multi-part-upload-to-a-temp-location-using-the-upload_id post /workspaces/import/upload/abort Abort a multi-part upload to a temporary location. Requires upload_id and key. # Begin a multi part upload to a temp location Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/begin-a-multi-part-upload-to-a-temp-location post /workspaces/import/upload/begin Begin a multi-part upload to a temporary location. Requires workspace_id and the sha of the file. # Check if a version exists by sha Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/check-if-a-version-exists-by-sha post /workspaces/import/exists/version Check if a version exists by SHA. Requires the SHA and optionally the asset_id. # Check if an asset exists by path Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/check-if-an-asset-exists-by-path post /workspaces/import/exists/asset Check if an asset exists by path. Requires file_location and file_name. # Complete a commit for the import Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/complete-a-commit-for-the-import post /workspaces/import/commit/complete Complete a commit for the import. Requires workspace_id, sync_commit_id. # Complete a multi part upload to a temp location using the upload id Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/complete-a-multi-part-upload-to-a-temp-location-using-the-upload_id post /workspaces/import/upload/complete Complete a multi-part upload to a temporary location. Requires upload_id, key, and upload_parts. # Create a commit for the import Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/create-a-commit-for-the-import post /workspaces/import/commit/create Create a commit for the import. Requires workspace_id, sync_commit_id, title, and description. # Create a version for an asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/create-a-version-for-an-asset post /workspaces/import/create/version Requires the commit_id, asset_id, and temp upload id. Adds the version with the file from the temp location and assigns the version to the commit. Returns version_id on success. # Create an asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/create-an-asset post /workspaces/import/create/asset Create an asset requires the commit_id, file_location, file_name, and temp upload id. Adds the asset, and a version with the file from the temp location. Assigns the asset/version to the commit. Returns asset_id, version_id on success. # Upload a part of a multi part upload to a temp location using the upload id Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/upload-a-part-of-a-multi-part-upload-to-a-temp-location-using-the-upload_id post /workspaces/import/upload/part Upload a part of a multi-part upload to a temporary location. Requires key, upload_id, part_no, mime_type, and optionally checksum. # Upload a single file to a temp location Source: https://docs.mudstack.com/api-reference/workspaces/assets/import/upload-a-single-file-to-a-temp-location post /workspaces/import/upload/single Upload a single file to a temporary location. Requires workspace_id, the sha of the file, and the content type. # Get libraries Source: https://docs.mudstack.com/api-reference/workspaces/assets/libraries/get-libraries get /workspaces/assets/{asset_id}/libraries Retrieve a list of asset libraries for a specific asset. # Lock asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/locking/lock-asset post /workspaces/assets/{asset_id}/lock Locks an asset by its ID. # Unlock asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/locking/unlock-asset post /workspaces/assets/{asset_id}/unlock Unlocks an asset by its ID. # Rename asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/rename-asset patch /workspaces/assets/{asset_id}/rename Renames an asset by its ID. # Restore asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/restore-asset patch /workspaces/assets/{asset_id}/restore Restores a soft-deleted asset by its ID. # Create review request Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviewRequests/create-review-request post /workspaces/assets/{asset_id}/reviewRequests/{user_id} # Delete review request Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviewRequests/delete-review-request delete /workspaces/assets/{asset_id}/reviewRequests/{user_id} # Get review requests Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviewRequests/get-review-requests get /workspaces/assets/{asset_id}/reviewRequests # Update review request Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviewRequests/update-review-request put /workspaces/assets/{asset_id}/reviewRequests/{user_id} # Create review Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviews/create-review post /workspaces/assets/{asset_id}/reviews Create a new review for a specific asset. # Delete review Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviews/delete-review delete /workspaces/assets/{asset_id}/reviews/{review_id} Delete a specific review by its ID. # Get review Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviews/get-review get /workspaces/assets/{asset_id}/reviews/{review_id} Retrieve a specific review by its ID. # Get reviews Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviews/get-reviews get /workspaces/assets/{asset_id}/reviews Retrieve all reviews for a specific asset. # Update review Source: https://docs.mudstack.com/api-reference/workspaces/assets/reviews/update-review put /workspaces/assets/{asset_id}/reviews/{review_id} Update a specific review by its ID. # Search asset ids Source: https://docs.mudstack.com/api-reference/workspaces/assets/search-asset-ids get /workspaces/assets/searchIds Searches for asset IDs based on query parameters. # Search assets Source: https://docs.mudstack.com/api-reference/workspaces/assets/search-assets get /workspaces/assets/search Searches for assets based on query parameters. # Create status Source: https://docs.mudstack.com/api-reference/workspaces/assets/status/create-status post /workspaces/assetStatuses Create a new asset status for the workspace. # Delete status Source: https://docs.mudstack.com/api-reference/workspaces/assets/status/delete-status delete /workspaces/assetStatuses/{status_id} Delete a specific asset status by its ID. # Get status Source: https://docs.mudstack.com/api-reference/workspaces/assets/status/get-status get /workspaces/assetStatuses/{status_id} Retrieve a specific asset status by its ID. # Get statuses Source: https://docs.mudstack.com/api-reference/workspaces/assets/status/get-statuses get /workspaces/assetStatuses Retrieve a list of all asset statuses for the workspace. # Update status Source: https://docs.mudstack.com/api-reference/workspaces/assets/status/update-status patch /workspaces/assetStatuses/{status_id} Update a specific asset status by its ID. # Get subscribers Source: https://docs.mudstack.com/api-reference/workspaces/assets/subscriptions/get-subscribers get /workspaces/assets/{asset_id}/subscriptions Retrieve a list of subscribers for a specific asset. # Update subscribers Source: https://docs.mudstack.com/api-reference/workspaces/assets/subscriptions/update-subscribers put /workspaces/assets/{asset_id}/subscriptions Update the subscription status for a specific asset. # Add tag Source: https://docs.mudstack.com/api-reference/workspaces/assets/tags/add-tag put /workspaces/assets/{asset_id}/tags/{tag_id} Add a specific tag to a specific asset. # Add tags Source: https://docs.mudstack.com/api-reference/workspaces/assets/tags/add-tags post /workspaces/assets/{asset_id}/tags Add one or more tags to a specific asset. # Get tag Source: https://docs.mudstack.com/api-reference/workspaces/assets/tags/get-tag get /workspaces/assets/{asset_id}/tags/{tag_id} Retrieve a specific tag associated with a specific asset. # Get tags Source: https://docs.mudstack.com/api-reference/workspaces/assets/tags/get-tags get /workspaces/assets/{asset_id}/tags Retrieve all tags associated with a specific asset. # Remove tag Source: https://docs.mudstack.com/api-reference/workspaces/assets/tags/remove-tag delete /workspaces/assets/{asset_id}/tags/{tag_id} Remove a specific tag from a specific asset. # Get tasks Source: https://docs.mudstack.com/api-reference/workspaces/assets/tasks/get-tasks get /workspaces/assets/{asset_id}/tasks Retrieve tasks associated with a specific asset within a workspace. # Update asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/update-asset patch /workspaces/assets/{asset_id} Updates an asset by its ID. # Cancel a multi part upload Source: https://docs.mudstack.com/api-reference/workspaces/assets/upload/cancel-a-multi-part-upload post /workspaces/assets/upload/multi/abort Cancels a multi-part upload and cleans up resources on S3. # Direct upload to a specified location Source: https://docs.mudstack.com/api-reference/workspaces/assets/upload/direct-upload-to-a-specified-location post /workspaces/assets/upload/direct Directly uploads a file to a specified location and returns a signed URL for the upload. # Finish a multi part upload Source: https://docs.mudstack.com/api-reference/workspaces/assets/upload/finish-a-multi-part-upload post /workspaces/assets/upload/multi/complete Completes the multi-part upload process. # Generate a signed url for a specific part Source: https://docs.mudstack.com/api-reference/workspaces/assets/upload/generate-a-signed-url-for-a-specific-part post /workspaces/assets/upload/multi/signedurl Generates a signed URL for uploading a specific part of a multi-part upload. # Start a multi part upload Source: https://docs.mudstack.com/api-reference/workspaces/assets/upload/start-a-multi-part-upload post /workspaces/assets/upload/multi/begin Initiates a multi-part upload process. # Uploads a file to a temporary location Source: https://docs.mudstack.com/api-reference/workspaces/assets/upload/uploads-a-file-to-a-temporary-location post /workspaces/assets/upload Uploads a file to a temporary location and returns a signed URL for the upload. # Uploads an asset and creates a new version or a new asset Source: https://docs.mudstack.com/api-reference/workspaces/assets/upload/uploads-an-asset-and-creates-a-new-version-or-a-new-asset post /workspaces/assets/upload/assets Uploads an asset to a temporary location and creates a new version or a new asset if it doesn't exist. # Create version Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/create-version post /workspaces/assets/{asset_id}/versions Create a new version for a specific asset. # Delete version Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/delete-version delete /workspaces/assets/{asset_id}/versions/{version_id} Delete a specific version of an asset. # Download version Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/download-version get /workspaces/assets/{asset_id}/versions/{version_id}/download Download a specific version of an asset. # Get version Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/get-version get /workspaces/assets/{asset_id}/versions/{version_id} Retrieve a specific version of an asset. # Get versions Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/get-versions get /workspaces/assets/{asset_id}/versions Retrieve all versions of a specific asset. # Restore version Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/restore-version patch /workspaces/assets/{asset_id}/versions/{version_id}/restore Restore a soft-deleted version of an asset. # Update thumbnail Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/update-thumbnail post /workspaces/assets/{asset_id}/versions/{version_id}/thumbnail Upload a thumbnail for a specific version of an asset. # Update version Source: https://docs.mudstack.com/api-reference/workspaces/assets/versions/update-version patch /workspaces/assets/{asset_id}/versions/{version_id} Update a specific version of an asset. # Create workspace Source: https://docs.mudstack.com/api-reference/workspaces/create-workspace post /workspaces Creates a new workspace with the given name and thumbnail. # Delete workspace Source: https://docs.mudstack.com/api-reference/workspaces/delete-workspace delete /workspaces Deletes the current workspace. # Download assets Source: https://docs.mudstack.com/api-reference/workspaces/download-assets post /workspaces/download/assets Downloads all assets in the current workspace. # Add assets Source: https://docs.mudstack.com/api-reference/workspaces/folders/add-assets post /workspace/folders/addAssets Add assets to a specific folder. # Create folder Source: https://docs.mudstack.com/api-reference/workspaces/folders/create-folder post /workspace/folders Create a new folder in the workspace. # Delete folder Source: https://docs.mudstack.com/api-reference/workspaces/folders/delete-folder delete /workspace/folders Delete a folder from the workspace. # Get assets Source: https://docs.mudstack.com/api-reference/workspaces/folders/get-assets get /workspace/folders/assets Retrieve assets in specific folders. # Get file types Source: https://docs.mudstack.com/api-reference/workspaces/folders/get-file-types get /workspace/folders/filetypes Retrieve file types for a specific folder. # Get folder Source: https://docs.mudstack.com/api-reference/workspaces/folders/get-folder get /workspace/folders Retrieve details of a specific folder. # Get hierarchy Source: https://docs.mudstack.com/api-reference/workspaces/folders/get-hierarchy get /workspace/folders/hierarchy Retrieve the hierarchy of folders in the workspace. # Get statistics Source: https://docs.mudstack.com/api-reference/workspaces/folders/get-statistics get /workspace/folders/stats Retrieve statistics for a specific folder. # Move folder Source: https://docs.mudstack.com/api-reference/workspaces/folders/move-folder post /workspace/folders/move Move a folder from one location to another within the workspace. # Get thumbnail Source: https://docs.mudstack.com/api-reference/workspaces/get-thumbnail get /workspaces/download Retrieves a signed URL for downloading the workspace thumbnail. # Get upload url Source: https://docs.mudstack.com/api-reference/workspaces/get-upload-url post /workspaces/upload Generates a signed URL for uploading a file. # Get workspace Source: https://docs.mudstack.com/api-reference/workspaces/get-workspace get /workspaces Retrieves the details of the current workspace. # Get history Source: https://docs.mudstack.com/api-reference/workspaces/history/get-history get /workspaces/history Retrieve the history of a specific workspace. # Add asset Source: https://docs.mudstack.com/api-reference/workspaces/libraries/assets/add-asset put /workspaces/libraries/{library_id}/assets/{asset_id} Adds an asset to a specified library. # Download assets Source: https://docs.mudstack.com/api-reference/workspaces/libraries/assets/download-assets post /workspaces/libraries/{library_id}/download Downloads assets from a specified library. # Remove asset Source: https://docs.mudstack.com/api-reference/workspaces/libraries/assets/remove-asset delete /workspaces/libraries/{library_id}/assets/{asset_id} Removes an asset from a specified library. # Create library Source: https://docs.mudstack.com/api-reference/workspaces/libraries/create-library post /workspaces/libraries Create a new library in the current workspace. # Delete library Source: https://docs.mudstack.com/api-reference/workspaces/libraries/delete-library delete /workspaces/libraries/{library_id} Delete a library by its ID. # Favorite library Source: https://docs.mudstack.com/api-reference/workspaces/libraries/favorites/favorite-library post /workspaces/libraries/{library_id}/favorites Adds the specified library to the user's list of favorite libraries. # Get favorites Source: https://docs.mudstack.com/api-reference/workspaces/libraries/favorites/get-favorites get /workspaces/libraries/favorites Retrieve a list of favorite libraries for the current user. # Unfavorite library Source: https://docs.mudstack.com/api-reference/workspaces/libraries/favorites/unfavorite-library delete /workspaces/libraries/{library_id}/favorites Removes the specified library from the user's list of favorite libraries. # Get file types Source: https://docs.mudstack.com/api-reference/workspaces/libraries/get-file-types get /workspaces/libraries/filetypes Retrieve file types for a library. # Get libraries Source: https://docs.mudstack.com/api-reference/workspaces/libraries/get-libraries get /workspaces/libraries Retrieve a list of all libraries for the current workspace. # Get library Source: https://docs.mudstack.com/api-reference/workspaces/libraries/get-library get /workspaces/libraries/{library_id} Retrieve a library by its ID. # Get recent Source: https://docs.mudstack.com/api-reference/workspaces/libraries/get-recent get /workspaces/libraries/recent Retrieves a list of recently used libraries. # Get stats Source: https://docs.mudstack.com/api-reference/workspaces/libraries/get-stats get /workspaces/libraries/stats Retrieve statistics for a library. # Get thumbnail Source: https://docs.mudstack.com/api-reference/workspaces/libraries/get-thumbnail get /workspaces/libraries/{library_id}/download Retrieve a signed URL for the library thumbnail. # Search libraries Source: https://docs.mudstack.com/api-reference/workspaces/libraries/search-libraries get /workspaces/libraries/name Retrieve a library by its name. # Update library Source: https://docs.mudstack.com/api-reference/workspaces/libraries/update-library put /workspaces/libraries/{library_id} Update a library by its ID. # Create member Source: https://docs.mudstack.com/api-reference/workspaces/members/create-member post /workspaces/members/{user_id} Add a user to the workspace with specified roles. # Delete member Source: https://docs.mudstack.com/api-reference/workspaces/members/delete-member delete /workspaces/members/{user_id} Remove a user from the workspace. # Get members Source: https://docs.mudstack.com/api-reference/workspaces/members/get-members get /workspaces/members Retrieve a list of members in the workspace. # Leave workspace Source: https://docs.mudstack.com/api-reference/workspaces/members/leave-workspace delete /workspaces/members/leave Remove the current user from the workspace. # Update member Source: https://docs.mudstack.com/api-reference/workspaces/members/update-member put /workspaces/members/{user_id} Update the roles of a user in the workspace. # Get setting Source: https://docs.mudstack.com/api-reference/workspaces/settings/get-setting get /workspaces/settings/{key} Retrieve a specific setting for the current workspace by key. # Get settings Source: https://docs.mudstack.com/api-reference/workspaces/settings/get-settings get /workspaces/settings Retrieve the settings for the current workspace. # Update setting Source: https://docs.mudstack.com/api-reference/workspaces/settings/update-setting put /workspaces/settings/{key} Update a specific setting for the current workspace by key. # Update settings Source: https://docs.mudstack.com/api-reference/workspaces/settings/update-settings put /workspaces/settings Update the settings for the current workspace. # Create tags Source: https://docs.mudstack.com/api-reference/workspaces/tags/create-tags post /workspaces/tags Create new tags for the specified workspace. # Delete tag Source: https://docs.mudstack.com/api-reference/workspaces/tags/delete-tag delete /workspaces/tags/{tag_id} Delete a specific tag for the specified workspace. # Get recent Source: https://docs.mudstack.com/api-reference/workspaces/tags/get-recent get /workspaces/tags/recent Retrieve recently used tags for the specified workspace. # Get tag Source: https://docs.mudstack.com/api-reference/workspaces/tags/get-tag get /workspaces/tags/{tag_id} Retrieve a specific tag for the specified workspace. # Get tags Source: https://docs.mudstack.com/api-reference/workspaces/tags/get-tags get /workspaces/tags Retrieve all tags for the specified workspace. # Update tag Source: https://docs.mudstack.com/api-reference/workspaces/tags/update-tag patch /workspaces/tags/{tag_id} Update a specific tag for the specified workspace. # Create task Source: https://docs.mudstack.com/api-reference/workspaces/tasks/create-task post /workspaces/tasks Creates a new task in the workspace. # Delete task Source: https://docs.mudstack.com/api-reference/workspaces/tasks/delete-task delete /workspaces/tasks/{task_id} Deletes a task by its ID. # Get task Source: https://docs.mudstack.com/api-reference/workspaces/tasks/get-task get /workspaces/tasks/{task_id} Retrieves a task by its ID. # Get tasks Source: https://docs.mudstack.com/api-reference/workspaces/tasks/get-tasks get /workspaces/tasks Retrieves tasks for a workspace # Update task Source: https://docs.mudstack.com/api-reference/workspaces/tasks/update-task put /workspaces/tasks/{task_id} Updates a task by its ID. # Empty trash Source: https://docs.mudstack.com/api-reference/workspaces/trash/empty-trash post /workspaces/trash/empty Empties the trash in the current workspace. # Restore assets Source: https://docs.mudstack.com/api-reference/workspaces/trash/restore-assets post /workspaces/trash/restore Restores soft-deleted assets in the current workspace. # Restore folder Source: https://docs.mudstack.com/api-reference/workspaces/trash/restore-folder patch /workspace/folders/restore Restore a previously deleted folder in the workspace. # Update workspace Source: https://docs.mudstack.com/api-reference/workspaces/update-workspace put /workspaces Updates the details of the current workspace. # Get usage Source: https://docs.mudstack.com/api-reference/workspaces/usage/get-usage get /workspaces/usage Retrieves the current usage statistics of the workspace. # Annotations Source: https://docs.mudstack.com/features/annotations Draw anywhere on your monitor Mudstack supports annotating anywhere on your monitor(s)— in app or in Maya/Unreal etc. Pictures speak louder than a thousand words, which is why as a lead or art director, you regularly take screenshots of work in progress and mark it up with various tools to share feedback with your artists. Doing this outside of Mudstack is cumbersome, and the annotated feedback itself can easily get lost when it is disconnected from the artwork itself. ## Why Annotate in Mudstack When you annotate files in Mudstack, you ensure that the annotated feedback is always connected to the file rather than disconnected in Jira/Trello/Slack etc. Due to how our annotation toolbar works, you can share annotated feedback on any file type— even those that Mudstack doesn't support for preview, such as Maya, ZBrush, Substance etc, by annotating directly in those apps and keeping that annotation connected to the file in your Mudstack workspace. ## How to Annotate To annotate via Mudstack, you must be using the [desktop application](/getting-started/desktop-application). Because our annotation tools allow you to draw anywhere on your monitor, it does not work via the browser app. annotations in Mudstack **Start an annotation**: 1. You must be leaving a comment or a review to add an annotation. 2. Launch the annotation tool by clicking the pencil icon in the comment box. 3. Organize your windows and monitors as you would like them to appear (you can deselect unnecessary monitor screens later). 4. Click one of the annotation tools— pencil or text, and start drawing or writing on the screen. 5. You can change the color by selecting one of the color presets. 6. You can move the entire toolbar by clicking the Mudstack icon or `Annotate` text on the toolbar and dragging. 7. Use the eraser tool to delete parts of your annotation, the undo or redo buttons to step back or forwards and the delete button to clear the annotation. 8. Once you're done, you can click `Submit Annotation`. If you decide not to annotate, you can click the `×` to close the toolbar. 9. You will see a screenshot of your annotation in the comment box. The annotation tool captures all connected monitors, you can delete any unwanted monitor screencaptures at this point inside the comment box before submitting. ## Viewing Annotations Submitted annotations can be viewed from the attachments section for a file. ### Annotation Improvements We have a few planned improvements to our annotation toolbar on our roadmap: 1. Allow the user to title each annotation. 2. Allow the user to select a monitor or window to capture rather than all connected monitors. # Conflicts Source: https://docs.mudstack.com/features/conflicts Resolving conflicts in Mudstack. Conflicts occur when you have local changes to a file, but someone else pushed a change to the same file since you last pulled. ## Where to View Conflicts Conflicts are shown on changes in the `Changes` view. This could happen in either the **Unstaged Changes** or **Staged Changes** section, depending on the timing on the conflicting change. If a local change is in the Unstaged Changes section when Mudstack detects a conflict, that change cannot be staged and pushed till the conflict is resolved. If the change has already been staged, and then the conflict is detected, it will not be included in the push till you resolve the conflict. View and fix conflicts The conflicting change will show in an `In Progress` push in the **Push History**. You can select the push to see the details of that push, which should include the conflict as well for the file in question. To resolve the conflict, click the `Fix Conflict` button. This will open a modal showing you the conflicting changes and give you the option to either select the cloud changes or your changes in order to resolve the conflict. If there are multiple conflicts (for example, due to the location change of files), you can also batch select whether you want cloud or local changes to apply from this modal. ### Resolving Data Conflicts Changes to a file's name, location, tags or libraries are considered data changes. A conflict can be triggered if you make changes to a file's data locally and someone else has pushed changes to the same data for the file to the cloud. If a data conflict occurs, either your local changes or the cloud changes will be overwritten depending on the action you take: **If you pull the cloud changes**, your local changes will be removed. **If you push your local changes**, the cloud will match your local changes. ### Resolving File Version Conflicts what causes a version conflict? File version conflicts will occur if someone (e.g. Artist B) makes local changes to a file they pulled from the cloud, and then someone (e.g. Artist A) else creates and pushes a new version of the same file to the cloud first. Whenever a file version conflict occurs, you ***will not*** lose any data if you keep cloud changes or push your local changes. **If you pull the cloud changes**, your local changes will remain untouched and won't affect the current version. The recently pulled version can be found in the file's [versions](/features/version-control) tab. You have the flexibility to choose any available version from that file and set it as the active version. **If you push your local changes**, the cloud version tree will display a "broken" link connecting your version with the previous cloud version. # Custom Attributes Source: https://docs.mudstack.com/features/custom-attributes Configure workspace-specific metadata fields on files Custom attributes let you define your own metadata fields on files in a workspace—things like production status, external IDs, links to tools like Jira or Miro, or technical data such as poly counts. This page covers how workspace admins configure attributes, how users edit values on files, how filtering works, and how attributes appear in the API. In the initial release, custom attributes only apply to **files**. Later releases will add support for folders, file versions, libraries, and workspace-level attributes. ## Who Can Use Custom Attributes * **Workspace admins** * Create, edit, reorder, duplicate, and delete custom attributes. * Decide which attributes are **filterable**. * **Users with upload access** * Edit **values** for custom attributes on files. * **All users who can view files** * See filterable custom attributes in the **Files** view filters. ## Attribute Primitives and Types In general, custom attributes have: * **Name** — the label shown in the UI (must be unique). * **Primitive** — the underlying data type. * **Type** — how values are entered or constrained for that primitive. Supported **primitives**: * **Text** — Free-form text. * **Number** — Numeric values. * **Boolean** — True/false values. * **Date** — Date. Supported **types**: * For **Text** and **Number**: * **Any value** — Users can enter any value of the appropriate primitive. * **Select** — Users pick a single option from a predefined list. * **Multi-Select** — Users pick one or more options from a predefined list. * For **Boolean** and **Date**: * These do **not** have a separate Type setting; the value is always a single Boolean or Date. All attributes: * **Must have a unique name** within the workspace. * Are **visible** on all supported objects (currently **files only**). Attribute visibility controls (for example, hiding certain attributes from specific views or users) are not available yet, but are planned for a future release. ## Managing Attributes The custom attributes admin page To configure which attributes exist in a workspace: 1. Open the Mudstack desktop app. 2. Go to **Workspace Settings**. 3. Open the **Custom attributes** page. Only **workspace admins** can see and use the Custom attributes page. ### Discriminators Discriminators let you target specific sets of objects with different attribute configurations based on a **query**. * A **discriminator** defines which files a given attribute set applies to (for example, files in a certain path, with a certain extension, or matching other file metadata). * If there is **no discriminator**, the attribute set applies to **all files** in the workspace. * There is **one shared draft per discriminator (or per object when there is no discriminator)**. All workspace admins editing that discriminator work on the same draft. Future releases will extend discriminators so you can configure attributes for other object types (folders, file versions, libraries, workspaces) using similar query-based rules. Behavior: * The **draft is saved to the cloud automatically** as you make changes. * There is only **one draft per discriminator (or per object when there is no discriminator)**. * Other workspace admins see the same draft and can collaborate on it. * Changes in the draft do **not** affect files until you **promote** it. For the first release of custom attributes, we will only support Files as one discriminator. ### Create a New Attribute Creating and Editing an attribute To add a new attribute to the current discriminator’s draft: 1. Click **Create a new attribute**. 2. A new row appears at the bottom of the attribute list. 3. Set the **Name** (must be unique). 4. Set the **Primitive**: * **Text** * **Number** * **Boolean** * **Date** 5. Set the **Type** (for **Text** and **Number** primitives only): * **Any value** * **Select** * **Multi-Select** * For **Boolean** and **Date**, Type is fixed and not editable. 6. (Optional) Click **Options**: * For **Select** and **Multi-Select**, define the list of allowed options and any relevant validation (e.g. required, max selections). * Set a **default value** (can be empty). 7. Toggle **Show in filters** if you want this attribute to appear in the Files view filter list (see [Filtering and Searching](#filtering-and-searching-by-custom-attributes)). Adding many custom attributes to the filters list can **slow down search and filtering**. Prefer only marking attributes as filterable when they are truly needed for discovery. #### Required Dropdown Values For **Select** and **Multi-Select** attributes: * Attributes that are configured as active/required must have a **valid value** before you can save changes. * If a dropdown-type attribute is missing a required value: * The attribute row shows a **warning** indicating it’s incomplete. * You must resolve the warning (set a valid value) before the change can be pushed. ### Edit an Existing Attribute Within the draft, you can update: * **Name** * **Type** (within the same primitive, where applicable for Text/Number) * **Options** (for Select / Multi-Select) * **Default value** * **Filterable / Show in filters** toggle * **Order** in the list Editing rules: * You **cannot change the Primitive** of an attribute after it has been created and promoted. * If you need a different primitive (for example, changing Text to Number), create a **new attribute** and migrate values as needed. To edit: 1. Locate the attribute in the list. 2. Use the **edit** button to update: * Name of the attribute. * If the attribute is filterable. 3. **Drag** the attribute to change its order. This order controls how attributes appear on files and in filter lists. All edits you make here are part of the **draft** and are saved automatically. ### Delete an Attribute 1. Find the attribute in the draft list. 2. Click the **Delete** button on that row. 3. Confirm deletion when prompted. When an attribute is deleted and the draft is later **promoted**: * Existing values on files are **preserved on the record** until the next write to that file, but the attribute will no longer be editable. * The attribute is removed from the workspace configuration and will no longer appear in the UI or filters. ### Reordering Attributes You can drag attributes in the draft list to change their order. * The order on the **Custom attributes** page controls: * The order attributes appear on files. * The order filterable custom attributes appear in filter lists. Creating attributes **always adds them to the end** of the list. Creating attributes directly in-between other attributes by specifying a position is **not** supported in this release. ### Promoting Attribute Changes Editing attribute values as an artist When you are happy with the draft: 1. Click **Promote** (or the equivalent promote action) on the Custom attributes page. 2. Mudstack validates the **entire draft**: * Attribute names are unique. * Attribute definitions are compatible with existing data as required. * Filter and option configurations are consistent. 3. If validation fails, you’ll see errors to correct in the draft before you can promote again. 4. If validation succeeds, the draft becomes the new **promoted** configuration for that discriminator. Changing attribute definitions (including create, edit, delete, reorder) **does not** generate local file value changes or commits by itself. Only editing attribute **values** on specific files produces local changes. ## Attribute Values on Files Editing attribute values as an artist ### Editing Values With upload access, you can edit values for any custom attribute defined in the workspace: 1. Open a file. 2. Go to the **Info** tab. 3. Scroll to **Custom attributes**. 4. Update the value for the attribute you want to change. Behavior: * All supported primitives and types are editable: * **Text** (Any value, Select, Multi-Select). * **Number** (Any value, Select, Multi-Select). * **Boolean**. * **Date**. * Attributes appear in the order defined on the Custom attributes page. * Changes to attribute values are treated like other local changes: * They appear in the **Changes View**. * Pushing the change creates a **web-based commit**, just like edits to built-in attributes. ### When Values Are Updated * Local edits to attribute values become part of your workspace’s history once pushed. * Users see updated attribute values as soon as: * The commit containing the changes is synced, and * They fetch or refresh data for those files. ## Filtering and Searching by Custom Attributes Filterable custom attributes can help your artists find files based on your own custom criteria. ### Making Attributes Filterable * Each attribute has a **Filterable** option that can be toggled on the Custom attributes page. * Only attributes marked as **filterable** appear in the filters panel in the files view Each additional filterable custom attribute adds overhead to search and filtering. For the best performance, limit filterability to attributes that are actually used for discovery. ### Using Custom Attributes as Filters To filter by a custom attribute: 1. Open **Files**. 2. Open the **Filter** panel. 3. In the filter list, you’ll see: * Built-in (base) attributes. * Any custom attributes marked as **filterable**. 4. Click a filterable custom attribute to see its available **facets** (values). 5. Click a facet to filter files by that attribute value. ## API Behavior for Custom Attributes Custom attributes are available through the API both at the **definition** level and on individual objects. See the API documentation for more information ### Attribute Definitions in API Responses When you request an object that uses custom attributes, the response includes information about the attributes that exist in the workspace. For each attribute definition, the API includes at minimum: * **title** - Attribute Name * **type** - Primitive * **enum** - (if the type supports options, such as Select or Multi-Select) * **displayorder** - Order of an attibute on an object Filterable attributes will show under **searchable** ### Attribute Values on Objects For each **file** with custom attributes, the object’s representation includes at minimum: * **Attribute name** * **Primitive and Type** * **Value** Future releases will extend this behavior so that folders, file versions, libraries, and workspace-level entities expose their own custom attributes and values through the API. > **Note:** Attribute and value CRUD endpoints are exposed via the API. External tools and plugins can create/update attributes and attribute values, and those changes will be reflected in the app once fetched. ## How plugins work with custom attributes [Plugins](/developer/plugin-system) can: * Read workspace custom attribute definitions and values. * Create or update custom attribute values. * Create or update attribute definitions via the API (where permitted). This enables workflows such as: * Automatically populating a custom attribute from an external system (e.g. Jira ticket IDs, contract IDs). * Keeping a large dropdown list in sync with external data (e.g. IP or contract lookup tables maintained outside Mudstack). * Interrogating a file on new version and updating custom attributes (e.g. Poly count, material count, image dimensions) # Disk Management Source: https://docs.mudstack.com/features/disk-management Control how Mudstack uses your disk space Downloading and storing files can eat up quite a bit of your hard drive. Use these tools to help reduce disk usage for especially large workspaces or files. Go to `Settings → App Settings → Cloud Workspaces` to manage disk usage across all of your mapped workspaces. Depending on how much data you are storing, this page may take some time to load. ## Store Cloud The `Store Cloud` option (default is unchecked) will store a copy of every downloaded file in the workspace’s version store (`/.mudstack`). Leave this unchecked unless you want to have local copies. ## Keep Local `Keep local` (default is checked) will store a copy of every file you have pushed to a workspace in the workspace’s version store (`/.mudstack`). Unchecking this will give you back space whenever you push new files and versions to your cloud workspace ## Cleanup Workspace The Cleanup Workspace action will clean your current version store of any files that do not match the settings you have defined for that workspace. You wil see this button in the `Actions` column for each mapped cloud workspace. In the event you have a lot of excess disk usage before version `1.3.6`, this action may provide you with more space. # Local Version Limits You can configure how many local versions Mudstack should keep for each parent cloud version. Once you exceed the limit, the oldest version is deleted so you can reclaim disk space. Local Version limits configuration This option is accessible in `Settings → Local Versions`. If left at `0`, Mudstack will keep an unlimited number of local versions, which can cause disk space issues. You should adjust this based on your workflow and preferences. # Disable Syncing on a file or folder Click the `Disable Syncing` icon in the top right of a synced file/folder or Right click → `Disable Syncing` To see more about managing sync, please read how to [disable auto syncing](/features/pull-and-sync#disable-auto-syncing). # Cleanup old local versions Go to [saving space with versions](/features/version-control#saving-space-with-versions) to remove old local versions and prevent accrual of old versions for future changes. # Libraries Source: https://docs.mudstack.com/features/libraries Contextual collections of your files. Having a well considered folder structure and good file naming conventions for your game project is just part of good game development practices. The reality is however, that it is the rare studio and team that is actually able to stick to these ideal methods. Mudstack supports both a structured folder based set up as well as a more contextual grouping of files. Sometimes you just want to see all subsets of files associated with a specific level in the game, or by the character modeling team or some other contextual logic. With only a folder based file organization system, this is impossible to do without duplication of files. That's where **libraries** come in. ### What Are Libraries, Exactly? Think of libraries as a [tag](/features/tags) with special properties— they get their own view in Mudstack. When a file gets added to a library, you can see it from that library view without the context of its folder hierarchy. Mudstack reports on the review status of library content in the form of a library health indicator. Deleting a library has no impact on any files in that library, except the removal of the library property from that file's metadata. ### How to Use Libraries Teams commonly use libraries to group files by level, sprint, team, and asset type to view these collections without the distraction of a folder structure. The imagination is your limit when it comes to the purpose of a library. Because libraries are cheap in Mudstack (remember that deleting a library does not delete the files within!), you can try out a few different contextual groups to see what makes the most sense for your team. ## Adding Files to Libraries From any search view, you can select one or more files and add the selection to one or more libraries: 1. Right click after selecting files and choose `Add to Library`, or 2. Use the right sidebar to click the `Add to Library` button Once you've completed this step, you'll be able to explore and designate the specific library or libraries you wish to incorporate your selection into. Additionally, you can add a file to libraries via the file details view. Simply navigate to the file info tab on the right sidebar and click to initiate the process. ## Syncing Libraries When on the desktop app, any changes you make to a library places it into the [push](/features/push) table for syncing with your cloud workspace. If you apply a library to a file, that file gets added to the push table. When Mudstack [pulls](/features/pull-and-sync) any new library changes from the cloud, these changes will be available to you locally. ## Removing Files from Libraries The easiest method of removing files from a library is to go into that library and select the files you want to remove. Next, you can click the delete icon next to the library name in the right sidebar to remove these files from the library. Remember that removing a file from a library does not impact the file itself other than the removal of the library association from its metadata! # MCP Source: https://docs.mudstack.com/features/mcp Use MCP to connect Mudstack with Claude, GPT, Cursor, or VSCode and manage assets with AI. The Model Context Protocol (MCP) integration lets Mudstack connect directly to AI clients like Claude, GPT, Cursor, and VSCode. Once connected, your LLM can securely search, tag, rename, lock, and comment on assets inside your workspaces — all through structured tool calls. Configure the MCP server once, authenticate with your account ID, and your AI will have everything it needs to work with your libraries and projects. ## Setup Instructions ### General 1. Ensure your LLM client supports MCP (Claude Desktop, GPT, Cursor, VSCode). 2. Configure your client’s MCP settings file (examples below). 3. Start the client — you will be prompted for authentication 4. Some clients require a restart after authentication (Claude Desktop). 5. Others (VSCode, Cursor) typically don’t require a restart. It is important to have your account ID, as every MCP call requires it. Your account ID is easiest to grab by copying a link from a file in the app. `https://app.mudstack.com/sh/asset/9c8f1e7a-2d34-4f71-b58c-7e9d2a3f4b10/2e7c4d8a-91f2-4c73-8f6b-1a0e5bc9d432/ab51f7c0-38d2-4e1b-b927-3f68a2cd8e4f` The account ID is the first ID string in this URL `9c8f1e7a-2d34-4f71-b58c-7e9d2a3f4b10`. For your first message, write `Get account data for 9c8f1e7a-2d34-4f71-b58c-7e9d2a3f4b10` You should receieve a summary of your account data if everything is connected properly. Once you provide the account ID once, the LLM will remember it. Using the get-account-data tool, the LLM can fetch all workspace IDs and metadata. This allows you to reference workspaces by name, while the model will infer the correct IDs automatically. ### Chat GPT (Web) 1. Click on your profile icon in the bottom left and select `Settings` 2. Click on `Connectors` in the left hand column 3. Click the `Create` button in the top right, and configure the server. The MCP Server URL is `https://mcp.mudstack.com/mcp`, and the authentication is `Oauth`. 4. Trust the aplication and create the server 5. You'll see an authentication window appear. Select `allow` 6. When you are ready to use the server, click the `+` icon, click on `More`, and select `Developer Mode`. Click the dropdown `Add Sources` and select the Mudstack MCP server. ### Claude Desktop 1. The Mudstack MCP Server and many other MCP servers require Node.js to run. Verify your Node.js installation by opening a terminal and running: `node --version` 2. Open Claude Desktop Settings: Click on Claude in your system's menu bar and select `Settings...` 3. Access Developer settings: In the settings window, navigate to the `Developer` tab in the left sidebar. Click the `Edit Config` button to open the configuration file (located at `~/Library/Application\ Support/Claude/claude_desktop_config.json`) 4. Open the file and configure the Mudstack Server 5. A browser window should open, complete the authentication process 6. Restart Claude Desktop ```json theme={null} { "mcpServers": { "mudstack": { "command": "npx", "args": ["mcp-remote", "https://mcp.mudstack.com/mcp"] } } } ``` ### VSCode 1. Make sure [mcp is enabled](vscode://settings/chat.mcp.enabled) in your application 2. Run the command `MCP: Add Server` (`Ctrl`+`Shift`+`P` or `CMD`+`Shift`+`P` then search for `MCP: Add Server`) 3. Select `HTTP (HTTP or Server-Sent Events)` 4. For the url enter `https://mcp.mudstack.com/mcp` 5. Name the `Mudstack` and press enter 6. Choose either `Global` or `Workspace` for the install, we recommend `Global` 7. You'll see an authentication window appear. Select `allow` 8. Select `MCP` as the account to sign into `https://mcp.mudstack.com/mcp` 9. For the chat window, make sure your mode is set to `Agent` and the Mudstack MCP tools are selected (click the wrench icon in the bottom right to check this) ```json theme={null} { "servers": { "mudstack": { "url": "https://mcp.mudstack.com/mcp", "type": "http" } }, "inputs": [] } ``` ### Cursor 1. Open Cursor Settings: Click on Cursor in your system's menu bar and select `Settings -> Cursor Settings` 2. Click on `Tools` in the left hand column 3. If you have no MCP Tools, click `Add Custom MCP`, otherwise click on the `+` button to add a new mcp server 4. Configure the Mudstack mcp server 5. You'll see an authentication window appear. Select `allow` ```json theme={null} { "mcpServers": { "mudstack": { "url": "https://mcp.mudstack.com/mcp", "type": "http" } } } ``` OR ```json theme={null} { "mcpServers": { "mudstack": { "command": "npx", "args": ["mcp-remote", "https://mcp.mudstack.com/mcp"] } } } ``` ## Available Tools ### `get-account-data` Gets account information for the provided account ID. **Parameters:** * `account_id` (string, required) **Purpose:** Returns roles, IDs, and workspace information.\ **Use case:** “What workspaces do I have access to?” *** ### `search-assets` Searches for all assets in a workspace. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `folder` (string, optional) * `library_id` (string, optional) * `asset` (string, optional) **Purpose:** Flexible filesystem search. Returns asset IDs and metadata.\ **Use case:** “Find all assets in `/scenes` with ‘car’ in their name.” *** ### `lock-asset` Locks a specified asset. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `asset_id` (string, required) **Use case:** Batch lock assets for editing. *** ### `unlock-asset` Unlocks a specified asset. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `asset_id` (string, required) **Use case:** Undo a Lock. *** ### `create-comment` Adds a comment to an asset. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `asset_id` (string, required) * `content` (string, required) **Use case:** “Add a ‘looks good!’ comment to all `.jpg` files.” *** ### `get-tags` Fetches all tags in a workspace. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) **Purpose:** Enables tag-aware tool calls. *** ### `add-tag` Adds a tag to an asset. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `asset_id` (string, required) * `tag_id` (string, required) **Use case:** Bulk classification (e.g., add “summer” tag to all `/scenery` images). *** ### `create-tag` Creates a new tag in the workspace. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `tag_name` (string, required) * `tag_color` (string, optional) **Use case:** Create tags dynamically for workflows. *** ### `update-tag` Updates an existing tag in the workspace. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `tag_id` (string, required) * `tag_name` (string, required) * `tag_color` (string, optional) **Use case:** Update `Phase-1` tag to `Phase-2`, and change the color to red. *** ### `rename-asset` Renames a specific asset. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `asset_id` (string, required) * `new_name` (string, required) **Use case:** Append `-finished` suffix to all assets in `/parts`. *** ### `asset-history` Gets the version history of an asset. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `asset_id` (string, required) * `num_versions` (integer, optional) **Purpose:** Summarize commits, renames, reviews, etc.\ **Use case:** “Show all changes on this asset in the last 2 weeks.” *** ### `purge-old-versions` Deletes old versions of an asset. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `asset_id` (string, required) **Use case:** Clean up all completed assets in `/finished`. *** ### `search-commits` Search for commits in a specific workspace. **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `num_commits` (number, optional) **Use case:** Search for commits with in the last month the name `Robot`. *** ### `get-commit-details` Get the details of a specific commit **Parameters:** * `account_id` (string, required) * `workspace_id` (string, required) * `commit_id` (string, required) **Use case:** Give me a list of changes in the commit `Updated character mesh`. ## FAQs When you first configure the Mudstack MCP server in your client, you’ll be prompted to authenticate. Some clients (Claude Desktop) may require a restart afterwards. See the Available Tools section for a complete list. Your access depends on your account roles and workspace permissions. # Ignore Files & Folders Source: https://docs.mudstack.com/features/mudignore How to ignore files and folders within a Mudstack workspace. mudstack allows you and your team to ignore specific paths, folders, files by creating and editing the `.mudignore` file. To use mudignore, create a text file in the root folder of a workspace and set the name to `.mudignore`. The extension for the file is `.mudignore` and the name is empty. If there is no `.mudignore` file, we will return to the default list of files to ignore. By default, here is what we ignore: ``` # folders to ignore /.mudstack .git .godot # # files to ignore .gitconfig .gitignore .place-holder .DS_Store *.lock *.painter_lock *.assbin *.temp *.tmp *.blend1 *.pyc ``` ## Patterns in mudignore Each line is a rule **Blank Line** matches nothing **Comments** must start with # Quote any rules that would include spaces `“folder name/file name.txt”` `!` includes what should be excluded. If there is a rule `*.txt` , `!item.txt` will include any .txt files with the name “item”. `/` is a separator for directories. Leading separators like `/item` searches for “item” from the root folder. The results include both files and folders. Separators after a term like `item/` searches for a folder “item”. Build a folder path with separators like `/folder1/folder2/file`. `*` matches every character except `/`. `?` matches one character except `/`. Range notation `[a-zA-Z]` will match one of the characters in a name. `/**` matches everything inside a folder like `folder/**`. `**/` matches zero or more directories. `a/**/b` matches `a/b`, `a/x/b`, `a/x/y/b` and so on. Additional `*` are considered regular asterisks and will match according to the previous rules. ## Pushing and pulling mudignore `.mudignore` works exactly like other files when you push or pull changes. It has it’s own version history, so all version actions are available to you. ## FAQ Nothing, they will still stay in the cloud, but when they are pulled down, they will not be managed by Mudstack. For files that didn’t exist before a rule was set, the file will not appear in the search, nor will it be stored in Mudstack db. For files that were watched by Mudstack before being ignored, they will be flagged as ignored in the Mudstack db. Your data will still be stored locally if you undo this action. Note that they may appear as missing after updating the mudignore file. You may disable sync or send the file/folder to the trash to resolve the missing item. They will be watched by Mudstack and added to your local Mudstack db. Any files that existed before the initial ignore will have their metadata restored. * There may only be one mudignore file placed at the root of a workspace. * The `.mudstack` folder will always be ignored, regardless of whether you remove this rule from your `.mudignore` file. * When an ignore rule is defined as a folder (ending in /), then the regex should allow paths that do not end in a slash (e.g. a file) # Notifications Source: https://docs.mudstack.com/features/notifications Get notified about important activity in your account. ## Real-time Notifications Mudstack offers a Slack webhook integration that allows you to send real-time event activity for a Mudstack Workspace to a selected Slack channel. A Discord integration is currently planned. ### Slack Integration Slack integration We recommend selecting or creating one Slack channel per Mudstack workspace that you would like to set up real-time notifications for. Events that generate a notification include: **Files** * Add file * Add file version **Workspace** * Create Folder * Create library * Create tag **Review & Feedback** * Change request * Approval * Review request * New comment ### Setting it up 1. Create an app for your Slack workspace [here](https://api.slack.com/apps). You need to be a Slack account admin to do this. Slack app creation 2. Select a channel to send the messages to. 3. Get the webhook URL of the bot (click the `Copy` button) and email it to us at [support@mudstack.com](mailto:support@mudstack.com) and we can finish the setup. Slack app creation For each new channel you want to send notifications to, you need a separate webhook URL. Click the `Add New Webhook to Workspace` button and send it to us to finish set up. `mudstack Workspace 1 → Slack channel 1 = Webhook URL 1` `mudstack Workspace 2 → Slack channel 2 = Webhook URL 2` ## Other Integrations Use our [webhooks](/api-reference/webhooks) and [API](/api-reference/getting-started) to build out the messages to task management apps, chat apps and more! # Pulling & Syncing Data Source: https://docs.mudstack.com/features/pull-and-sync Stay synced with your team's changes. ## Auto Pulling Changes ### Fetching changes Mudstack automatically fetches and pulls changes from the cloud once per minute. When you see the fetch icon in the toolbar spin, this means that Mudstack is performing a fetch. how to tell when Mudstack is fetching changes This ensures that you are seeing the latest data in app— files (including activity and new versions), folders, locations, tags, libraries, review and change requests etc. ### Pulling Changes If there are changes available to pull, you will see the fetch icon in the top right spin, and Mudstack will automatically start pulling all the changes. To see what data is getting pulled, you can click on `Changes` to look at the pull history. The files themselves are not downloaded to your disk unless they are [auto sync enabled](/features/pull-and-sync#enable-auto-syncing). ## Enable Auto Syncing If you want to stay in sync with a file, folder or library, you can now enable auto syncing for your selection. This will ensure that you always see the **latest** file version(s) in your local working directory. Remember that enabling auto sync ***only automatically pulls*** changes from the cloud. Changes you make locally still need to be [pushed](/features/push) to the cloud, as this is not an automated process. ### File Auto Sync To set up file auto sync, select the file(s), and click the cloud icon or right-click and choose `Enable File Syncing`. See how to [download older file versions](/features/version-control#downloading-a-version) if you need an older version on disk. ### Folder Auto Sync Similar to file syncing, you can stay in sync with folders by either selecting the folder(s), and clicking the download icon or right clicking and choosing `Enable File Syncing`. This will ensure that the contents of the selected folder(s) is always available to you on disk, including new files and folders added by others. Folders with auto sync enabled will appear green in app compared to non-autosyncing folders, which appear purple. If you create new folders inside an autosynced folder, they do not automatically get autosynced for you. You will need to enable auto syncing for these folders. When others pull your changes, *however*, they will get these folders with auto sync enabled if they are also auto synced to the parent folder. ### Library Auto Sync To stay in sync with a [library](/features/libraries), enable auto sync either from the Libraries or library details view. This will ensure that files added to or removed from this library by anyone else will appear on your disk in their correct folder structure. ## Disable Auto Syncing If you no longer need the latest content— file, folder or library— to be available to you locally, you can disable syncing for that selection. Much like enabling syncing, you can also disable syncing: * Click the cloud check icon on a file, or * Select `Disable File Syncing` via the right-click menu. Doing this will remove the file(s) from your working directory, freeing up disk space but will leave them untouched in the cloud. You can re-enable syncing at any point if you change your mind. ### Disable Folder or Library Auto Sync There are some points to note about disabling file syncing for folders and libraries. When you do this, you have the option to select `Disable File Syncing for all children` in the confirmation modal. #### Disable File Syncing for All Children Selecting this option will remove all the contained files from your disk *and* stop syncing changes made by others to the folder/library *but will leave* the empty parent folder on your disk. If you want to clean these empty folders up from your disk, you can delete them from your filesystem (Explorer on Windows/Finder on Mac) and then open the File Watcher (eye icon on bottom left of app). Finally, for the broken `replacement` folder shown below, select the `Disable Sync` option. Remove empty folders from file watcher #### Don't Disable File Syncing for All Children Leaving this option unchecked will stop syncing *new* changes made by others to the folder/library but leave the contents of the folder/library synced on your disk. ### Conflict Management The only time Mudstack will not automatically download a change from the cloud is if you have made local changes to a file/tag/library, and someone else also made changes and pushed them to the cloud. In this case, you will see the option to `Fix issue` to [resolve the conflict](/features/conflicts). # Pushing data Source: https://docs.mudstack.com/features/push Upload content to the cloud. Pushing data involves uploading your local changes to the cloud. To view your local changes, click the `Changes` button in the top nav or the `View my changes` button located at the top right corner. ## Pushing Content to a Workspace You **MUST** have have a local directory mapped to a cloud workspace to push local versions to the cloud. If your workspace is cloud only, [map the workspace](/features/sync-overview#mapping-a-workspace) first. Every modification you make to file metadata, libraries, tags, and workspace details will be included in the push table. This table displays only the pushes related to the currently selected workspace. ### Staging & Pushing Your Changes On the Changes view, you will see a list of all local changes made by you. From here, you can select related changes in order to push them as a group with a push message title and optional description. Choose the data you wish to push and stage it for a push by clicking the checkbox. Write a brief yet descriptive title to summarize the reason for your changes, with an optional more detailed description. Click the `Push Changes` button to send your changes to the cloud. When you click the `Push Changes` button, Mudstack will [fetch](/features/syncing-data/fetch) before the push to check for [conflicts](/features/syncing-data/conflicts). By default, **only the current version** of any file in the staged area gets pushed to the cloud. In most instances, this will also be your last save for the file unless you manually set [an older local version to be the current version](/features/version-control#set-current-version). ### Unstaging Changes At any point before clicking the `Push Changes` button, you can unstage changes to remove them from that push. To do this, simply uncheck the checkbox and that change will go back to the `Unstaged` area. ### Discarding Changes You can discard a change by selecting one or more changes (either in the staged or unstaged section), right-clicking and selecting `Discard Changes` from the menu. ### Uploading Non-current Versions If you want to upload any non-current local versions for any reason, Mudstack allows you to do this from outside of the regular push flow described on this page. See [upload non current versions](/features/version-control#upload-non-current-versions) for more Info. ## Automated Pushing Some data will be pushed automatically. This will happen immediately after a change in order to maintain continuity with the cloud workspace. Automated pushes include: 1. Account Data 2. Workspace Deletion 3. Workspace Creation -> Send to Cloud ## Cloud Import On occasions where you need to import large volumes of content to Mudstack on a one-off basis, we recommend using our Cloud Import feature. This allows you to upload folders to the root of your workspace without going through the staging process. This is much faster as it skips the local indexing and backing up process that is followed by the app when watching for changes and staging them for a push. To use this feature, go to `Settings/Account/Workspaces`, select your workspace from the dropdown and then use the Cloud Import section to upload your content. # Reviews & Feedback Source: https://docs.mudstack.com/features/reviews-feedback How to request and provide feedback in Mudstack. Speed of iteration is key to the progress of a team, and feedback is an integral part of iteration. Feedback, however, tends to get misplaced. It might live in easily lost Slack/Discord chats, be forgotten in Zoom calls that no-one took notes for, or get buried in issue tracking tools. One thing, however, is certain: without Mudstack, feedback is always detached from the file itself. ## Reviews A daily workflow for an art team is the act of leads and directors providing their feedback to their team of artists. **Mudstack streamlines this process**: 1. Artists can request a review and tag the relevant reviewer at any time through Mudstack. 2. This creates a to-do in the leads Mudstack dashboard. 3. The lead can either approve or request changes on the file. 4. Change requests will show up as a to-do on the assigned artist's dashboard. 5. The artist can make the changes and upload a new version, and return to step 1. ### Request a Review When a file has reached a stage where the artist is ready for a review, they can upload the file (or new version) to Mudstack and tag their lead(s) to provide their feedback and review. requesting a review in Mudstack 1. To do this, follow the steps to [push](/features/push) a file or version to the cloud. 2. Select the file and click on the `Reviews` tab. 3. Using the dropdown, select a reviewer. This list will show any team members that has the `Review` action selected on their team access rule. 4. This creates a `Review Request` to-do for the selected reviewer. 5. Once the reviewer has either `Approved` or `Requested Changes`, the artist will see a notification in their dashboard. 6. If the review result is a `Change Request`, that will show up as a to-do in the assigned artist's dashboard under the `Changes Requests` tab. ### Provide a Review providing a review in Mudstack 1. When an artist requests a review from an art lead, the reviewer will see a `Review Request` to-do in their dashboard. 2. To act on the review request, click the file and then the `Reviews` tab. Here, you can leave your approval or change request. When leaving a `Change Request`, you can assign it to a specific artist for action. 3. When you select `Request Changes`, this creates a `Change Request` to-do for the assigned artist on their dashboard. ## Feedback History When viewing a file in the Mudstack cloud, you can click on the `Timeline` section to see a complete history of that file, including all feedback. All comments, approvals, change requests and lifecycle changes (new versions, tags etc) for the file are displayed here. Learn how to set up real-time feedback notifications. # Searching Source: https://docs.mudstack.com/features/searching Find what you need, fast. Searching for files in Mudstack is the fastest way to find what you're looking for. Using the combination of search keywords and filters, you no longer need to know the exact file name or location in order to find what you're looking for. The desktop app searches against a local database of your last [fetched](/features/fetch) cloud data + your local data. If you want the most up to date cloud data to search against, click `Fetch` icon in the left side of the toolbar before searching. ## Using Mudstack Search Click in the search bar and type in the search phrase you want to use. searching for content in Mudstack Search runs against the entire workspace by default. If you are in a folder, you will see the option to change the search scope to the current folder you are viewing. ### Filters With thoughtful usage of [Tags](/features/tags) and [Libraries](/features/libraries), the built in filters can help you narrow down the file you're looking for. Do you want to filter against all files in the workspace? Type `.` into the search bar while at the workspace root, and use the filters to narrow down your results. Ever wish you could find that `Robot` `FBX` that `Josef` made last year for `The Grind` project? In Mudstack, you can do that. searching for content in Mudstack # Sharing Links Source: https://docs.mudstack.com/features/sharing-links Learn how to share files and folders with others, both inside and outside your Mudstack workspace. ## Sharing Files and Folders as Links in Mudstack Mudstack allows you to easily share files and folders, both with collaborators inside your organization and with people outside your account. Here’s how it works: ### Sharing Links with Other Mudstack Users If you want to share files, libraries, or history items with other users who already have access to your workspace: * **File Links:** You can find a file link by right-clicking on the file or from its sidebar details. Copy the URL and share it with another user in your workspace. * **Library Links:** Accessible from the Library details page; copy and share as needed. * **Push History/Commit URLs:** Right-click an item on the Push History page or open a Push History detail page to copy the URL. **How it works:** * When another user clicks the link, they’ll be routed directly to the specific item or location in the Mudstack app (if they have access). * Only users with the appropriate permissions in that workspace will be able to view the content. Users without access will receive an error or be denied. ### Sharing Files and Folders as Links Outside of Your Account If you want to send files or folders to people who are not members of your Mudstack account, you can generate a secure, time-limited shared link. You must be a workspace admin to share files or folders outside of your Mudstack account. #### Creating a Shared Link searching for content in Mudstack 1. **Select Files and Folders:** In Mudstack, select all the files and folders you wish to share. 2. **Right-Click → Share Files:** Right-click your selection and choose **Share Files**. searching for content in Mudstack 3. **Enter Emails:** In the modal dialog that appears, enter the email addresses of the people you want to send the shared link to. 4. **Set Expiration:** By default, the shared link expires after 7 days. You can adjust the expiration if needed. #### Using a Shared Link searching for content in Mudstack 1. The recipient will receive an email (or you can send them the generated URL directly). 2. Clicking the shared link takes them to an authentication page. 3. **Authentication:** They must enter an email address that matches the one specified for sharing. searching for content in Mudstack 4. **Download Content:** Once authenticated, recipients can selectively download files and folders. 5. If multiple files are selected, Mudstack will prepare and download them as a ZIP file. #### Managing Shared Links searching for content in Mudstack As an admin or user with permissions in Mudstack, you can manage all shared links for your workspace: 1. **Navigate to Workspace Settings:** Go to your `Workspace Settings`. 2. **Open the Shared Links Tab:** Here you can see all active shared links created by your team. searching for content in Mudstack 3. **Edit Shared Links:** Update the list of recipient emails, change the expiration date (extend or shorten), or disable a link as needed. 4. **Copy or Delete Links:** From the management table, you can copy the shared link URL or delete a shared link if you no longer want it to be accessible. You can also view the activity log for each shared link: see who attempted to access the link, when, and what files or folders were downloaded. This helps you track download history and monitor sharing security. For more information on managing permissions or troubleshooting issues with sharing, [contact our support team](/support/get-help). # Sync Overview Source: https://docs.mudstack.com/features/sync-overview Transferring content between the cloud and your computer. Map your Mudstack cloud workspace to a local directory, and stay in sync with cloud changes. Make changes locally, and effortlessly push them to the cloud when you're ready. Mudstack's sync feature is broken up into 2 parts: 1. [Pulling & Syncing](/features/pulling-and-syncing) data from the cloud to your local computer, and auto syncing files and folders, so that you're in sync with cloud data. 2. [Pushing](/features/push) changes from your computer up to the cloud, so cloud data can stay in sync with your changes. ## How Local and Cloud Workspaces Interact Diagram of cloud and local data passing For a given user, workspaces in Mudstack can be of the following types: 1. **Cloud only workspace**: this is a workspace that is ***not*** [mapped](/features/sync-overview#mapping-a-workspace) to a local directory for the user. Indicated by a "Map workspace" banner in the Files view. 2. **Mapped workspace**: this is a workspace that exists both locally and in the cloud, and can be kept in sync. Local and cloud workspaces interact by syncronizing files and data in both directions to ensure changes made on either platform are reflected across both, facilitating collaborative and accesible project management. All changes to files, tags, libraries, and workspaces are done locally first, then explicitly pushed to the cloud when using the desktop app. Cloud changes to content must be fetched and pulled to see those changes reflected in the desktop app. When a workspace is mapped, downloads and uploads between a cloud workspace and the defined local directory go to the relative path of the set workspace locations. The following data changes are immediate and **will not** show in the Sync Table: Comments, Tasks, Reviews, File Activity, User management and Attachments. ## Mapping a Workspace In order to synchronize data between a cloud workspace and your computer, you must first connect, or `map` the cloud workspace to a designated location on your computer. The workspace sidebar will also show a button alongside workspaces that haven't been mapped yet— whether they are local only or cloud only. ### Map an Existing Cloud Workspace send a local workspace to the cloud To map a cloud workspace, click the `Map workspace` button in the Files view on your desktop app. You will see a modal appear. Click `Select Workspace Location` to choose the parent folder of the location where you want to create the local directory for the workspace. ### Unmap a Workspace unmap a workspace in Mudstack Go to `Settings > App Settings > Cloud Workspaces`. From here you can click the Unsync icon for a synced workspace and confirm that you want to stop syncing. Any files that are already synced will remain but Mudstack will stop watching this directory for changes or creating new local versions for files in this directory. ## Data vs. File Syncing When Mudstack `pulls` changes, it is: 1. Pulling updates made by others to metadata for the selected workspace— its libraries, tags, and files (names, locations and any changes to the current version). 2. Downloading only the files (and folders) that you have enabled auto syncing on. See [pull](/features/pull-and-sync) for more information. # Tags Source: https://docs.mudstack.com/features/tags Tag all your files and thank yourself later. With only file names and folder hierarchies, finding files is very difficult unless you know the name and/or location of the file under question. Tagging your files is a powerful way of helping your future self and team! A central tagging system that works closely with your naming conventions makes [filtering](/features/searching#filters) down your search to quickly find what you need very easy. ## Managing Tags To manage your tags, go to the `Tags` view by clicking the link in the top bar. Only account admins and team members with the `Tag Management` action create tags for a workspace. Account admins and Workspace Admins can delete them. Here, you can create, edit and manage all your workspace tags. You can also click a tag to see a filtered view of all files using that tag. ## Syncing Tags While using the desktop app, any changes you make to a tag places it into the [push](/features/push) table to sync with your cloud workspace. If you assign a tag to a file, that file is also included in the push table for syncing. When Mudstack [fetches](/features/fetch) any new tag changes from the cloud, these tags will be available to you locally. ## Auto Tagging If your team has a well designed file naming convention, then you can use Mudstack's auto tagging to do some of the work. Create your tag system **before uploading content** to Mudstack. As long as a tag matches a string in the filename separated by a `.`, `-`, `_` or ` `, the file will automatically get tagged on upload. For example, if the tags `Red` and `Sword` already existed in the workspace, files named: * `Red_sword-3.png`, * `Red-Sword_final_final.fbx`, * `red sword wip.ma`, * `RED.SWORD.BIG.ztl` etc, would all get automatically tagged with both `Red` and `Sword` on upload. Tags that are a part of a word will also be added. For example, if you have the tag `Red` and a file `Reddish_sword_1.obj`, the tag `Red` will be applied to that file. ## Managing Tags on Files From any search view, you can select one or more files and add/remove tags to/from the selection: 1. Right click after selecting files and choose `Manage Tags`, or 2. Use the right sidebar to either remove tags from the selection or click the `Add tags` button to add new tags. You can also add tags to a file from the file details view by clicking on the file info tab on the right sidebar. Remember that removing a tag from a file does not impact the file itself other than the removal of the tag association from its metadata! ## AI Tagging This is an opt-in feature. If you want your team to use this, please contact [Mudstack support](mailto:support@mudstack.com?subject=Turn%20on%20AI%20Tagging%20for%20my%20Account) so we can turn this feature on for you. Generating a tag ### Generate Tag Suggestions * AI tagging only runs if there is a thumbnail on the file. It will also take in metadata related to the file to best suggest tags. * We use OpenAI to parse the image and generate the tags. * We weight the tags by existing tags in your workspace. * Once generated, you'll receive a list of suggestions you can apply to a file. Generating a tag * Currently, this is done 1 file at a time. If you would like to tag multiple files at once using AI tagging, you can use our [MCP](/features/mcp) with an agent or the [API](/api-reference/getting-started) to cycle through multiple files at once. # Version Control Source: https://docs.mudstack.com/features/version-control Version control, built for artists-first. Artists work differently from engineers. We recognized this fact from the beginning, so Mudstack's version control is designed to be file-based, not project based. Each file in Mudstack has its own version history. This allows artists to work on a subset of files in the project and not have to deal with project level conflicts due to work of other artists entering the system. Working locally, you are able to quickly start working off of any cloud version. Non-destructive versioning with easy rollbacks allows artists to confidently adopt a version control system that doesn't force them into a software development workflow with branching, checking out and locking files. ## Create New Versions New versions are created automatically on each save **as long as** the file is in a [local or mapped workspace](/features/sync-overview#mapping-a-workspace): Ensure that Mudstack is running so that changes to your local working directories are watched. Each save is considered a new `local version` by Mudstack. With our current process, Mudstack will work with overwriting saves. Incremental saves show as a new file. All overwritten versions are stored within Mudstack. Next, pick which of these local changes— file changes and modifications to tags and libraries— you want to push, provide an optional description to share what changed, and then [push them to the cloud](/features/push) workspace. ### Edit Versions click the edit name button that displays when hovering over the version name To edit a version's title, click the edit icon located next to the version's title and enter a new title. This title will be visible to other users. ## Send Your Changes to the Cloud To share your work with other team members in the cloud workspace, you must [push these changes](/features/push) to the cloud. ### Upload Non Current Versions There are occasions where you might want to upload a file version to the cloud but not want it to be the current version— whether it's to share work in progress or just make a cloud backup. You can do this at any point from the file details sidebar outside of the Changes view. Find the local version you want to upload and expand the card. Then, click the `Save version to cloud` icon— this will upload the version to the cloud history for that file and make it available to others without setting it as the current version. Upload a non-current version of a file in Mudstack ## Cloud File Versions Whenever a new version of a file is pushed to the cloud from the Changes view, it is treated by default as the `Current` version. This is the version that any user gets when they sync the file. ### Roll Back Version roll back to an older version in Mudstack To roll back to an older cloud version, hover over that version in the `Versions` tab. Click the `Set current version` button to set it as the `Current` version, then push your change. Cloud versions will always have a profile picture of the user that pushed up that version. Local versions will not as they are visible only to the logged in user on the desktop app. ## Downloading a version Downloading a version will sync the version to disk in your version store for access later. If you set the [current version](#set-working-version) to an older version, it will be downloaded if you have not already downloaded it. Pulling from the sync table will only pull the file's current version. If you want to pull older versions of a file, you must use that file's version tab and click the `Set current version` button. ## Set Current Version click the push button after committing local versions A working version refers to the version accessible in your local directory. You can replace the file in your local directory with a different version by switching which version is the current version. Other versions of your files are stored in the ".mudstack" folder within the same local directory. Click the `Set current version` button on the left side of the version card. ### Working From a Cloud Version Your local directory will always contain that current version of a synced file, allowing you to work off of it. In order to work from a different cloud version, you must set that cloud version as the current version. If you don't push this change, it will not impact other users, so you can safely use this option to swap versions locally. ### Recall Uncommitted Versions click the version button on the right side of a version to expand its uncommitted versions If you set a cloud version as a working version, all uncommitted local versions in front of that cloud version will be expanded as local versions, and all uncommitted versions from other versions are collapsed. From there you may set any of the uncommitted versions as your new working version. You can see the count of uncommitted versions related to a cloud version on the top right of the version card. ## Preview or Open a Version click the eye to preview in Mudstack and the open button in the bottom left to open with your OS default app Previewing a file version will display the file in app. Opening a file version will use your computer's default app to open the file outside of Mudstack. Either action will download and sync the file if you do not already have the file pulled locally. ## Deleting Versions click delete in the bottom left and confirm the delete to remove a version. In the event you need to delete a version of a file, here are the options you have available. ### Trashing a Local Version Trash a local version by clicking the bottom right delete button on an expanded version card. The version will move to the `Trashed Versions` area. ### Trashing a Cloud Version **Using the desktop app**: Same as local in action, but you need to perform a push after. The deletion action is initially carried out locally and only applied to the cloud after you push. **Using the web app**: Deleting a version from the web app is instant and appears as a pull record for other desktop app users. ### Permanently deleting a version Click the `Show Trashed` button in the top right of the versions tab. Either click the `Delete trashed versions` to delete all currently trashed versions for a file. ### Restoring trashed versions Click the `Show Trashed` button in the top right of the versions tab. Click the `Restore version` button next to the name of the version. ## Saving space with versions When you push files from your local computer to a workspace, you can delete versions inbetween the cloud version you worked from on during a push. To do this, check the `Flatten local version on push?` button, then check the `Permanently delete versions?` button if you want those trash buttons permanently deleted. see all old local version stored in Mudstack. This action does not affect branched versions, only local version parents of the current set version you are pushing to the workspace. ### Manage all local versions see all old local version stored in Mudstack. Go to the `Settings` → `Local Versions` area You can see the total storage usage and version counts across all files. Any local versions that you have set as current will not be visible in this area, so you can't delete current work, only past versions. To bulk delete old local versions across multiple files, you can click the checkbox next to any file you'd like to clean up, or select all in the checkbox above the file list. Click the `Cleanup local versions for selected files` to permanently delete those old local versions. # Accounts & Workspaces Source: https://docs.mudstack.com/getting-started/accounts-workspaces Understand how your Mudstack account is structured. ## Account Types When you log in to Mudstack, you have access to 1 or more accounts. An account can be either a single user account (Artist plan) or a multi-user account (all other plans). What you can see and do within an account depends on the [plan](/getting-started/plans-pricing) that account is subscribed to and what your specific [permissions](/getting-started/permissions) have been set to. ### Single User Accounts Every Mudstack user gets a free personal account on sign up. This account is subscribed to the free `Artist` plan. Artist plan accounts have a single user and do not allow collaborators. ### Multi User Accounts To create a new multi user account, please contact our sales team at [sales@mudstack.com](mailto:sales@mudstack.com). ## Workspaces Each account contains 1 or more workspaces. A workspace is a container that a specific file can belong to. An empty workspace is created by default for each new account. At this point, you cannot transfer files between workspaces from the Mudstack interface. Workspaces are ideal for managing distinct projects or giving access to a secure area for internal or external teams. How you choose to use workspaces is up to you— if you need any advice, be sure to [get in touch with our team](/support/get-help). Depending on the plan and your permissions on that account, a workspace may or may not be visible to you. ### Create a New Workspace From Scratch creating a workspace in Mudstack If you don't have an existing project or collection of files to import, you can create a new workspace by clicking the `New Workspace` button in the left sidebar. In the desktop app, you will need to map this workspace to a location on your machine. ### Convert an Existing Directory If you have an existing directory of content you would like to bring into Mudstack, you can convert it to a Mudstack workspace. Let's assume you have a `My New Project` directory located at `C:\My Files\My New Project`. To import this, follow these steps: Give this workspace the exact same name as the directory you want to import, e.g. `My New Project`. Next, set the location by **selecting the parent directory** of the directory you want to import. In this example, you should specify `My Files` as the location. Finally, allow Mudstack to finish indexing the contents of this directory. Depending on the size of the directory, this could take a few minutes. ## Workspace Visibility On the `Enterprise` plan, all workspaces are **private** by default. Users with the account role of `Member` must belong to a team with access to a workspace via a rule on the team. [Click here to learn more about the Teams update](\getting-started\permissions#managing-teams) There are no public Mudstack workspaces— you must log in and have access to the account *and* workspace in order to see it. # Desktop Application Source: https://docs.mudstack.com/getting-started/desktop-application Work with local files, and move to the cloud when you want to collaborate. Use the desktop application to make working with local files easier. Mudstack has a desktop application for [Windows](https://mudstack-desktop.s3.amazonaws.com/mudstack_windows_latest.exe) and [Mac](https://mudstack-desktop.s3.amazonaws.com/mudstack_mac_latest.dmg), as well as a browser application that works on all modern browsers. ## Benefits Artists build up massive collections of assets over time, and managing these files becomes a chore. Native OS folder structures don't allow for convenient tagging and organization— that's where the Mudstack desktop app can help. The desktop application can be used by anyone for free. You can manage your local files without sending anything to the cloud. Tag your local files, organize them in libraries and allow Mudstack to capture local versions as you work and save files. ## How It Works Start by pointing Mudstack to an existing directory on your computer, or create a new workspace and map it to a directory on your computer. This allows Mudstack to watch and manage the contents of this directory. Learn more about [creating workspaces](/getting-started/accounts-workspaces#workspaces). Your local file versions are stored in a cache inside your workspace folder. The Mudstack app can recall and swap these versions. These files must be committed and pushed to be visible by other team members that have access to the workspace. Mudstack will then index the contents of these directories, allowing you to tag files and add them to libraries. Any changes made to these directories locally— adding, renaming, moving and deleting files will be tracked up by Mudstack. As you work on files in mapped directories, **as long as Mudstack is running in the background**, each save is treated as a new version locally. To enable this, we recommend checking `Minimize on Close` and `Start Automatically` in the app `Startup Settings`. # Managing Files & Folders Source: https://docs.mudstack.com/getting-started/manage-files-folders Move, cut, and rename in the app ## Create a File Simply move your desired files into the [local directory](/features/sync-overview#how-local-and-cloud-interact) location. You may also create or save files in this folder to automatically add them to the directory. Created files *will not* go to the cloud automatically. A [version](/features/version-control) must be committed, then [pushed](/features/push) to upload to a cloud workspace. ### Locking Files For teams that have a content pipeline with sequential handoffs, this locking system will give you a status for when a file is being worked on by someone else. Lock files icon This "soft" lock only prevents pushes, not local version changes. So if you are blocked by a lock, you don't need to wait for the file to be unlocked to continue working. Select one or more files, right click and select `Lock files` to prevent other users from pushing changes to a file until you unlock it. Only the user that locked the file (and account admins) can unlock it. ## Create a Folder You have several methods to create a new folder: 1. From grid or list view: Click the `Create folder here` button in the toolbar 2. In your local directory: * For Windows: Use Explorer and choose `Create New Folder`. * For Mac: Use Finder and select `New Folder`. ## Moving Files and Folders To reorganize your files and folders: 1. To the Breadcrumb Bar: Click and hold the desired file or folder. Drag and release it onto the breadcrumb bar at the top. 2. Into a Folder in View: Click and hold the file or folder you wish to move. Drag and release it into the desired folder. Using drag and drop streamlines your file and folder organization. ### Cut and Paste `Cut`: Select file(s). Click the `Cut` button on the top right bar or right-click and choose `Cut`. `Paste`: Navigate to desired location. Right-click in or on the folder. Select `Paste`. Large `cut`/`paste` actions may take some time. ## Renaming To rename a file, select it, open its `Info` tab, and click the `Edit` button next to the file name. You can also rename a file from your Windows Explorer or Mac Finder and Mudstack will track this change as long as it is running. Make sure that the correct extension is placed on the end of the name. ## File Subscription To receive file [notifications](/features/notifications#real-time-notifications) on your dashboard, click the `Subscribe` button. Click it again to unsubscribe. Automatic subscriptions occur when you: 1. Comment, review, or take action on a file. 2. Upload a new version of a file. 3. Create a new file. ## Sync States different file sync states in Mudstack Every file has a sync state in Mudstack. The sync state will tell you where the file is stored, and if there is an issue that needs to be resolved. * **Local** - File only exists locally, and can be pushed to the cloud * **Cloud** - File only exists in the cloud workspace, and can be pulled (downloaded) from the cloud * **Synced** - File exists in the cloud workspace, is mapped to your local directory and in sync * **Local Changes** - A previously synced file that now has local changes, and can be pushed to the cloud workspace * **Conflict** - A previously synced file has local changes but is out of sync with the cloud because another user has pushed their changes to the cloud. Your changes aren't based off of the latest cloud version. This state updates after a [push](/features/push), [pull](/features/pulling-and-syncing), or [fetch](/features/fetch), while local changes reflect instantly. If you make any changes you would like to quickly send up to the cloud, you can [quick push data](/features/push). You can also sync files quickly to disk with [quick pull](/features/pulling-and-syncing). ## Delete Files and Folders Deleting of cloud content is a 2 step process in Mudstack, similar to that on your OS. The first step sends the selection to the Trash. To permanently delete files from the Trash, you can empty the Trash. ### Moving Files to Trash To send files/folders to the Trash: 1. Right-click and select `Send to Trash`, or 2. Use the `Trash` icon in the top actions bar when you have one or more items selected. Deleting a file or folders from the desktop app will show as local changes. You must push the changes in order for you to move these files and folders to the trash for everyone else. ### Emptying Trash Once files are in the Trash, if you want to permanently delete them, you can do so from within the Trash. To get to the Trash, click on the Filters icon in Search and select `Go To Trash`. Here you can either selectively empty the trash of files or restore them to their original locations, or permanently delete them by emptying the trash. Permanent delete actions will also need to be pushed to the cloud for the changes to affect everyone else. ### Deleting via Your OS If you delete files or folders from a local directory that's mapped to a cloud workspace using your Windows Explorer or Mac Finder, Mudstack will assume by default that this was an error, and show the file or folder as missing. If this was an error, you can right click and `Restore` the missing file/folder. This will place the file back in its original location but it will not appear on your disk unless you re-enable syncing for the file. If this was not an error, you can select `Remove`. Files removed this way will be sent to the trash. ## Multi Select To select multiple files, hold `Shift` or `Control` and click on each file that you want to select. # Permissions Source: https://docs.mudstack.com/getting-started/permissions Protect your IP: manage access to content in Mudstack. Looking for legacy permissions? [See our legacy documentation here.](/getting-started/permissions-legacy) Protecting your IP is a big concern for any game studio. Mudstack is designed from the ground up with this in mind. Besides our secure architecture, the ability to manage permissions for users in your account is the main way you can control access to your content. Mudstack account members have 3 roles: `Member`, `Admin`, and `Owner`. Depending on the plan the account is subscribed to, you can [manage workspace permissions with Teams](#managing-teams). ## Account Permissions account level permissions in Mudstack When a user joins an account, they can be granted a role at the account level and assigned to Teams for permissions to content within the account. All users with access to a workspace can download and comment on files they can see. ### Account Roles **Member**: this is the permission you should grant to **artists** on the team. This allows them to upload files and versions. They can select Team members with `Review` access to review their work when they are ready for feedback. **Admin**: this allows the user to administer the account— change the account or workspace name/icon, invite new users to the account, create workspaces and manage teams. **Owner**: By default, the account creator is the owner. After account creation, this permission can be shared with other users in the account. Only owners can change billing/plan details and delete the account. Owners will have full access to all content within their account. Only account `Admins` and `Owners` can see the `Account members` settings in order to invite users to the account and manage their permissions. ## Account Management Set the account role to Member, Admin, and Owner ## Migrating to Role Based Permissions ### What happens to my current workspace members and their roles? * Click the button `Enable team permissions` to migrate all workspace permissions to teams. * Migrated teams are named after the workspace and roles selected for each user in the workspace. After migration, you can edit the teams * Account roles will also be updated to match the original roles of Non-admins (marked `Member`), `Admin`, and `Owner` All new accounts start with Teams enabled. We will auto-migrate existing teams 2 months after on launch Dec. 15th ## Managing Teams account level permissions in Mudstack Teams allow your team to fine tune access to workspaces by grouping together similar members in a rules based permission system. You'll be able to manage a single team's access to multiple workspaces for fast user management ### Creating a Team Teams must have a name, a member selected, and one access level rule ### Adding a Rule to a Team * In the `Access level` column when editing or creating a team, click the `Add new rule` button. * Select what the rule has access to, then select the actions that can be used within this rule. #### Actions * `Download` allows users to view and download content. In legacy, this was the `Viewer` role. * `Upload` allows members to push changes to the defined locations in the rule. * `Tag Management` allows for members to create new tags. Users must be an admin to delete tags. * `Workspace Admin` allows members to manage designated workspaces. * `Review` allows members to post `Change Request` and `Approval` comments on a file, and displays members as reviewers in the `Request a reviewer` dropdown on files. If any rules are conflicting between teams, the members access is additive. Whatever rule gives the most access is what they can use. ### Setting Members on a Team * Search and select the members you want on this team. * When you are done, click the `Save` button in the top right to create the team. ### Editing a Team * Select the option button on the right of a team in the Teams list, then select `Duplicate`. Confirm the duplication. ### Duplicate a Team * Select the option button on the right of a team in the Teams list, then select `Duplicate`. Confirm the duplication. ### Removing a Team * Select the option button on the right of a team in the Teams list, then select `Delete`. Confirm the deletion. # Security Source: https://docs.mudstack.com/getting-started/security Protecting your intellectual property and reducing risk for your teams One of the most import concerns for any studio is protecting their intellectual property. It's critically important that data, teams, and devices are protected in this remote and distributed era of collaboration. Mudstack is dedicated to protecting the studios and teams that rely on our cloud and desktop solutions to streamline their collaboration and productivity. We do this through effective controls that ensure confidentiality of intellectual property, integrity of stored and shared files, and high availability of data through our managed cloud service. ## Ways Mudstack protects your intellectual property Mudstack relies on multiple mechanisms to reduce risk and protect your business. The primary mechanisms employed by Mudstack are our secure system architecture, access controls through roles and permissions at the account and workspace level, as well as adopting proactive business processes for our employees and partners. ### Our secure system architecture architecture overview Mudstack's customer facing interfaces, our Web Client, Desktop Application, and REST API, are backed by a secure architecture hosted by Amazon Web Services. Our secure backend works behind the scenes, enforcing secure access to, cloud synchrozination of, and high availability of files and metadata. Mudstack's secure architecture is made up of the following components: #### File Storage Server Using a combination of **AWS S3**, **AWS Cloudfront**, and **Signed URLs**, all files managed by Mudstack require authorized access to generate a **Signed URL**, are available on the network edge, and are only available to access for a short period of time after which the **Signed URL** will expire. #### Metadata Databases All account and workspace metadata stored by Mudstack is encrypted at rest and keyed by cryptographically **universally unique identifiers (UUIDs)**. This dramatically reduces the risk of unauthorized access to metadata, makes it **next to impossible** to guess ownership or providence of data in individual payloads, and drives the **multi-tenant implementation** of our platform. #### Authorization Server Mudstack relies on **Auth0 by Okta** to manage our authentication flow. When a user authenticates via SSO or email auth flows, Auth0 signs and distributes a **JSON Webtoken** to that user. This **JSON Webtoken** is used by our clients to manage our internal authorization. Using this workflow, our platform has to simply authenticate that the **JSON Webtoken** was signed with a valid private key (managed by Auth0). Authorization takes place within our API itself, but for authentication we rely on Auth0 for SSO and token via email to authenticate identity. #### Mudstack API Mudstack's REST API empowers all of our user facing interfaces. Every endpoint in our API requires a **JSON Webtoken**, which is first checked for authenticity. This cannot be avoided and is required for our cloud to access tenant metadata. The identity attached to the **JSON Webtoken** is correlated to a specific email, which is connected to any number of accounts and workspaces within our platform. Every account or workspace endpoint of our REST API requires the account and workspace to be specified as part of the request headers. Each request submitted this way triggers a cascading series of authorization checks, ensuring **Account Roles** and **Team Roles** allow for the request and also ensuring that the resources being requested or mutated belong to the specified account or workspace access via a Team. #### SSL/TLS All network communication to, from, and inside of Mudstack's secure environment are encrypted using **Secure Sockets Layer (SSL)/Transport Layer Security (TLS)**, establishing a secure connection between interfaces. Mudstack relies on **Amazon Web Services** to deploy our **SSL Certificates**. #### Virtual Private Cloud All of Mudstack's core infrastructue and environments are isolated within a virtual network hosted by **Amazon Web Services**. The majority of the infrastructue within our **Virtual Private Cloud (VPC)**, is hidden behind **Private Subnets**, unable to be connected to from outside of the VPC itself. ### Access controls through roles and permissions account level permissions in Mudstack Using a combination of account and team roles, Mudstack enables your organization to control access to your projects and intellectual property. Account administrators can easily manage who has overall access to the account, and what level of access they have through Artist, Review, Admin, and Owner roles. Account admins can create and manage workspaces, further segmenting users and their access to specific content. Team roles are allow users to interact with content via access rules on each team, and in many cases require the corresponding role on the account (i.e a member of a workspace can only have the Artist role if they are already an Artist on the account). The available roles, and their rights, are outlined in the above diagram. Only account `Admins` and `Owners` can see the `Account members` settings in order to invite users to the account and manage their permissions. ### Proactive business processes Mudstack leverages industry standard practices to ensure that our employees are held to the high ethical standards, have access to appropriate training, and are aware of the liabilities we carry as a platform provider. #### Employee policies All Mudstack employees are required to sign non-disclosure agreements and receive security training as part of their onboarding. Only individuals that have completed these procedures are granted logical access to the corporate environment as required by their job responsibilities. In addition, Mudstack provides ongoing security awareness training and resources to each employee. Employee access to Mudstack environments is maintained through a combination of our PEO and **Amazon Web Services Identity and Access Management (IAM)**. In addition, our internal policies require employees accessing production and corporate environments to adhere to best practices for the creation and storage of SSH private keys. Mudstack utilizes internal policies that prohibit employees from arbitrarily accessing user files and restricts access to metadata and other information about user accounts. Unless explicitly approved in writing by an administrator of an account, or backed by a signed non-disclosure agreement between Mudstack and the customer, Mudstack employees will not directly access or manipulate customer files. Employee access to any and all systems and information is promptly revoked when an employee leaves Mudstack, but any agreements, especially non-disclosure agreements signed by the employee, are still valid post employment. #### Internal access to production systems All access to production systems within Mudstack is managed with unique SSH key pairs. Mudstack has policies and procedures in place that ensure the proper protection and rotation of SSH keys. All SSH keys are revoked when employees leave Mudstack. #### File and metadata syncing Mudstack offers best-in-class file syncing, ensuring fast and responsive file transfers and anywhere access to data across devices. Mudstack selectively synchronizes content on devices based on applicable permissions. Mudstack's synchronization is also highly resilient, maintining local file management regardless of internet access and resuming cloud synchronization when access is restored. #### Remote wiping of files metadata When users leave a team or have their access revoked, Mudstack's desktop application will ensure that synchronized metadata is removed from any devices that were synchronized, on next initialization / synchronization of the desktop application. #### Audit of account and workspace activity Mudstack maintains an audit history of all activity taken within enterprise accounts and workspaces. Mudstack is able to provide these audits to account owners and administrators on request, and as part of the account administration interface. #### Passwordless security Mudstack is a passwordless system, relying on SSO and email authentication to manage access to accounts and workspaces. This means that Mudstack does not have any access to or responsibility over managing or maintaining user passwords. #### Privacy Mudstack's Privacy Policy is available [here](https://mudstack.com/static/Mudstack_Privacy_Policy-efc87914cdf0ad76542161f50954a4b8.pdf) Mudstack's Privacy Policy, Customer Terms of Service, User Terms of Service, and Acceptable Use Policy all provide notice of the following terms. * What kind of data we collect and why. * With whom we may share information. * How we protect this data and how long we retain it. * Where we keep and transmit your data. * What happens if the policy changes or if you have questions. #### Transparency around law enforcement Mudstack is committed to transparency in handling law enforcement requests for user information, as well as the number and types of those requests. Mudstack verifies all data requests to make sure they comply with the law and is committed to giving users notice, as permitted by law, when their accounts are identfified in a law enforcement request. #### Incident response Mudstack is diligent in our efforts to provide both a stable and secure platform experience. In support of this, Mudstack has policies and procedures in place to address any issues that arise regarding service availability, data integrity, and platform security. As part of these procedures Mudstack: * Responds promptly to potential incidents. * Actively triages severity of incidents. * Executes measures to both contain and resolve issues. * Preserves all evidence gathered in regards to any issues. * Communicates directly with impacted customers. # Working With a Team Source: https://docs.mudstack.com/getting-started/working-with-a-team Working with other people in Mudstack. All multi-user accounts (i.e. accounts subscribed to anything but the personal `Artist` plan) allow you to invite and work with others in the same account. ## Create a multi-user account To create a multi-user account, please contact our sales team at [sales@mudstack.com](mailto:sales@mudstack.com). ## Adding Users Users must belong to the account **and** team with access to a workspace in order to view workspace contents. ### Invite to an Account To invite users to the account, you must be an account admin. If you are an account admin, go to `Settings > Account Settings > Members`. Here you will be able to enter one or more email addresses for users you would like to invite to the account. ### Accepting Invitations When an invite is sent, pending invitations will show at the bottom of your account members list. These users should receive an email invitation asking them to join the account. On clicking the button in the email, they will be prompted to sign in to Mudstack and asked to join the account. We know of certain occasions where the button in the email does not function. Never fear! These invited users can *still* log in to Mudstack with the same email. Doing so will prompt them to join the account. ### Add to a Workspace Admins must add account members to team with access to a workspace in order for them to see the workspace. To do this, go to `Settings > Account Settings > Teams` and add user to an existing team with access, or create a new team with access to the workspace. ## Removing Users ### From a Workspace Admins can remove users from a workspace by removing them from all teams that have access to the workspace over their record under `Settings > Workspaces > Teams` and deselecting them in each team. ### From the Account To remove a user from the account entirely, go to `Settings > Account Settings > Members` and delete the user from the list. ## Working With External Artists Mudstack makes it easy to allow external artists to work out of the same location as your internal art team. On the [Enterprise plan](/getting-started/accounts-workspaces#enterprise-plan), you can control access to each workspace at the user level. This allows you to keep your external artists in their own workspace, so your team can see their work but they are unable to see work that they don't need access to. # Introduction Source: https://docs.mudstack.com/introduction Welcome to mudstack— the digital asset management platform for game studios and digital art teams. cloud storage, version control for artists and review & feedback, all in one tool Mudstack gives your team one place to store all their work. With built in [artist-first version control](/features/version-control) and [review & feedback](/features/reviews-feedback) tools, the whole team stays on the same page from anywhere, at anytime. Take your first step to becoming a mudstack power user. # Mudstack 101 Source: https://docs.mudstack.com/mudstack-101 Take your first steps to becoming a pro Mudstack user with these quick videos. # Your First Steps Watch this short overview video to understand the key features of Mudstack: