The REST API is currently in beta. This means we may change certain endpoints and API responses.
You can only access the REST API via https. In order to access the REST API you need to use an Access Token. You can generate an Access Token by going to your Organization's Account page.
In the API Tokens section click on Generate Token.
Give your token a name and click the button to create your new token. A new window will appear showing you your new access token.
Make sure you note that down because you will not be able to see the token once you close this window. This token is meant to be kept secret so do not share it with anyone other than your team (for example do not post this on forums).
From your Account page you can also Revoke all the tokens you have generated or a specific one. You can also edit the name of a token.
When you make calls to the API you must set the 'Authorization' header in your HTTP request to this value:
[access_token] with an Access Token you generated in your Account page.
curl -H "Authorization: Bearer nesgdxhiqe7hylfilr6ss1rds0gq1uj8" https://playcanvas.com/api/...
Various routes accept a number of parameters. For GET requests if the parameter is not part of the URL, you can pass it as an HTTP query string parameter. For POST, PUT and DELETE requests parameters not included in the URL should be encoded as JSON with a Content-Type of 'application/json'.
There are several common parameters that are used in each endpoint:
This can be found in the URL on the project overview page.
When opening a scene in the Editor, the scene id is in the URL.
This is found in the version control panel and can be selected and copied.
Our REST API is following some generic guidelines when it comes to the response format of each API call.
If you are trying to GET a single resource the response will be a JSON object with the resource you requested.
GET multiple resources
If you are trying to GET multiple resources like for example listing the Apps of a Project you will get a JSON object with this format:
As you can notice the response in this case also contains pagination data. To control the pagination of the response you can pass the following URL parameters:
|The maximum number of items to include in the response.
|The number of items to skip from the original result set.
|The name of the field to use to sort the result set. See the documentation of each request to see which values are allowed here.
|If you want results in ascending order pass 1 otherwise pass -1 for descending order.
So for example to get 32 items after the first 16 items you would send this request:
When an error is raised you will get a JSON object with this format:
"error": "This is the error message"
Also the status code of the response will be the appropriate HTTP error code.
Calls to the REST API have a rate limit. Check your actual limits by querying this endpoint. There are different rate limits depending on the request:
|Rate Limit Type
|Limit for free accounts
|Limit for personal/org accounts
|The normal rate limit
|The strict rate limit
|The assets rate limit
The response will contain the following headers to help you regulate how often you call the API:
|The number of requests allowed in a minute.
|The remaining number of requests that you are allowed to make this minute.
|The time at which the current rate limit window resets in UTC epoch seconds.
If you exceed the rate limit you will get a
429 Too Many Requests status code. You will have to wait for the current window to reset in order to continue making requests.