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

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.

Get list of projects

Retrieve list of projects associated with account

Responses

default
get /projects

The Platform.sh API gateway

//projects

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created_at": "2019-07-09T22:37:05Z",
  • "updated_at": "2019-07-09T22:37:05Z",
  • "attributes":
    {
    },
  • "title": "string",
  • "description": "string",
  • "region": "string",
  • "subscription":
    {
    },
  • "repository":
    {
    },
  • "owner": "string",
  • "default_domain": "string",
  • "status":
    {
    }
}

Create a new project

Create an empty project on the platform

Request Body schema: application/json
title
required
string (Title)
region
required
string (Region)
attributes
object (Arbitrary attributes attached to this resource)
Default: null
description
string (Description)
Default: null
default_domain
string (Default domain)
Default: null

Responses

default
post /projects

The Platform.sh API gateway

//projects

Request samples

application/json
Copy
Expand all Collapse all
{
  • "attributes": null,
  • "title": "string",
  • "description": null,
  • "region": "string",
  • "default_domain": null
}

Response samples

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

Get a project's info

Retrieve the details about an existing project

path Parameters
projectId
required
string

Responses

default
get /projects/{projectId}

The Platform.sh API gateway

//projects/{projectId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created_at": "2019-07-09T22:37:06Z",
  • "updated_at": "2019-07-09T22:37:06Z",
  • "attributes":
    {
    },
  • "title": "string",
  • "description": "string",
  • "region": "string",
  • "subscription":
    {
    },
  • "repository":
    {
    },
  • "owner": "string",
  • "default_domain": "string",
  • "status":
    {
    }
}

Update a project's info

Update the details about an existing project

path Parameters
projectId
required
string
Request Body schema: application/json
attributes
object (Arbitrary attributes attached to this resource)
title
string (Title)
description
string (Description)
region
string (Region)
default_domain
string (Default domain)

Responses

default
patch /projects/{projectId}

The Platform.sh API gateway

//projects/{projectId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "attributes":
    {
    },
  • "title": "string",
  • "description": "string",
  • "region": "string",
  • "default_domain": "string"
}

Response samples

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

Delete a project

Delete a project from the platform

path Parameters
projectId
required
string

Responses

default
delete /projects/{projectId}

The Platform.sh API gateway

//projects/{projectId}

Response samples

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

Get a project's capabilities

Get a list of capabilities on a project, as defined by the billing system. For instance, one special capability that could be defined on a project is large development environments.

path Parameters
projectId
required
string

Responses

default
get /projects/{projectId}/capabilities

The Platform.sh API gateway

//projects/{projectId}/capabilities

Response samples

application/json
Copy
Expand all Collapse all
{ }

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.

path Parameters
projectId
required
string

Responses

default
post /projects/{projectId}/clear_build_cache

The Platform.sh API gateway

//projects/{projectId}/clear_build_cache

Response samples

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

Domain Management

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.

Get list of project domains

Retrieve a list of objects representing the user-specified domains associated with a project. Note that this does not return the domains automatically assigned to a project that appear under "Access site" on the user interface.

path Parameters
projectId
required
string

Responses

default
get /projects/{projectId}/domains

The Platform.sh API gateway

//projects/{projectId}/domains

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created_at": "2019-07-09T22:37:06Z",
  • "updated_at": "2019-07-09T22:37:06Z",
  • "project": "string",
  • "name": "string",
  • "attributes":
    {
    },
  • "ssl":
    {
    }
}

Add a project domain

Add a single domain to a project. If the ssl field is left blank without an object containing a PEM-encoded SSL certificate, a certificate will be provisioned for you via Let's Encrypt.

path Parameters
projectId
required
string
Request Body schema: application/json
name
required
string (Domain name)
attributes
object (Arbitrary attributes attached to this resource)
Default: null
ssl
object (The SSL information for the domain.)

Responses

default
post /projects/{projectId}/domains

The Platform.sh API gateway

//projects/{projectId}/domains

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "string",
  • "attributes": null,
  • "ssl":
    {
    }
}

Response samples

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

Get a project domain

Retrieve information about a single user-specified domain associated with a project.

path Parameters
projectId
required
string
domainId
required
string

Responses

default
get /projects/{projectId}/domains/{domainId}

The Platform.sh API gateway

//projects/{projectId}/domains/{domainId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created_at": "2019-07-09T22:37:06Z",
  • "updated_at": "2019-07-09T22:37:06Z",
  • "project": "string",
  • "name": "string",
  • "attributes":
    {
    },
  • "ssl":
    {
    }
}

Update a project domain

Update the information associated with a single user-specified domain associated with a project.

path Parameters
projectId
required
string
domainId
required
string
Request Body schema: application/json
attributes
object (Arbitrary attributes attached to this resource)
ssl
object (The SSL information for the domain.)

Responses

default
patch /projects/{projectId}/domains/{domainId}

The Platform.sh API gateway

//projects/{projectId}/domains/{domainId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "attributes":
    {
    },
  • "ssl":
    {
    }
}

Response samples

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

Delete a project domain

Delete a single user-specified domain associated with a project.

path Parameters
projectId
required
string
domainId
required
string

Responses

default
delete /projects/{projectId}/domains/{domainId}

The Platform.sh API gateway

//projects/{projectId}/domains/{domainId}

Response samples

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

Cert Management

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.

Get list of SSL certificates

Retrieve a list of objects representing the SSL certificates associated with a project.

path Parameters
projectId
required
string

Responses

default
get /projects/{projectId}/certificates

The Platform.sh API gateway

//projects/{projectId}/certificates

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created_at": "2019-07-09T22:37:06Z",
  • "updated_at": "2019-07-09T22:37:06Z",
  • "certificate": "string",
  • "chain":
    [
    ],
  • "is_provisioned": true,
  • "domains":
    [
    ],
  • "issuer":
    [
    ],
  • "expires_at": "2019-07-09T22:37:06Z"
}

Add an SSL certificate

Add a single SSL certificate to a project.

path Parameters
projectId
required
string
Request Body schema: application/json
certificate
required
string (The PEM-encoded certificate)
key
required
string (The PEM-encoded private key)
chain
Array of strings (Certificate chain)
Default: null

Responses

default
post /projects/{projectId}/certificates

The Platform.sh API gateway

//projects/{projectId}/certificates

Request samples

application/json
Copy
Expand all Collapse all
{
  • "certificate": "string",
  • "key": "string",
  • "chain": null
}

Response samples

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

Get an SSL certificate

Retrieve information about a single SSL certificate associated with a project.

path Parameters
projectId
required
string
certificateId
required
string

Responses

default
get /projects/{projectId}/certificates/{certificateId}

The Platform.sh API gateway

//projects/{projectId}/certificates/{certificateId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "created_at": "2019-07-09T22:37:06Z",
  • "updated_at": "2019-07-09T22:37:06Z",
  • "certificate": "string",
  • "chain":
    [
    ],
  • "is_provisioned": true,
  • "domains":
    [
    ],
  • "issuer":
    [
    ],
  • "expires_at": "2019-07-09T22:37:06Z"
}

Update an SSL certificate

Update a single SSL certificate associated with a project.

path Parameters
projectId
required
string
certificateId
required
string
Request Body schema: application/json
certificate
string (The PEM-encoded certificate)
chain
Array of strings (Certificate chain)

Responses

default
patch /projects/{projectId}/certificates/{certificateId}

The Platform.sh API gateway

//projects/{projectId}/certificates/{certificateId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "certificate": "string",
  • "chain":
    [
    ]
}

Response samples

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

Delete an SSL certificate

Delete a single SSL certificate associated with a project.

path Parameters
projectId
required
string
certificateId
required
string

Responses

default
delete /projects/{projectId}/certificates/{certificateId}

The Platform.sh API gateway

//projects/{projectId}/certificates/{certificateId}

Response samples

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

Project Variables

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.

Get list of project variables