Platform.sh is a container-based Platform-as-a-Service. Our main API is simply Git. With a single git push and a couple of YAML files in your repository you can deploy an arbitrarily complex cluster. Every Project can have multiple applications (PHP, Node.js, Python, Ruby, Go, etc.) and managed, automatically provisioned services (databases, message queues, etc.).

Each project also comes with multiple concurrent live staging/development Environments. These ephemeral development environments are automatically created every time you push a new branch or create a pull request, and each has a full copy of the data of its parent branch, which is created on-the-fly in seconds.

Our Git implementation supports integrations with third party Git providers such as GitHub, Bitbucket, or GitLab, allowing you to simply integrate Platform.sh into your existing workflow.

In addition to the Git API, we also offer a REST API that allows you to manage every aspect of the platform, from managing projects and environments, to accessing accounts and subscriptions, to creating robust workflows and integrations with your CI systems and internal services.

These API docs are generated from a standard OpenAPI (Swagger) Specification document which you can find here in YAML and in JSON formats.

This RESTful API consumes and produces HAL-style JSON over HTTPS, and any REST library can be used to access it. On GitHub, we also host a few API libraries that you can use to make API access easier, such as our PHP API client and our JavaScript API client.

In order to use the API you will first need to have a Platform.sh account (we have a free trial available) and create an API Token.

API authentication is done with OAuth2 access tokens.

API tokens

You can use an API token as one way to get an OAuth2 access token. This is particularly useful in scripts, e.g. for CI pipelines.

To create an API token, go to the "API Tokens" section of the "Account Settings" tab on the Console.

To exchange this API token for an access token, a POST request must be made to https://auth.api.platform.sh/oauth2/token.

The request will look like this in cURL:

curl -u platform-api-user: \
    -d 'grant_type=api_token&api_token=API_TOKEN' \
    https://auth.api.platform.sh/oauth2/token

This will return a "Bearer" access token that can be used to authenticate further API requests, for example:

{
    "access_token": "abcdefghij1234567890",
    "expires_in": 900,
    "token_type": "bearer"
}

Using the Access Token

To authenticate further API requests, include this returned bearer token in the Authorization header. For example, to retrieve a list of Projects accessible by the current user, you can make the following request (substituting the dummy token for your own):

curl -H "Authorization: Bearer abcdefghij1234567890" \
    https://api.platform.sh/projects

Most endpoints in the API return fields which defines a HAL (Hypertext Application Language) schema for the requested endpoint. The particular objects returns and their contents can vary by endpoint. The payload examples we give here for the requests do not show these elements. These links can allow you to create a fully dynamic API client that does not need to hardcode any method or schema.

Unless they are used for pagination we do not show the HAL links in the payload examples in this documentation for brevity and as their content is contextual (based on the permissions of the user).

Most endpoints that respond to GET requests will include a _links object in their response. The _links object contains a key-object pair labelled self, which defines two further key-value pairs:

• href - A URL string referring to the fully qualified name of the returned object. For many endpoints, this will be the direct link to the API endpoint on the region gateway, rather than on the general API gateway. This means it may reference a host of, for example, eu-2.platform.sh rather than api.platform.sh.
• meta - An object defining the OpenAPI Specification (OAS) schema object of the component returned by the endpoint.

There may be zero or more other fields in the _links object resembling fragment identifiers beginning with a hash mark, e.g. #edit or #delete. Each of these keys refers to a JSON object containing two key-value pairs:

• href - A URL string referring to the path name of endpoint which can perform the action named in the key.
• meta - An object defining the OAS schema of the endpoint. This consists of a key-value pair, with the key defining an HTTP method and the value defining the operation object of the endpoint.

To use one of these HAL links, you must send a new request to the URL defined in the href field which contains a body defined the schema object in the meta field.

For example, if you make a request such as GET /projects/abcdefghij1234567890, the _links object in the returned response will include the key #delete. That object will look something like this fragment:

"#delete": {
    "href": "/api/projects/abcdefghij1234567890",
    "meta": {
        "delete": {
            "responses": {
                . . . // Response definition omitted for space
            },
            "parameters": []
        }
    }
}

To use this information to delete a project, you would then send a DELETE request to the endpoint https://api.platform.sh/api/projects/abcdefghij1234567890 with no body or parameters to delete the project that was originally requested.

Requests to endpoints which create or modify objects, such as POST, PATCH, or DELETE requests, will include an _embedded key in their response. The object represented by this key will contain the created or modified object. This object is identical to what would be returned by a subsequent GET request for the object referred to by the endpoint.