RunCloud API Beta

This API docs will evolve from time to time depending on feature that we are adding. The API Version you are currently viewing is Version 2. Please treat our API as beta stage and may evolve from time to time without further notice.

Get Started

To get started with API, you need a RunCloud account. If you don't have one, you can create a new account here.

Once you have created the account, you can use API Key and API Secret that you can get from the profile menu to use our API.

API endpoint

The base URL for our API is

https://manage.runcloud.io/api/v2/
All request to the API must be made over HTTPS.
All request and response will be in JSON formatted output.

Headers

You need to make sure all the request to our API have Content-Type: application/json and Accept: application/json headers.

Pagination

If the API Endpoint returning array of data, you may adjust the number of result by adding perPage to query string. You also can move to the next page by using page inside the query string. The maximum perPage query is 40.

curl --request GET \
  --url https://manage.runcloud.io/api/v2/ping \
  -u YOUR_API_KEY:YOUR_API_SECRET \
  --header 'accept: application/json' \
  --header 'content-type: application/json'

Authentication

We are using Basic Authentication for Authentication

For every request made to RunCloud API, you need to supply API Key and API Secret as Basic Authentication.

You can get API Key and API Secret inside Settings > API Key.

Once you have got your API Key and Secret, you can test the authentication by sending GET request to /ping endpoint

Request
curl -X GET "https://manage.runcloud.io/api/v2/ping" \
    -u YOUR_API_KEY:YOUR_API_SECRET \
    -H "Content-Type: application/json" \
    -H "Accept: application/json"

If your request is successful, you will get pong message as the output.

Response
{
	"message": "pong"
}
HTTP Response

We are using standard HTTP response codes that is familiar to API development.

HTTP CodeExplanation
200Ok (Usually you will get this code)
401Authentication failed. This is due to wrong API Key and/or API Secret
403Forbidden request
422Unprocessable Entity. You will expect this HTTP Code if you send incomplete data for POST / PATCH request
404Not found. The resources you are trying to reach is unavailable
429Too Many Request. You will get this HTTP Code if you have exceeded our rate limits
500, 502, 503, 504Server Errors. If you get this error, it is coming from our side. Just make sure you know how to handle it.

Each HTTP code output may carry some message. You may use the message to output to your application that you are building.

Rate Limit

We placed rate limit to every endpoint to allow fair usage for each users.

The rate limit is 360 requests/minute. All request to our endpoint will be count. 360 requests/minute limit will be lower down to a fair usage when we have announced paid API model.

Additonally, we send X-RateLimit-Limit and X-RateLimit-Remaining header for each requests.

Once you have exceeded the rate limit, you will receive 429 HTTP Status Code indicating Too Many Requests.