Authentification
Requests to the API are authenticated with a bearer token using the HTTP header Authorization: Bearer <token>. Tokens can be created by clicking on your username on the bottom left of the Scalr UI and selecting "Personal Access Tokens". Service account tokens can also be created for production usage.
If the token is not supplied or it is invalid, Scalr returns the status response HTTP 401 Unauthorized and a JSON API error object. Status response 401 is only used when there are problems with the authentication token. If the token is valid but the requester does not have the required permissions for the endpoint/method then Scalr will return the status response HTTP 404 Not found.
API Versioning and Path
The Scalr API has the current major version “v3” with a path prefix of /api/iacp/v3
If there is a future change to API semantics the version will increment to “v4”.
API Feature Deprecation
Any deprecation will be communicated through the API specification, documentation, and HTTP API responses. Features planned for deprecation will remain in the API for 3 months after the announcement of the planned deprecation. After 3 months the feature will be completely removed.
API Format
The Scalr API is a REST API. It follows JSON:API v1.0 semantics for requests and responses.
JSON API Responses and Inputs
Responses from the API will be JSON Documents.
For POST and PATCH methods a JSON API document is required as the request payload. This is an example of payload to create a workspace.
{
"data": {
"attributes": {
"auto-apply": true,
"name": "workspace-name",
"operations": true,
"tags": [
{
"name": "tag-name",
"value": "tag-value"
}
],
"terraform-version": "0.12.28",
"vcs-repo": {
"branch": "master",
"identifier": "vcs-xxxxxxxxx"
},
"working-directory": "sub-dir"
},
"type": "workspaces"
}
The JSON must be structured as follows
- Top-level
dataproperty. data.typeproperty as defined in the API method specification.- Typically will include
data.attributescontaining the attributes of the object with possibly other nested objects.
The documentation will reference nested attributes using the format shown in this example.
{
"data": {
"attributes": {
"auto-apply": true
}
}
}
referenced as data.attributes.auto-apply.
Method Parameters
For some POST, PATCH and DELETE methods it is necessary to specify the relevant object ID as part of the endpoint path. This may be the only parameter or may also require a JSON object to be passed as well. The object ID place holder will be shown using {...} notation as shown in this example.
POST /api/iacp/v3/workspaces/{workspace}/actions/unlock
For GET methods it may be necessary to pass in query parameters such as filters, using the ?filter[attribute]=value format. Depending on the tooling, it may also be necessary to encode the [] using %5B and %5D. The documentation assumes the encoding is required and describes the method as shown in this example.
GET /api/iacp/v3/runs?filter%5Bworkspace%5D=string HTTP/1.1
The “parameters” section for each method describes the query parameters for the method and specifies which ones are required and which are optional. See below for details on using the pagination parameters.
Pagination Parameters
Pagination is supported for any method that returns an array of objects. The default is to return the first 20 objects but this can be altered by specifying a page number and size as parameters to the query in the following format.
...?page[number]=3&page[size]=25
This example would return objects from number 51 to 75 (if these exist).
The links and meta attributes will contain pagination data to make it easy to re-query the API for additional objects.
{
"links": {
"first": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"last": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20",
"next": null,
"prev": null,
"self": "https://my-account.scalr.io/api/iacp/v3/runs?filter%5Bworkspace%5D=ws-t4qmoc3kbumpoug?page%5Bnumber%5D=1&page%5Bsize%5D=20"
},
"meta": {
"pagination": {
"current-page": 1,
"next-page": null,
"prev-page": null,
"total-count": 2,
"total-pages": 1
}
}
}
Example Usage
Below is the syntax required to make an API call in shell script using curl
curl -s -X ${HTTP_OP} ${API_URL}${THE_PATH} \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/vnd.api+json" \
--data "@data.json"
This is an example of what a complete call to create a workspace might look like.
curl -s -X POST HTTPS://my-account.scalr.io/api/iacp/v3/workspaces \
-H "Authorization: Bearer xxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/vnd.api+json" \
--data "@create-workspace.json"
This is an example of the data required for a workspace bound to a VCS.
{
"data": {
"attributes": {
"auto-apply": true,
"name": "example",
"queue-all-runs": true,
"terraform-version": "0.13.5",
"vcs-repo": {
"branch": "master",
"identifier": "scalr-eap/vcs-example",
}
},
"relationships": {
"environment": {
"data": {
"id": "env-t2fcrq6h1v3nf0g",
"type": "environments"
}
},
"vcs-provider": {
"data": {
"id": "vcs-82d594bacd10",
"type": "vcs-providers"
}
}
},
"type": "workspaces"
}
}
OpenAPI Spec
The OpenAPI specification for Scalr can be found here: https://scalr.io/api/iacp/v3/openapi-public.yml
Rate Limit
The Scalr API is rate limited to prevent slow response times or downtime due to excessive usage. The limit is 500 requests per minute.
The expected error when hitting the rate limit is 429 - Rate Limit Exceeded.
If this is impacting your work in Scalr, please contact support to review the possibility of increasing the limit for your account.