Welcome to the CMP Scalr APIv2 documentation

NOTE

To access the API docs for the Scalr Terraform product, please visit https://docs.scalr.io/reference .

The Scalr API allows you to write scripts or applications to automate tasks on your Scalr-managed infrastructure. It allows you to edit roles, farms, images, launch farms and more. Three APIs are defined, to performs actions at the global scope, the account scope or the user scope. The list of all the defined endpoints and the possible responses from the server are available in the left menu, in the User API, Account API and Global API sections. The global API can be used to manage Images and Roles for the whole Scalr installation, the account API can be used to manage environments, orchestration rules, roles or images for an account; while the user API is rather used to manage farms, farm roles, projects or scaling metrics as an user in the account. To learn more about the difference between the global, account and user scopes, visit the corresponding documentation page.

Getting started

Before using the API, if you are using the enterprise or community editions of Scalr, you must enable the API and generate API keys. If you are using the hosted version of Scalr, you only need to generate API keys.

Enabling the API

To enable the API, add the following to your /etc/scalr-server/scalr-server.rb configuration file:

app[:configuration] = {
  :scalr => {
    :system => {
      :api => {
        :enabled => true,
        :allowed_origins => '*'
      },
    },
  },
}

Note that if you already have a app[:configuration] object defined, you should instead merge this in.

The allowed_origins parameter allows you to control which domains can host browser-based api clients that will be allowed access to your API, by using the Access-Control-Allow-Origin HTTP header. Setting this to '*' allows any domain to access your API. For security reasons, you might want to limit this by setting allowed_origins to ~, which will prevent browser-based clients to access your API, or by setting it to a list of domains, following the format of the Access-Control-Allow-Origin HTTP header. Read more here. If you want to use the test client built into the documentation pages, this parameter must include https://api-explorer.scalr.com

Run scalr-server-ctl reconfigure to apply the changes.

Generating API keys

Login to Scalr as the user you'd like to access the API as, and access the following URL: https://your-scalr-host/#/core/api2

Then, generate a new key. Do not forget to save the private key somewhere, as you will not be able to access it again. If you lose the private key, you will have to generate a new API key.

This key will have the same access rights as the user you're logged in as, so if you are logged in as a regular user, this key will have access only to the User API, if you are logged in as the account owner, this key will have access to the User and Account API, and if you are logged in as a global administrator, this key will have access to all APIs.

Using this documentation

The menu on the left allows you to browse the API endpoints. You can try the endpoints directly from your browser, so you can test them with your own data. To do so, click on the AUTHORIZE AND EXECUTE button at the bottom of each endpoint description, and fill in your API credentials when asked. You have the possibility to save your credentials in your browser to avoid having to type them again everytime you want to test an endpoint.

Be careful, as this is equivalent to giving someone that has access to your computer full access to Scalr. You should also be mindful when trying the API endpoints, especially with the PATCH and DELETE requests, as there are no safeguards: these API calls will alter or remove your data. We recommend that you start by copying the items you want to work on, and test the API only on the copies.

Writing a client for the Scalr API

To automate calls to the Scalr API, you need to write a client. You can do so in the programming language of your choice. Your client will have to generate HTTP requests that comply with the documentation, and authenticate them with your API credentials. The authentication mechanism is described here.

A few examples showing how to use the APIv2 with different programming languages are available on Github. These examples should help getting started with the API, but they are not fully fledged SDKs and they should only be considered as an extension to the documentation.

Error messages

{
   "errors":[{
      "code" : string,
      "message" : string
   }]
}

When something went wrong with your request, the Response data will contain “errors” list. Where “code” will contain machine code (like ObjectNotFound, ConfigurationMismatch etc.) and “message” will contain human-readable message that explains what exactly went wrong. The vast majority of these messages are build with defined patterns. The goals of these patterns are:

The main patterns to consider:

When we talk about particular property of an object we point-out the name of this object and property name, wrap it in single quotes and then go value(s) for this property in brackets. Example: "'FarmRole.cloudLocation' with value (abcd) is not allowed ...." The object name corresponds to the API Documentation (First letter capital, camelCases). When we have to expose two or more properties with values in one message follow the rule: After the 'property name' goes its (value), then goes next 'property name' and it's (value). If we've got the Object and we have to describe couple properties, we won’t repeat the object name in the message. Example: "'FarmRole.alias' (test-role) with 'cloudLocation' (east-us1) was not found". Here ‘alias’ and ‘cloudLocation’ are FarmRole’s properties. Properties with hierarchy (nested object properties) separated by dots. Example: "'FarmRole.networking.network' "

Note: There are conditions in Scalr API when we can’t build error message with defined pattern (for instance: original responses from cloud-services, etc.)

Swagger definitions

The swagger definitions for the Scalr user, account and global APIs are available respectively at:

These API specifications can be used to auto-generate client code in many languages, but you will likely have to rewrite the authentication part.