API v2 Introduction
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, create your workspace, and then you can use the API Token that you can get from the Workspace Settings page.API endpoint#
The base URL for our API is:https://manage.runcloud.io/api/v2/
Content-Type: application/json and Accept: application/json headers.Authentication#
We are using Bearer Token for AuthenticationFor every request made to RunCloud API, you need to supply API Token as Bearer Authentication.You can get API Token inside Workspace > Settings > API Keys.Once you have your API Token, you can test the authentication by sending GET request to /ping endpoint.curl -X GET "https://manage.runcloud.io/api/v2/ping" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
Legacy API v2 (Personal Space)#
If you still have access to our legacy API v2 inside your personal space,
we are using Basic Authentication for AuthenticationFor every request made to RunCloud API v2 from your personal space, you need to supply API Token as Basic Authentication.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"
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.If the API Endpoint returns 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.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.Modified at 2024-09-04 08:25:03
