Fork me on GitHub
API V1 RESOURCES LINKS

Applications

Application attributes

field type description
id string unique ID
name string name of the application, can substitute the ID
created_at date creation date of the application
updated_at date last time the application has been updated
git_url string URL to the GIT remote to access your application
owner object information about the owner of the application
url string URL used to access your app
base_url string URL generated by Scalingo for your app
links object object of related link like deployments_stream
force_https boolean activation of force HTTPS
flags object list of flags associated to the app
limits object list of limits associated to the app
sticky_session boolean activation of sticky session
router_logs boolean activation of the router logs in your app logs
last_deployed_at date date of the last deployment attempt
last_deployed_by string user who attempted the last deployment
last_deployment_id string id of the last successful deployment
stack_id string id of the stack used
data_access_consent object object representing data access consent
hds_resource bool app being hds compliant

Example object:

{
  "id": "54100930736f7563d5030000",
  "name": "example-app",
  "created_at": "2014-09-10T10:17:52.690+02:00",
  "updated_at": "2014-09-10T10:17:52.690+02:00",
  "git_url": "git@scalingo.com:example-app.git",
  "last_deployed_at": "2017-02-02T10:17:53.690+02:00",
  "last_deployed_by": "john",
  "last_deployment_id": "58c2b15af1453a0001e24d23",
  "force_https": true,
  "sticky_session": false,
  "router_logs": true,
  "hds_resource": false,
  "owner": {
    "username": "john",
    "email": "user@example.com",
    "id": "54100245736f7563d5000000"
  },
  "flags": {
    "sticky-session": true
  },
  "limits": {
    "git-repository-size": 1000000000
  },
  "url": "https://example-app.scalingo.io",
  "links": {
    "deployments_stream": "wss://deployments.scalingo.com/apps/example-app"
  },
  "data_access_consent": {
    "app_id": "ap-82a3cac5-9b25-473e-b33d-6272b87e636f",
    "containers_until": null,
    "database_until": null,
    "user_id": "us-8ba226e5-93e0-4545-8363-9c16b2d68d67"
  }
}

Create an Application

POST https://$SCALINGO_API_URL/v1/apps

Parameters

  • app.name: Should have between 6 and 48 lower case alphanumerical characters and hyphens, it can’t have an hyphen at the beginning or at the end, nor two hyphens in a row.
  • app.git_source: (Optional) URL to the future GitHub repository if your need to deploy from there without going through the git push workflow
  • app.stack_id: (Optional) ID of the stack that will be used for your app

Custom Header

  • X-Dry-Run: <boolean>: If set to true, the operation only checks if the application can be created with the given parameters. The same errors and responses are sent, but the application is not actually created.

Free Usage Limit

You can only have 1 application without having defined a payment method.

Example

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"
    }
  }'

Returns 201 Created

{
    "app": {
        "created_at": "2014-09-10T10:17:52.690+02:00",
        "git_url": "git@scalingo.com:example-app.git",
        "id": "54100930736f7563d5030000",
        "name": "example-app",
        "last_deployed_at": "2017-02-02T10:17:53.690+02:00",
        "last_deployed_by": "john",
        "last_deployment_id": "58c2b15af1453a0001e24d23",
         "owner": {
            "username": "john",
            "email": "user@example.com",
            "id": "54100245736f7563d5000000"
        },
        "updated_at": "2014-09-10T10:17:52.690+02:00",
        "url": "https://example-app.scalingo.io",
        "links": {
          "deployments_stream": "wss://deployments.scalingo.com/apps/example-app"
        }
    }
}

List Your Applications

GET https://$SCALINGO_API_URL/v1/apps

List all your applications and the one your are collaborator for.

Example

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

Returns 200 OK

{
  "apps": [
    {
      "name": "example-app",
      …
    }, {
      "name": "another-app",
      …
    }, …
  ]
}

Get a Precise Application

GET https://$SCALINGO_API_URL/v1/apps/[:app]

Display a precise application

The status field can take different values depending on your application state:

  • new: Your app has just been created
  • running: Your app has at least one container running
  • stopped: Your app has no containers running
  • crashed: Your app has crashed more than 12 times in a row
  • restarting: You triggered a restart operation
  • scaling: You triggered a scale operation
  • booting: You are deploying a new version of your application

The limits field is only present when a manual limit was specified by a Scalingo operator.

The default limits of an app are consequently not present.

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

Returns 200 OK

{
  "app": {
    "id" : "51e938266edff4fac9100005",
    "name" : "example-app",
    "owner" : {
       "email" : "user@example.com",
       "id" : "51d73c1e6edfeab537000001",
       "username" : "example-user"
    },
    "git_url" : "git@scalingo.com:example-app.git",
    "last_deployed_at" : "2014-11-16T12:17:16.137+01:00",
    "status" : "running",
    "updated_at" : "2015-02-02T18:00:18.041+01:00",
    "created_at" : "2013-07-19T14:59:18.329+02:00",
    "last_deployed_by" : "example-user",
    "url": "https://example-app.scalingo.io",
    "links": {
      "deployments_stream": "wss://deployments.scalingo.com/apps/example-app"
    },
    "force_https": true,
    "sticky_session": false,
    "router_logs": true,
    "limits": {
      "git-repository-size": 1000000000
    }
  }
}

Get Containers List

GET https://$SCALINGO_API_URL/v1/apps/[:app]/ps

Lists the different containers of a given application.

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/ps'

Returns 200 OK

{
  "containers": [
    {
      "id": "6054bcc56d80de00682f7a18",
      "type": "web",
      "type_index": 1,
      "created_at": "2021-03-19T15:01:25.088Z",
      "deleted_at": null,
      "state": "running",
      "size": "",
      "command": "",
      "container_size": {
        "id": "b46b1a69-085f-4b9a-ba01-241bd6f658fb",
        "human_cpu": "standard CPU priority",
        "name": "M",
        "human_name": "M",
        "memory": 536870912,
        "ordinal": 3,
        "hourly_price": 20,
        "thirtydays_price": 1440,
        "pids_limit": 0,
        "swap": 0,
        "sku": "osc-fr1-app-M"
      }
    },
    {
      "id": "6059fd0e6d80de005d85ca1a",
      "type": "one-off",
      "type_index": 9410,
      "created_at": "2021-03-23T14:37:02.102Z",
      "deleted_at": null,
      "state": "booting",
      "size": "",
      "command": "bash",
      "container_size": {
        "id": "b46b1a69-085f-4b9a-ba01-241bd6f658fb",
        "human_cpu": "standard CPU priority",
        "name": "M",
        "human_name": "M",
        "memory": 536870912,
        "ordinal": 3,
        "hourly_price": 20,
        "thirtydays_price": 1440,
        "pids_limit": 0,
        "swap": 0,
        "sku": "osc-fr1-app-M"
      }
    }
  ]
}

Get Container Types List

GET https://$SCALINGO_API_URL/v1/apps/[:app]/containers

This request lists the different container types of a given application. It includes how many containers and the size of the containers for each type.

Container type attributes

field type description
name string Type of container (web, worker, etc.)
amount integer Amount of containers of the given type
size string Size of the containers of this type (S/M/XL/..)

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/containers'

Returns 200 OK

{
  "containers": [
    {
      "name": "web",
      "amount": 2,
      "size": "L"
    }, {
      "name": "worker",
      "amount": 1,
      "size": "M"
    }
  ]
}

Scale an Application

POST https://$SCALINGO_API_URL/v1/apps/[:app]/scale

Send a scaling request, the status of the application will be changed to ‘scaling’ for the scaling duration. No other operation is doable until the app status has switched to “running” again.

You can follow the operation progress by following the Location header, pointing to an operation resource.

The request returns the complete formation of containers event those which are not currently scaled.

Parameters

  • containers: Array of the containers you want to scale. Each containers:
    • container.name: Name of the container you want to scale
    • container.amount: Final amount of container of this type
    • container.size (optional): Target size of container (not changed if empty). Container sizes list.

Free Usage Limit

You can only have 1 small or medium ‘web’ container without having defined a payment method.

Limit

There is a hard limit of 10 containers of a given type per application, if you need more: contact us

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/example-app/scale' -d \
  '{
    "containers": [
      {
        "name": "web",
        "amount": 2,
        "size": "L"
      }
    ]
  }'

Returns 202 Accepted (Asynchronous task) Headers:

  • Location: ‘https://$SCALINGO_API_URL/v1/apps/example-app/operations/52fd2357356330032b080000’
{
  "containers": [
    {
      "id": "52fd2457356330032b020000",
      "name": "web",
      "amount": 2,
      "size": "L"
    }, {
      "id": "52fd235735633003210a0001",
      "name": "worker",
      "amount": 1,
      "size": "M"
    }
  ]
}

Restart an Application

POST https://$SCALINGO_API_URL/v1/apps/[:app]/restart

In the same spirit than the ‘scale’ operation, the restart is an asynchronous operation

Send a restart request, the status of the application will be changed to ‘restarting’ for the operation duration. No other operation is doable until the app status has switched to “running” again.

You can follow the operation progress by following the Location header, pointing to an operation resource.

Parameters

  • scope: Array of containers you want to restart.
    • If empty or null: restart everything
    • Should fit the container types of the application: ["web", "worker"] or ["web-1"]

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/example-app/restart' -d \
  '{
    "scope": ["web"]
   }'

Return 202 Accepted (Asynchronous task) - Empty body

Delete an Application

DELETE https://$SCALINGO_API_URL/v1/apps/[:app]

Parameters:

  • current_name: As validation, should equal the name of the app

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X DELETE 'https://$SCALINGO_API_URL/v1/apps/example-app?current_name=example-app'

Returns 204 No Content

Rename an Application

POST https://$SCALINGO_API_URL/v1/apps/[:app]/rename

Parameters

  • current_name: As validation, should equal the name of the app
  • new_name: Target name of rename operation

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/example-app' -d \
  '{
    "current_name": "example-app",
    "new_name": "renamed-example-app"
  }'

Returns 200 OK

{
  "app": {
    "name": "renamed_example-app",
    ...
  }
}

Transfer Ownership of an Application

PATCH https://$SCALINGO_API_URL/v1/apps/[:app]

Parameters

  • current_name: as validation, should equal the name of the app
  • app.owner: email of the new owner of the app, should be part of the collaborators

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X PATCH 'https://$SCALINGO_API_URL/v1/apps/example-app?current_name=example-app' -d \
  '{
    "app": {
      "owner": "user2@example.com"
    }
  }'

Returns 200 OK

{
  "app": {
    "name": "example-app",
    ...
  }
}

Update Application Settings

PATCH https://$SCALINGO_API_URL/v1/apps/[:app]

Parameters

  • app.force_https: boolean to enable or disable force HTTPS on the application
  • app.sticky_session: boolean to enable or disable sticky session on the application
  • app.router_logs: boolean to enable or disable the router logs on the application
  • app.stack_id: string that changes your application stack

Example request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X PATCH 'https://$SCALINGO_API_URL/v1/apps/example-app' -d \
  '{
    "app": {
      "force_https": true,
      "router_logs": false
    }
  }'

Returns 200 OK

{
  "app": {
    "name": "example-app",
    ...
  }
}

Access to the Application Logs

GET https://$SCALINGO_API_URL/v1/apps/[:app]/logs

The request generates an URL you can use to access the logs of your application.

How to use this endpoint: more information here

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/logs'

Returns 200 OK

{
  "app": { … },
  "logs_url": "https://logs.scalingo.com/apps/example-app/logs?token=0123456789"
}

Access to the Application Logs Archives

GET https://$SCALINGO_API_URL/v1/apps/[:app]/logs_archives(?cursor=123456)

The request generates a list of URLs you can use to download your logs archives. URLs are valid for a duration of 60 minutes.

They are paginated so a response contain a boolean indicating if there is more archives available and a string cursor you need to provide to get next list.

One response item contains the file size and the approximate time period provided.

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/logs_archives'

Returns 200 OK

{
  "next_cursor": "234567",
  "has_more": true,
  "archives": [
    {
      "url": "https://scalingo.io/myfile",
      "size": 98765,
      "from": "Fri Mar 24 14:00:00 +0000 UTC 2017",
      "to": "Sun Mar 26 14:00:00 +0000 UTC 2017"
    },
    { … }
  ]
}

Run a One-off Container

Endpoint used by scalingo run

POST https://$SCALINGO_API_URL/v1/apps/[:app]/run

To run a batch job, or an administrative task, you have to start a one-off container. It is a container you can start for a given task and which will be destroyed after it. It can be any command which will be executed in the environment of your application.

Parameters

  • command (string required): Command line which has to be run (example: “bash”)
  • env (object): Environment variables to inject into the container (additionally to those of your apps)
  • size (string, default "M"): Size of the container (e.g. S, M, etc)
  • detached (boolean, default false): Foreground task by default, set to true if the container has to be run in background.

For one-off started with the parameter detached to false:
You can follow the operation progress by following the Location header, pointing to an operation resource.

Background vs Foreground One-off

By default one-off containers are started as attached command. They will only get started when a terminal interactively connect to it through the one-off endpoint. Once attached, data should be sent to the one-off or from it, otherwise the connection will be automatically closed after 30 minutes and the container stopped. So for long interactive jobs, make sure the process is writing something to stdout or stderr.

If the detached option is set to true, the container starts as a background one-off container. In this case the container is started instantly logs from the job are aggregated to the total logs of the application. You have to make sure this job ends at some point.

Limit

There is a hard limit of 10 containers per application and 50 per account as stated in our documentation. If you need more: contact us

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/example-app/run' -d \
  '{
    "command": "bundle exec rails console",
    "env": {
      "VAR1": "VAL1"
    },
    "size": "L"
  }'

Returns 200 OK

{
  "container": {
    "id" : "5250424112dba4edf0000024",
    "type" : "one-off",
    "type_index" : 1,
    "created_at" : "2015-02-17T22:10:32.692+01:00",
    "memory" : 5.36870912e+08,
    "state" : "booting",
    "app" : { "name": "example-app", ... }
  },
  "attach_url": "http://run-1.scalingo.com:5000/f15d8c7fb4170c4ef14b63b2b265c8fa3dbf4a5882de19682a21f6243ae332c6"
}

Stop a Container

Endpoint used by scalingo one-off-stop.

POST https://$SCALINGO_API_URL/v1/apps/[:app]/containers/[:container_id]/stop

Asynchronously stops a running container. Only one-off containers can be stopped that way.

You may have started a one-off container in background. This is also called a detached one-off. This endpoint will trigger an asynchronous stop of the one-off container. The container state becomes stopping after it returns but the container is not instantly stopped. It follows the standard container shutdown lifecycle

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/example-app/containers/6054bcc56d80de00682f7a18/stop'

Returns 202 Accepted

Send Signal to a Container

Endpoint used by scalingo send-signal.

POST https://$SCALINGO_API_URL/v1/apps/[:app]/containers/[:container_id]/kill

Allow to send signals to a running container.

Parameters

  • signal: Accepted signals are SIGUSR1 and SIGUSR2

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/example-app/containers/6054bcc56d80de00682f7a18/kill' -d \
  '{
    "signal": "SIGUSR1"
  }'

Returns 204 No Content

Create a Child Application

POST https://$SCALINGO_API_URL/v1/apps/[:parent_app_name]/child_apps

Create a child application based on the provided parent application.

Parameters

  • app.name: Name of the created child application. Should have between 6 and 32 lower case alphanumerical characters and hyphens, it can’t have an hyphen at the beginning or at the end, nor two hyphens in a row.

Example

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

Returns 201 Created

{
  "app": {
    "created_at":"2017-03-10T18:20:39.454+01:00",
    "git_url":"git@scalingo.com:example-child-app.git",
    "id":"58c2d99563b9fe00019298e2",
    "name":"example-child-app",
    "parent_app_name": "example-parent-app",
    "owner": {
      "username":"john",
      "email":"user@example.com",
      "id":"58bb138d97183e0001f90e1a",
    },
    "updated_at":"2017-03-10T18:20:39.458+01:00",
    "url":"https://example-child-app.scalingo.io",
    "links": {
      "deployments_stream":"wss://deployments.scalingo.com/apps/example-child-app"
    },
    "status":"new",
    "last_deployed_at":null,
    "last_deployed_by":null,
    "git_source":null,
    "flags":{},
    "limits":{}
  }
}

List Child Apps of an Application

This endpoint let you list the different child apps of an application

This endpoint supports pagination.

Example

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/apps/example-parent-app/child_apps

Returns 201 Created

{
  "child_apps": [
    {
      "created_at":"2017-03-10T18:20:39.454+01:00",
      "id":"58c2d99563b9fe00019298e2",
      "name":"example-child-app-1",
      "parent_app_name": "example-parent-app",
      ...
    }, {
      "created_at":"2017-03-10T18:20:39.454+01:00",
      "id":"58c2d99563b9fe00019298e3",
      "name":"example-child-app-2",
      "parent_app_name": "example-parent-app",
      ...
    }
  ]
}

The recommended value endpoint let you get the value we recommend to use for the autoscaling.

GET https://$SCALINGO_API_URL/v1/stats/:metrics/recommended_value

The metrics are aggregated by container types. If a type have more than one container and the container index is not passed, it returns the mean value of all the containers of the same type. The explanation about this value is in the documentation.

The metrics available are:

  • cpu
  • memory
  • swap
  • 5XX: amount of request which returns a 5XX HTTP status code, indicating a server error
  • all: requests per minute (RPM)
  • rpm_per_container: RPM per container
  • p95_response_time: 95th percentile of the requests response time

Parameters

When querying a metric about resource consumption (CPU, memory and swap), one must also provide the name of the container type of interest:

  • container_type: e.g. web, clock

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/stats/cpu/recommended_value?container_type=web

Returns 200 OK

{
	"time": "2018-05-24T00:00:00Z",
	"value": 0.9
}

Get Metrics Data of an Application

The stats endpoint lets you get metrics about the containers of an application. These data include the CPU usage and the memory usage, split between RAM and Swap memory. But also the number of request per minute handled by your app.

GET https://$SCALINGO_API_URL/v1/stats/:metrics(/:container)(/:index)

The metrics are aggregated by container types. If a type have more than one container and the container index is not passed, it will return the mean value of all the containers of the same type.

The metrics available are:

  • cpu
  • memory
  • swap
  • router

If the metrics type is router the container and index parameters are ignored. But you can pass a status_code get variable which filters router metrics by their status code.

Possible values are:

  • 1XX
  • 2XX
  • 3XX
  • 4XX
  • 5XX
  • all

Parameters

  • since: Viewing period in hour

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/stats/cpu/web/1?since=48

Returns 200 OK

[{
	"time":"2016-07-26T15:34:00Z",
	"value":5.925774222222222e+06
}, {
	"time":"2016-07-26T15:48:00Z",
	"value":6.561060571428572e+06
}, {
	"time":"2016-07-26T16:02:00Z",
	"value":7.012790857142857e+06
}, {
	"time":"2016-07-26T16:16:00Z",
	"value":7.579428571428572e+06
}, ...
]

Get Real Time Stats of an Application

To get real time metrics, you can use the following endpoint:

GET https://$SCALINGO_API_URL/v1/apps/[:app]/stats

Return the list of all stats for each container of the application.

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/stats

Returns 200 OK

{
  "stats" : [
    {
      "id" : "web-1",
      "cpu_usage" : 0,
      "memory_usage" : 200105984,
      "memory_limit" : 536870912,
      "highest_memory_usage" : 203440128,
      "swap_usage" : 212992,
      "swap_limit" : 1610612736,
      "highest_swap_usage" : 0
    },{
      "id" : "web-2",
      "cpu_usage" : 0,
      "memory_usage" : 203722752,
      "memory_limit" : 536870912,
      "highest_memory_usage" : 204136448,
      "swap_usage" : 0,
      "swap_limit" : 1610612736,
      "highest_swap_usage" : 0
    },{
      "id" : "worker-1",
      "cpu_usage" : 0,
      "memory_usage" : 210239488,
      "memory_limit" : 536870912,
      "highest_memory_usage" : 229318656,
      "swap_usage" : 0,
      "swap_limit" : 1610612736,
      "highest_swap_usage" : 0
    }
  ]
}