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. After you get an API token, you can exchange it for an access token.

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

To exchange this API token for an access token, a POST request must be made to https://accounts.platform.sh/oauth2/token. The request has one required header: Content-Type: application/json

The API token is sent to the authorization endpoint in the body of the request:

{
    "client_id": "platform-api-user",
    "grant_type": "api_token",
    "api_token": "API_TOKEN"
}

Note that the client_id and the grant_type fields are both required in addition to the api_token.

In practice, requesting an access token with cURL will look like this:

curl -X POST \
    -H 'Content-Type: application/json' \
    -d '{
        "client_id": "platform-api-user",
        "grant_type": "api_token",
        "api_token": "API_TOKEN"
    }' \
    https://accounts.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": 3600,
    "token_type": "Bearer",
    "scope": "account"
}

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 -X GET \
    -H "Authorization: Bearer abcdefghij1234567890" \
    -H "Content-Type: application/json" \
    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.

Project Overview

On Platform.sh, a Project is backed by a single Git repository and encompasses your entire application stack, the services used by your application, the application's data storage, the production and staging environments, and the backups of those environments.

When you create a new project, you start with a single Environment called Master, corresponding to the master branch in the Git repository of the project—this will be your production environment.

If you connect your project to an external Git repo using one of our Third-Party Integrations a new development environment can be created for each branch or pull request created in the repository. When a new development environment is created, the production environment's data will be cloned on-the-fly, giving you an isolated, production-ready test environment.

This set of API endpoints can be used to retrieve a list of projects associated with an API key, as well as create and update the parameters of existing projects.

These endpoints can be used to add, modify, or remove domains from a project. For more information on how domains function on Platform.sh, see the Domains section of our documentation.

User-supplied SSL/TLS certificates can be managed using these endpoints. For more information, see our Third-party TLS certificate documentation. These endpoints are not for managing certificates that are automatically supplied by Platform.sh via Let's Encrypt.

These endpoints manipulate user-defined variables which are bound to an entire project. These variables are accessible to all environments within a single project, and they can be made available at both build time and runtime. For more information on project variables, see the Variables section of the documentation.