API v3 Introduction

Get Started

To get started with the RunCloud API, you need a RunCloud account.

If you don’t have one, you can create a new account here.

Once you have created your account, create your workspace, and then you can use the API Token that you can get from your Workspace settings page.

API Endpoint

The base URL for our API is:

https://manage.runcloud.io/api/v3

All requests to the API must be made over HTTPS.

All requests and responses will be in formatted in JSON.

Headers

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

Authentication

We use Bearer Tokens for Authentication

For every request made to the RunCloud API, you need to supply API Token as Bearer Authentication.

You can get your API Token inside Workspace > Settings > API Management.

Once you have your API Token, you can test the authentication by sending a GET request to the /ping endpoint.

Request

curl -X GET "https://manage.runcloud.io/api/v3/ping" \
    -H "Authorization: Bearer YOUR_API_TOKEN" \
    -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 Code	Explanation
200	Ok (Usually you will get this code)
401	Authentication failed. This is due to wrong API Key and/or API Secret
403	Forbidden request
422	Unprocessable Entity. You will expect this HTTP Code if you send incomplete data for POST / PATCH request
404	Not found. The resources you are trying to reach is unavailable
429	Too Many Request. You will get this HTTP Code if you have exceeded our rate limits
50x	Server 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.

Pagination

If the API Endpoint returns an array of data, you may adjust the number of results by adding the perPage parameter to the query string.

You also can move to the next page by using the page parameter inside the query string. The maximum perPage query is 40.

Rate Limit

A rate limit is set for every endpoint to allow fair usage for each users.

You can get the information about your current rate limit in Workspace > Settings > API Keys.

Additionally, 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.