Mudstack API: Getting Started

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.
• Workspaces: Workspaces are collaborative environments where you can organize and manage your assets. Learn more in the Workspaces Documentation.
• Assets: Assets are the core entities you manage in Mudstack. Learn more about asset management in the Assets Documentation.

​

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.

​

Base URL

The base URL for all API requests is:

https://api.mudstack.com/v1

​

Making Your First API Call

Here’s an example of how to make your first API call to retrieve a list of workspaces:

​

Request

curl -X GET "https://api.mudstack.com/v1/workspaces" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "x-account-id: YOUR_ACCOUNT_ID"

​

Response

{
  "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

{
  "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

{
  "error": {
    "code": "invalid_request",
    "message": "The provided account ID is invalid."
  }
}

​

Next Steps

• Learn how to authenticate: Authentication Documentation
• Manage your accounts: Accounts Documentation
• Explore workspaces: Workspaces Documentation
• Manage assets: Assets Documentation