The CloudMC API allows you to manage your environments and provision resources in a simple programmatic way using standard HTTP requests.

The API is RESTful. Responses, successful or not, are returned in JSON. Request bodies must be JSON, and should be made over SSL.

API endpoint : https://cloudmc_endpoint/api/v2

## To authenticate, add a header
## Make sure to replace `your_api_key` with your API key.
curl "https://cloudmc_endpoint/api/v2/organizations" \
   -H "MC-Api-Key: your_api_key"

API endpoints are secured by the same role-based access control (RBAC) as the CloudMC portal. To identify who is making the requests, it is required to add a header to your HTTP requests:

MC-Api-Key: your_api_key

The API key is found from the API keys section under the user profile menu. If you don't see CloudMC API keys section, contact your system administrator as you may not have the permission to see that section. Your API key carries the same privileges as your CloudMC account, so be sure to keep it secret. If you think your API has been compromised, regenerate your API key from the API keys section.

If you don't know what a sub-organization is, you can safely skip this section.

When using the API in an organization other than your own, make sure to specify the org_id query parameter in your request. This looks like:

https://cloudmc_endpoint/api/v2/users&org_id=:org_id

The CloudMC API can be used by any tool that is fluent in HTTP. The appropriate HTTP method should be used depending on the desired action.

# Example without tasks

{
  "data": [
    { "_comment" : "JSON representation of first object goes here" },
    { "_comment" : "JSON representation of second object goes here" }
  ]
}

# Example of compute API call with task

{
  "taskId": "c2c13744-8610-4012-800a-0907bea110a5",
  "taskStatus": "PENDING"
}

When an API request is successful, the response body will contain the data field with the result of the API call. If you're using the compute API, the data field might be empty since most of the operations are asynchronous. The response will contain the taskId and taskStatus fields so that you can retrieve the result of the operation you executed through the task API.

# Example of error response

{
  "errors": [
    {
      "code": 2012,
      "message": "Cannot stop an instance that isn't in the running state",
      "context": {
        "id": "4534cc36-bc46-48bc-ac5c-3ee4e42f0a44",
        "currentState": "Stopped",
        "expectedStates": [
          "Running"
        ],
        "type": "instances"
      }
    }
  ]
}

When an API request is unsuccessful, the response body will contain the errors field :

Each error has additional fields to describe it :

The HTTP status codes of error responses :

# Example of an asynchronus operation response

{
  "taskId": "b2f82e2a-123e-4f86-a4c7-dc9b850dd11e",
  "taskStatus": "PENDING"
}

Some operations take longer to execute, and to avoid blocking on the response until it is fully completed, these are treated in an asynchronous fashion. This means the API will return immediately, and provide you a taskId that is your reference to the ongoing background task. Using the tasks API, you can query the task's status to find if it has completed and obtain the result of the operation.

# Example of success response

{
  "taskId": "b2f82e2a-123e-4f86-a4c7-dc9b850dd11e",
  "taskStatus": "SUCCESS",
  "result": {
    "id": "8f064230-82a6-4f93-a17d-9cf9623b0cb5",
    "name": "morty"
  }
}

GET https://cloudmc_endpoint/api/v2/tasks/:id

A task has three different status: PENDING, FAILED and SUCCESS. On a successful completion of the task (i.e. it's in the SUCCESS state), the response will contain a result field which will contain the result of the operation. It is important to note that we don't persist our task, a task will only stay alive for 30 minutes (in general).