Platform.sh Rest API (1.0)

Introduction

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.

Using the REST API

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.

Authentication

OAuth2

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.

Getting an Access Token

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

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

_embedded Objects

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

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.

Note:

To list projects or to create a new project, use /subscriptions.

Clear project build cache

On rare occasions, a project's build cache can become corrupted. This endpoint will entirely flush the project's build cache. More information on clearing the build cache can be found in our user documentation.

Authorizations:
path Parameters
projectId
required
string

Responses

default
post/projects/{projectId}/clear_build_cache

The Platform.sh API gateway

{schemes}://api.platform.sh/projects/{projectId}/clear_build_cache

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "status": "string",
  • "code": 0
}

Delete a project

Delete a project from the platform

Authorizations:
path Parameters
projectId
required
string

Responses

default
delete/projects/{projectId}

The Platform.sh API gateway

{schemes}://api.platform.sh/projects/{projectId}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "status": "string",
  • "code": 0
}

Update a project's info

Update the details about an existing project