Global information

Introduction

The Scalingo V1 API is a publicly available interface allowing developers to control Scalingo’s entire cloud computing platform and access to the rich Scalingo dataset. The interface is stable and currently used by the Scalingo command line client (written in Go) and dashboard (a Vue.js app). However, changes are occasionally made to improve performance and enhance features. See the changelog for more details.

If you’re an addon provider, you’d better go to our addon provider API for you to interface your service with Scalingo’s platform.

The current API version is the v1. All the endpoints are prefixed by /v1. It’s only available through HTTPS: it’s TLS, or nothing.

The API has been tagged v1. However it is not a frozen API. We may and we will update endpoints and create new ones. But you can be sure we won’t break the existing. If any major change about the way JSON is structured, we will keep the right to release a v2 and so forth.

When any change is applied to the API, it will be displayed in the changelog section of this documentation and on our changelog website.

Base URL:

https://$SCALINGO_API_URL/v1/

Endpoints

Scalingo being available on multiple regions, the API endpoint depends on the region your application is hosted on. It’s designated by SCALINGO_API_URL in this documentation and must be replaced with one of the following value:

3DS Outscale Paris: api.osc-fr1.scalingo.com
3DS Outscale Paris SecNumCloud: api.osc-secnum-fr1.scalingo.com

HTTP Verbs

The API is not perfectly RESTful, it is more REST-ish. It has been developed to be easy to use and instinctive, we’ll probably normalize it, in a second version.

HEAD Can be issued against any resource to get just the HTTP header info.
GET Get resources, nullipotent operation (no matter how many times you call it, there is no side effect).
POST Used for creating resources. (creation of a new app, or to create an environment variable)
PATCH Update part of resources, as the value of an environment variable.
PUT Update complete resources.
DELETE Used for deleting items.

Parameters

GET and DELETE endpoints

Parameters for GET and DELETE requests are known as query parameters, they are declared in the resource URL.

POST/PUT/PATCH

For these types of request, parameters are not included as query parameters, they should be encoded as JSON with the following header: Content-Type: 'application/json'.

Example request:

curl -H 'Accept: application/json' -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/apps -d \
  '{
    "app": {
      "name": "example-app"
    }
  }'

Authentication

The authentication to the API is done thanks to an authentication token and Bearer HTTP Auth. The API is HTTPS only, so credentials are always sent encrypted.

Create an API token from your dashboard

You can create an API token from your Profile page on the dashboard:

Create your API Token

Create your API token with the authentication API

Otherwise you can create an API token with the authentication API directly:

POST https://auth.scalingo.com/v1/tokens

Parameters:

token.name: Name of this token

Example request:

curl -H "Accept: application/json" -H "Content-Type: application/json" \
 -u "<your username>:<your password>"
 -X POST https://auth.scalingo.com/v1/tokens -d \
 '{
   "token": {
     "name": "Test Token"
   }
 }'

Returns 201 Created

{
  "token": {
    "id": "e061a292-bab4-47fa-bb08-d7f7895ae5b6",
    "name": "Test Token",
    "created_at": "2018-03-28T19:56:09.433Z",
    "last_used_at": null,
    "issued_at": "2018-03-28T19:56:09.422Z",
    "token": "tk-us-BQ3LRmLGc35pMjdgwjX6kI1IWh7MAYk2uqquYwLDxCd4fhSm"
  }
}

Exchange this token for a Bearer Token

Scalingo’s API only accept Bearer Tokens so you’ll need to exchange your token for a Bearer Token.

Bearer tokens are only valid for an hour.

The token exchange is done by the authentication API:

POST https://auth.scalingo.com/v1/tokens/exchange

More informations available on the token page.

Example request:

curl -H "Accept: application/json" -H "Content-Type: application/json" \
 -u ":<your token>" \
 -X POST https://auth.scalingo.com/v1/tokens/exchange

Returns 200 OK

{
  "token": "the-bearer-token"
}

Make an authenticated request

HTTP requests have to be authenticated with HTTP basic authentication, with the authentication token as password, the username can be empty.

Data format

JSON

The API sends and receives JSON, XML is not accepted, please ensure JSON is used. All the returned object are object, there is never an array as root element.

Resources are rooted, it means that they have a parent key corresponding to its name. This key may be plural if a collection of items is returned.

Dates

All the dates are sent with the ISO 8601: YYYY-MM-DDThh:mm:ss.μμμZ

Example:

2015-01-13T09:20:31.123+01:00

This format is commonly understood, here are some examples:

JavaScript:

var date = new Date("2015-01-13T09:20:31.123+01:00")
Tue Jan 13 2015 09:20:31 GMT+0100 (CET)

Ruby:

require 'date'
DateTime.iso8601("2015-01-13T09:20:31.123+01:00")
=> #<DateTime: 2015-01-13T09:20:31+01:00 ((2457036j,30031s,123000000n),+3600s,2299161j)>

Go:

/*
 * go run iso8601.go
 * 2015-01-13 09:20:31.123 +0100 CET
 */
date, _ := time.Parse(time.RFC3339Nano, "2015-01-13T09:20:31.123+01:00")
fmt.Println(date)

Errors

Client errors - Status codes: 4xx

Invalid JSON - 400 Bad Request

The JSON you’ve sent in the payload is is wrongly formatted.

curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/users/sign_in -d '{"user": {'

Returns HTTP/1.1 400 Bad Request

{
  "error" : "There was a problem in the JSON you submitted: 795: unexpected token at '{\"user\": {'"
}

Exceeding free trial - 402 Payment Required

If you try to do an action unauthorized in the free trial, you will get an error 402 Payment Required.

curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/apps -d \
  '{
    "app" : {
      "name" : "my-new-app"
    }
  }'

Returns 402 Payment Required if user is not allowed to create a new app.

{
    "error": "Sorry, you need to verify your account (billing profile and payment card) to create a new app",
    "url": "https://my.scalingo.com/apps/billing"
}

Resource not found - 404 Not found

When you’re doing a request to an invalid resource

curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/apps/123

Returns HTTP/1.1 404 Not Found

{
  "resource": "app",
  "error" : "not found"
}

Invalid field - 422 Unprocessable Entity

There is an invalid field in the JSON payload.

curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/apps -d '{}'

Returns HTTP/1.1 422 Unprocessable Entity

{
  "errors" : {
    "app": [ "missing field" ]
  }
}

Invalid data - 422 Unprocessable Entity

Invalid data were sent in the payload.

curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/apps -d \
  '{
    "app" : {
      "name" : "AnotherApp"
    }
  }'

Returns HTTP/1.1 422 Unprocessable Entity

{
  "errors": {
    "name": [ "should contain only lowercap letters, digits and hyphens" ]
  }
}

Server errors - 50x

If the server returns a 50x status code, something wrong happened on our side. You can’t do anything about it, you can be sure that our team got notifications for it and that it will be fixed really quickly.

Pagination

Some resources provided by the platform API are paginated. To ensure you can correctly handle it, metadata are added to the JSON of the response.

Request parameters

page: Requested page number
per_page: Number of entries per page. Each resource has a maximum for this value to avoid oversized requests

Response meta values

The returned JSON object will include a meta key including pagination metadata:

{
  "meta": {
    "pagination": {
      "prev_page": "<previous page number>",
      "current_page": "<requested page number>",
      "next_page": "<next page number>",
      "total_pages": "<total amount of pages>",
      "total_count": "<total amount of items in the collection>"
    }
  }
}

prev_page and/or next_page are equal to null if there is no previous or next page.

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET 'https://$SCALINGO_API_URL/v1/apps/example-app/events?page=4&per_page=20'

Returns 200 OK

This request returns the events 40 to 60.

{
  "events": [
    { ... }
  ],
  "meta": {
    "pagination": {
      "current_page": 4,
      "prev_page": 3,
      "next_page": 5,
      "total_pages": 12,
      "total_count": 240
    }
  }
}